Integrating
Your game talks to the platform by posting messages to the window that embeds it. The SDK formats those messages, targets the right origin and turns replies into promises. Use it unless you have a reason not to; the raw protocol is at the end of this page.
With the SDK and without it
The SDK is optional. A game without it is reviewed, listed and playable like any other. It just has nothing to send the platform, so the features that need your game's input are missing.
| Feature | With the SDK | Without it |
|---|---|---|
| Listing and play | Yes | Yes |
| Scores and leaderboard | Yes, for signed-in players | No. Nothing is submitted, so the leaderboard stays empty. |
| Achievements | Your game unlocks manual ones; the platform awards the rest | Only play_count ones. Nothing unlocks a manual or score_threshold achievement. |
| Cloud saves | Yes, for signed-in players | No. Use your own storage, which stays on that browser. |
| Who is playing, and when your frame is hidden | Yes: gm-session and gm-visibility | No |
The SDK is only a convenience. A game that speaks the protocol directly gets the same as one that loads it. Start with scores: one script tag and one call per run.
The SDK
Load it before your game code. Every game origin serves it at /_gm/sdk.js; your local dev server does not. To pin a version, copy the file into your ZIP: it is plain JavaScript with no dependencies.
<script src="/_gm/sdk.js"></script>
<script type="module" src="js/main.js"></script>It attaches one global, GM. Guard every call with if (window.GM) so your game behaves the same when the script did not load. The game must also be complete without scores or achievements: a signed-out player, a local build with GM absent and a call that resolves TIMEOUT should all end in a finished game. Record a reply; never make a state change wait for one.
| Call | What you get back |
|---|---|
GM.submitScore(score, metadata?) | A promise for the platform's gm-ack. It never rejects: with no reply in ten seconds it resolves code: 'TIMEOUT'. |
GM.unlockAchievement(slug) | Same reply shape. The achievement's ULID also works in place of the slug. |
GM.getLeaderboard() | A promise for { ok, code?, top, you }. See gm-leaderboard. |
GM.saveGame(data) | A promise for the gm-ack of a save, with version and overwrote on success. It waits up to 30 seconds. See Saves. |
GM.loadGame() | A promise for { ok, code?, signedIn, save }. See Saves. |
GM.getSession() | The last gm-session payload, or null before the first arrives. |
GM.onSession(cb) | Calls cb with { signedIn, preview } on every gm-session, and at once if one is already known. |
GM.onVisibility(cb) | Calls cb with a boolean: once when your frame finishes loading (false behind the pre-play ad, otherwise true) and with true when the ad closes. Earlier values are not replayed: register at startup. |
GM.isEmbedded() | true when your game runs inside any iframe. |
// Submit a score once per run, when the run ends. The promise resolves
// with the platform's reply; it never rejects.
if (window.GM) {
GM.submitScore(12500, { level: 3 }).then((ack) => {
if (ack.ok) showToast('Score saved');
else if (ack.code === 'UNAUTHENTICATED') showToast('Sign in to save your score');
else showToast('Score not counted');
});
}
// Unlock an achievement by its slug. Same reply shape as submitScore.
if (window.GM) {
GM.unlockAchievement('first-boss');
}
// Who is playing? Called once your frame has loaded, or at once if that has
// already happened. It does not change mid-run: signing in reloads the page.
if (window.GM) {
GM.onSession((session) => {
if (!session.signedIn) showSignInHint();
if (session.preview) enableDebugOverlay();
});
}
// Whether your frame is on screen. The callback is given a BOOLEAN, not an
// object. First call: when your frame finishes loading, false behind the
// pre-play ad and true otherwise. Register it at startup: it is not replayed.
if (window.GM) {
GM.onVisibility((visible) => {
visible ? resume() : pause();
});
}Scores
- The player must be signed in. A signed-out submission stores nothing and the reply is
ok: falsewithUNAUTHENTICATED. Readgm-sessionon load and ask for sign-in before a run starts: signing in reloads your game, and a run interrupted to sign in is lost. scoreis an integer of 0 or more. A float or a negative number is rejected withVALIDATION_ERROR.- Set a maximum score on the game's Scores tab to keep impossible scores off your leaderboard. A score above it is refused with
SCORE_ABOVE_MAXIMUMand not stored; a score equal to it is accepted. It takes effect at once, with no review. Scores already stored stay on the leaderboard even if they are above a new maximum: an admin can hide them. With no maximum set, any integer is accepted. metadatais optional: a flat object of strings, numbers or booleans, at most 20 keys, keys up to 32 characters, string values up to 256 characters, and at most 4096 characters as JSON. A nested object, or anything over a limit, rejects the whole submission.- Submit once per run, when the run ends, behind a flag so a game loop cannot fire it twice. Scores sent too fast are refused with
RATE_LIMITEDand not stored. If a run can be very short, submit only when the player beats their own best: the leaderboard keeps only each player's best. - The reply does not say whether the score was a personal best, and a tie does not replace the best. Track the player's best score in your game to celebrate it.
- Test your scoring loop in Preview. A score submitted from your owner-only Preview page is acknowledged like a live one and is not recorded, so your leaderboard stays clean.
Creating an achievement
Achievements are defined on the platform and unlocked from your game. Create each one on the game's Achievements tab before your game names it. The badge image is in the artwork table on the Publishing page.
- Up to 10 per game. Retiring one frees a slot, but its slug stays reserved forever: you cannot retire
first-bloodand then create a newfirst-blood. - Each has a slug, derived from the title or supplied by you. Editing the title never changes it, so it is safe to hard-code. A slug already taken on that game is reported when you save. Slugs are unique within your game only.
| Trigger | Value | Who awards it |
|---|---|---|
| My game decides | manual | Your game, by sending an unlock. The only type your game can unlock. |
| Score reaches a value | score_threshold | The platform, from submitted scores. |
| Number of plays | play_count | The platform, from play data. |
An unlock naming a score_threshold or play_count achievement is refused like an unknown slug.
Testing it, and getting it published
- A new achievement is a private draft. Only its creator or the game's owner can unlock it, and that unlock records nothing: it returns the full reply so you can confirm the slug resolves and the toast shows.
- Test before your game is approved in Preview. It is owner-only, opens your build at any status, shows the toast a player sees and records no play.
gm-sessionarrives withpreview: true. Unlocking an already published achievement from Preview is recorded on your own profile. - Game not approved yet: its draft achievements go live in the same step as the game. One you already submitted for review keeps waiting in the queue.
- Game approved for a release date: the drafts that existed at approval go live at the release. One you add or change afterwards needs its own review: press Submit for review on it. Until it is approved it stays a draft.
- Game already live: press Submit for review on the achievement. Players can earn it once it is approved, and the game stays live. No email is sent either way: check the Achievements tab.
- Rejected is not lost. A returned achievement goes back to draft with everything intact. Change what you need and submit again.
- Retiring is the only way to withdraw one, and it is permanent. Players who earned it keep the badge; nobody new can earn it. There is no delete.
- What you can edit. Title, description and badge, always. While it is a draft or in review, everything, including the slug and the trigger. Once it is published the slug is frozen; once any player holds it the trigger type is frozen and a threshold can only be raised.
Unlocking one from your game
- Name the achievement by its slug. Its ULID is also accepted, for achievements created before slugs existed.
- The player must be signed in. A signed-out player earns nothing and the reply is
ok: falsewithUNAUTHENTICATED. Design the achievement so the game still plays correctly without it. - The player must have started the game recently. The platform records that when the player presses Play; your game does nothing to create it.
- Fire an unlock when its condition is met, never on a timer or from a render loop. Too many attempts are answered
RATE_LIMITED, and repeats of an achievement the player already holds count. Back off. - Sending the same unlock twice is safe. The reply is
ok: truewith nothing new written, and the toast is not shown again. - An unlock that comes back
NOT_FOUNDhas several possible causes. See Troubleshooting.
Saves
Your game can keep one save per signed-in player on Gamemoor, so it follows the player to any device and survives cleared browser storage. It is free for every signed-in player.
- One save per game, as a string.
GM.saveGame(data)replaces the last one. Gamemoor stores the string as you sent it and never reads it, so serialise it yourself. A value that is not a string is refused withVALIDATION_ERROR. - At most 64 KB per save and 2 MB per player across every game, counted as UTF-8 bytes. Over either, the save is refused and the stored one is kept:
SAVE_TOO_LARGEorSAVE_QUOTA_EXCEEDED. - Signed-out players have no Gamemoor save.
GM.loadGame()answerssignedIn: falseandGM.saveGame()answersUNAUTHENTICATED. Keep saving tolocalStoragefor them. - Save whenever the state changes. The player page sends at most one save every 10 seconds, the latest copy, and sends a waiting copy at once when the page is hidden or closed. A call's ack comes when the save carrying its copy is stored, so it can take 10 seconds. A copy near the size limit may be lost if the page closes before it is sent.
GM.loadGame()returns the copy you saved last, even before it is sent, withupdatedAt: null.- The last save wins. Each stored save gets the next
version. When a save replaced one your page had not seen (the player saved on another device in between), its ack saysoverwrote: true. Load before you save to avoid that; merging two saves is up to your game. - Saves work on a live game, in a scheduled game's Club window for Club members, and on your own Preview page, where they go to your own save.
// On start: the player's save, if they have one.
if (window.GM) {
GM.loadGame().then((reply) => {
if (!reply.signedIn) return startFrom(loadFromLocalStorage()); // a guest: no server save
startFrom(reply.save ? JSON.parse(reply.save.data) : null); // save is null when there is none yet
});
}
// Whenever the state changes. Call it as often as you like.
if (window.GM) {
GM.saveGame(JSON.stringify(state)).then((ack) => {
if (ack.overwrote) showToast('Replaced a save from another device');
if (ack.code === 'UNAUTHENTICATED') saveToLocalStorage(state);
});
}Protocol reference
This is what the SDK does underneath. Every message in either direction has the same envelope: gm exactly true and version exactly 1, or the message is discarded without a reply. So is a message of an unknown type. A known score, unlock or save type with a bad payload is answered with VALIDATION_ERROR.
- Post to
window.parentwith target originhttps://gamemoor.com: the page your game is embedded in, not where it is served from. - The protocol works only for builds you upload, served from your game's own origin. A game hosted elsewhere gets silence in both directions.
- Any message may carry a
requestId: a non-empty string of at most 64 characters. Onlygm-ack,gm-leaderboardandgm-saveecho it. An invalid one is not an error: the message is still acted on and the reply comes back without one.
| Message you send | Payload | Reply |
|---|---|---|
gm-score-submit | { score, metadata?, requestId? } | gm-ack |
gm-achievement-unlock | { id, requestId? }, where id is the slug or the achievement's ULID | gm-ack |
gm-session-request | none | gm-session |
gm-leaderboard-request | { requestId? } | gm-leaderboard |
gm-save-write | { data, requestId? }, where data is a string | gm-ack |
gm-save-request | { requestId? } | gm-save |
// Every message has this envelope. Post it to the window that embeds you.
window.parent.postMessage({
gm: true, // required, exactly true
version: 1, // required, exactly 1
type: 'gm-score-submit',
payload: {
score: 12500, // integer, 0 or more
metadata: { level: 3 }, // optional, flat, string | number | boolean
requestId: 'run-42' // optional, echoed back on the reply
}
}, 'https://gamemoor.com'); // the PARENT window's origin, not where your game is served
// An unlock is the same envelope, with the slug in `id`.
// type: 'gm-achievement-unlock', payload: { id: 'first-blood', requestId: 'boss-1' }gm-session: who is playing
- Sent when your frame finishes loading, and again whenever you post
gm-session-request. Payload:{ signedIn: boolean, preview: boolean }. - It always arrives on Gamemoor. If none has arrived a couple of seconds after your load event, your game is not running in the Gamemoor player, or your listener checks the wrong origin: treat the player as signed out.
- It is not re-sent when the player signs in during play. Signing in returns to your game's page, which loads your game again with
signedIn: true. Anything the interrupted run had not saved is gone. signedInis all you learn about the player: never a name, an id or a tier.previewistrueonly on your own Preview page. Use it for a debug overlay and nothing else. Your game must behave the same wherever it runs: a build that plays differently depending on who it thinks is watching can be removed.
gm-ack: did it land
- One reply per
gm-score-submit,gm-achievement-unlockorgm-save-write. Payload:{ for, ok, code?, requestId? }, wherefornames the message being answered. A stored save addsversionandoverwrote. ok: truemeans the platform accepted it, not always that something was written: unlocking a badge the player already holds, and unlocking your own unpublished achievement, answerok: truehaving stored nothing.ok: falsecarries exactly onecode:
| Code | Meaning |
|---|---|
UNAUTHENTICATED | The player is not signed in. Scores, unlocks and saves all need a session. |
VALIDATION_ERROR | The message or its payload is malformed: a non-integer score, a missing or over-long slug, metadata over a limit. Nothing else gets this code. |
RATE_LIMITED | Too many requests. Nothing was stored. Back off; do not retry in a loop. |
SCORE_ABOVE_MAXIMUM | The score is above the maximum set on your game's Scores tab. Nothing was stored. Do not retry the same score. |
NOT_FOUND | An unlock did not resolve, for one of several reasons (see Troubleshooting). For a save: the game does not take saves where it is running. |
SAVE_TOO_LARGE | The save is over 64 KB. The stored save is kept. |
SAVE_QUOTA_EXCEEDED | The player's saves across every game would pass 2 MB. The stored save is kept. |
NETWORK_ERROR | The player page got no response from the platform. The request may have arrived, so whether the write landed is unknown. |
INTERNAL_ERROR | The platform failed. It does not prove nothing was stored: treat a resubmitted score as a second score, because that is what it is. |
TIMEOUT | SDK only. No reply within ten seconds, or 30 for a save. |
NOT_EMBEDDED | SDK only. Your game is not running inside an iframe at all. |
gm-visibility: is my frame on screen
- Payload:
{ visible: boolean }. Always sent when your frame finishes loading, with the starting state. Behind a pre-play ad your frame getsvisible: false, thenvisible: truewhen the ad closes. With no ad it getsvisible: trueat once. - You may wait for
visible: truebefore starting your game. Off Gamemoor nothing is sent, so if nothing has arrived a couple of seconds after load, start anyway. - Treat it as a state, not an event: the same value can arrive twice. Add your listener while the page loads: a message sent before you listen is not sent again.
- A hidden tab or a minimised window is not reported here. Handle the document's
visibilitychangeevent as well.
gm-leaderboard: the top ten, and where the player stands
- The reply to
gm-leaderboard-request. Payload:{ ok, code?, requestId?, top, you }. With the SDK, callGM.getLeaderboard(). topis the public top ten, best first, as{ rank, name, score }: the list your game's page shows. Equal scores rank by who set them first.youis the player's own best as{ rank, score }. It isnullfor a guest and for a player with no score in your game yet, never a zero: draw no rank when it isnull.- Nothing in it identifies the player, and it holds nothing about anyone else beyond the public page.
- Ask when you need it, for example on your game-over screen after the score's
gm-ack. A request within 5 seconds of the last answer gets that same answer again, not an error.
gm-save: the player's save
- The reply to
gm-save-request. Payload:{ ok, code?, requestId?, signedIn, save }. With the SDK, callGM.loadGame(). - Three answers, none of them empty:
signedIn: false(a guest, no Gamemoor save),save: null(no save yet), orsaveas{ data, version, updatedAt }. - A save is written with
gm-save-writeand answered with agm-ack. See Saves.
window.addEventListener('message', (event) => {
// Only the page that embeds you, and only its own window.
if (event.origin !== 'https://gamemoor.com' || event.source !== window.parent) return;
const msg = event.data;
if (!msg || msg.gm !== true || msg.version !== 1) return;
switch (msg.type) {
case 'gm-session': // { signedIn: boolean, preview: boolean }
if (!msg.payload.signedIn) showSignInHint();
break;
case 'gm-ack': // { for, ok, code?, requestId? }
if (msg.payload.for === 'gm-score-submit') onScoreReply(msg.payload);
break;
case 'gm-visibility': // { visible: boolean }, on load and when the ad closes
msg.payload.visible ? resume() : pause();
break;
case 'gm-leaderboard': // { ok, top, you }, you is null for a guest
if (msg.payload.ok && msg.payload.you) showRank(msg.payload.you.rank);
break;
case 'gm-save': // { ok, signedIn, save }, save is null when there is none
if (msg.payload.ok && msg.payload.save) restore(msg.payload.save.data);
break;
}
});