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
| Origin | What it is |
|---|---|
https://gamemoor.com | The page your game is embedded in. You post to it. The SDK accepts replies only from it. |
https://<game id>.gamemoorusercontent.com | Where 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-acknever arrives, check this first. - The SDK hard-codes
https://gamemoor.comas its target and as the onlyevent.originit 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:
// 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.jsresolves 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()andprompt()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.referreris at mosthttps://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/catchand render correctly when storage throws or comes back empty.
// 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 ondocument.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.
| Value | What you are claiming | What the platform does with it |
|---|---|---|
full | Built for touch and for a small screen. | Nothing at runtime. A player reads it before tapping. |
limited | Playable on a phone, but not designed for one. | Nothing at runtime. Identical to full. |
disabled | Not 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:
| What | Allowed from |
|---|---|
| Scripts | Your own origin, inline scripts, eval, WebAssembly and blob: |
| Stylesheets | Your own origin and inline styles |
| Images and media | Your own origin, data: and blob: |
| Fonts | Your own origin and data: |
| Network requests | Your own origin, https://gamemoor.com, data: and blob: |
| Web workers | Your own origin and blob: |
| Nested frames | Your 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.
- Develop locally. Your dev server does not serve
/_gm/sdk.js, sowindow.GMis undefined and guarded calls do nothing. A copy of the SDK inside your build reportsisEmbedded()asfalsewhen the page is opened directly, and every call no-ops. Build and tune the game loop here. - Upload a build. A build that is not live is not served publicly; open it in your preview.
- Test on your preview. The owner-only preview page mounts the real player and sends a real
gm-sessionwithpreview: 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%,100dvwand100dvh, not fixed pixels: the frame is one size on the game page, another on the phone play page, another in fullscreen. Avoid100vhon mobile: it is measured with the browser chrome expanded, so the bottom of your canvas sits under the toolbar. - Handle both visibility signals.
gm-visibilitymeans the platform covered your frame; the browser'svisibilitychangemeans 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.
// 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();
});