Skip to content

Runtime

Your game is a page in a sandboxed frame on Gamemoor. Several browser APIs are off, every request it makes is checked against a Content-Security-Policy, storage belongs to your game but can vanish, and the only channel back to Gamemoor is postMessage.

Two origins, and which one you post to

OriginWhat it is
https://gamemoor.comThe page your game is embedded in. You post to it. The SDK accepts replies only from it.
https://<game id>.gamemoorusercontent.comWhere your files are served from, with the id in lower case.
  • Passing your own origin as the target silently drops every score and unlock. The browser refuses to deliver the message and nothing reports an error. If your gm-ack never arrives, check this first.
  • The SDK hard-codes https://gamemoor.com as its target and as the only event.origin it accepts, so with the SDK neither origin is yours to get wrong.

Where your build lives, and why relative paths are mandatory

Every upload is its own version. A live game serves its active build under its build id, on your game's own origin:

The shape of a build URL
// Where a build is served from: your game's own origin, then the build.
// Both ids are in lower case. The build id changes on every promotion.
https://<game id>.gamemoorusercontent.com/<build id>/index.html

// Resolve everything against that document.
<script src="./game.js"></script>                // loads
<link rel="stylesheet" href="assets/app.css">       // loads

<script src="/game.js"></script>                 // 404: resolves to the origin root
  • Resolve every asset relative to your entry document. A root-relative /assets/game.js resolves to the root of your game's origin, not of your build, and 404s. It is the most common way a build that ran from a local folder ships broken, and inside a frame it fails quietly.
  • Paths are case-sensitive. An unknown path is a 404: there is no fallback to index.html.
  • The build id changes with every promotion. Nothing in your game may hard-code its own absolute URL, and no outside service may key anything to it.
  • The frame's URL carries no query string and no player identity. Who is playing arrives in gm-session.

The frame: what does not work

The public game page, the phone play page and your preview all mount the same player with the same frame attributes. What works in preview works in production.

  • No modal dialogs. alert(), confirm() and prompt() do not run. Draw your own.
  • No pointer lock. requestPointerLock() fails. Use relative mouse movement instead.
  • No downloads. A file exported from inside the frame is blocked.
  • No top-level navigation. Your game cannot navigate the page it is embedded in.
  • No service workers. Registration fails.
  • Forms submit only to your own origin, and only as GET. A POST to the game origin gets 405.
  • window.open() works. The window it opens keeps the frame's sandbox.
  • Camera, microphone, geolocation and the Payment Request API are off. There is no prompt: the call fails.
  • document.referrer is at most https://gamemoor.com/, and you cannot read the address of the page you are embedded in. Do not key anything off either.
  • Audio and video may autoplay as far as the platform is concerned. The browser's user-activation rules still apply, so start sound from a gesture.

Storage is your game's own, and it stays on one device

Your game has an origin of its own, so no other game can read or overwrite its localStorage, IndexedDB or cookies, and every build of the game shares them. Use localStorage for a guest, and as a local copy for everyone. For a signed-in player, a Gamemoor save follows them to any device: see Saves.

  • Version your keys (save:v3) so a new build can tell an old save from its own.
  • Treat it as a best-effort cache, never the only copy. The frame is cross-site, so browsers that partition storage key it to Gamemoor as well as to your origin, and Safari can evict it after a stretch of inactivity.
  • Wrap every read and write in try/catch and render correctly when storage throws or comes back empty.
Saving without assuming storage exists
// Your game's own key space. Survive it being partitioned away, evicted,
// blocked or reset.
const KEY = 'ninja-cats:save:v3';

function save(state) {
  try {
    localStorage.setItem(KEY, JSON.stringify(state));
  } catch {
    // Quota, private mode, blocked storage. The game keeps playing.
  }
}

function load() {
  try {
    return JSON.parse(localStorage.getItem(KEY) ?? 'null');
  } catch {
    return null;
  }
}

Fullscreen

  • The frame is granted fullscreen: document.documentElement.requestFullscreen() works from inside your game. Call it from a user gesture and gate the control on document.fullscreenEnabled.
  • iOS Safari does not implement it for arbitrary elements, which is why phones get a dedicated full-viewport play page. Design the game to play at the frame's own size; fullscreen is the nicer version.

Mobile support

One field on your listing tells a player on a phone whether to bother. Set it honestly.

ValueWhat you are claimingWhat the platform does with it
fullBuilt for touch and for a small screen.Nothing at runtime. A player reads it before tapping.
limitedPlayable on a phone, but not designed for one.Nothing at runtime. Identical to full.
disabledNot playable on a phone.Hides the player on phones and shows a compatibility panel instead.

disabled is a listing signal, not access control. If your game must not run on a small screen, handle that inside the game too.

Frame shape

Set the frame shape on your listing to the one the game is built for: Landscape 16:9, 4:3 or 3:2, Square 1:1, Portrait 9:16, or Any. The platform draws exactly that box, as large as the screen allows, on your game page and full screen on a phone.

  • A fixed shape is letterboxed. Your game always receives the shape it asked for.
  • Any fills the space. Choose it only if your game adapts to every shape.
  • Do not draw your own rotate screen. When a phone is held the other way, the platform shows a note to turn it, outside your frame. A game that blocks play until the phone is rotated can strand the player.

Network: what the game origin allows

Ship a self-contained game. Every response from your game origin carries a Content-Security-Policy, and the browser blocks anything outside it with a console error and nothing else:

WhatAllowed from
ScriptsYour own origin, inline scripts, eval, WebAssembly and blob:
StylesheetsYour own origin and inline styles
Images and mediaYour own origin, data: and blob:
FontsYour own origin and data:
Network requestsYour own origin, https://gamemoor.com, data: and blob:
Web workersYour own origin and blob:
Nested framesYour own origin only
Plugins (object, embed)Nothing
  • Bundle your assets. A CDN script, a Google Fonts link, an analytics snippet, a third-party image or an API call is blocked. Put fonts, audio, sprites and the engine runtime in the ZIP.
  • What you need from Gamemoor (who is playing, scores, achievements, saves) arrives over postMessage. See Integrating.

Testing without a staging environment

There is no staging Gamemoor and no local copy of the parent page.

  1. Develop locally. Your dev server does not serve /_gm/sdk.js, so window.GM is undefined and guarded calls do nothing. A copy of the SDK inside your build reports isEmbedded() as false when the page is opened directly, and every call no-ops. Build and tune the game loop here.
  2. Upload a build. A build that is not live is not served publicly; open it in your preview.
  3. Test on your preview. The owner-only preview page mounts the real player and sends a real gm-session with preview: true. Nothing you do there is recorded: no play, no score, and no unlock for an achievement you have not published.

Best practices while the game runs

  • Get to a first render fast: aim for under two seconds. The frame mounts when the player presses Play (the phone play page mounts it at once), so every second of load is a second of a blank rectangle. Measure from the press. Keep the first bundle small, compress images, and defer what the opening screen does not need.
  • Size against the iframe, not the screen. Use 100%, 100dvw and 100dvh, not fixed pixels: the frame is one size on the game page, another on the phone play page, another in fullscreen. Avoid 100vh on mobile: it is measured with the browser chrome expanded, so the bottom of your canvas sits under the toolbar.
  • Handle both visibility signals. gm-visibility means the platform covered your frame; the browser's visibilitychange means the player switched tab or minimised the window. Neither implies the other, so a game that listens for one keeps playing audio to nobody. See gm-visibility.
Pausing on both visibility signals
// Two signals. Neither one implies the other, so handle both.

// The platform covered your frame, for example with a pre-play ad.
GM.onVisibility(function (visible) {
  if (visible) resume(); else pause();
});

// The player switched tab or minimised the window.
document.addEventListener('visibilitychange', function () {
  if (document.hidden) pause(); else resume();
});