# Gamemoor developer docs

The pages of <https://gamemoor.com/developer/docs> as one file. Links point at the web version.

## Quickstart

A Gamemoor game is a folder of static files that runs in an iframe in the player's browser. Nothing of yours runs on our side.

1. **Build it static.** HTML, JavaScript and assets in one folder, with `index.html` at its root and every internal reference relative.
2. **Add the SDK.** One script tag, before your game code. It is optional: without it the game is listed and playable, with no scores, achievements or saves. See [what each gets](https://gamemoor.com/developer/docs/integrating#sdk-or-not).
3. **Submit a score when a run ends.** One call per run, behind a flag so a game loop cannot fire it twice. See [Scores](https://gamemoor.com/developer/docs/integrating#scores).
4. **Zip it.** Zip the contents of the folder, not the folder, so `index.html` sits at the archive root. The limits are in [Publishing](https://gamemoor.com/developer/docs/publishing#submission-requirements).
5. **Submit the game.** Use [Submit a game](https://gamemoor.com/developer/submit-game) in the portal. We email you when it is approved or rejected.

_index.html: load the SDK, submit one score per run_

```
<!-- index.html, at the root of the folder you zip -->
<script src="/_gm/sdk.js"></script>
<script type="module" src="js/main.js"></script>

<script>
  // Call this once, when a run ends. Never on a timer or every frame.
  function endRun(score) {
    if (!window.GM) return;   // the SDK did not load: the game still plays
    GM.submitScore(score).then((ack) => {
      if (!ack.ok) showScoreNotice(ack.code);
    });
  }
</script>
```

### The docs

| Page | Covers |
| --- | --- |
| [Publishing](https://gamemoor.com/developer/docs/publishing) | What to send, how a game moves from draft to live, builds, and uploading from CI. |
| [Integrating](https://gamemoor.com/developer/docs/integrating) | The SDK and the postMessage protocol: scores, achievements, saves and error codes. |
| [Runtime](https://gamemoor.com/developer/docs/runtime) | What the game frame allows and blocks, and how to build for it. |
| [Troubleshooting](https://gamemoor.com/developer/docs/troubleshooting) | A score, an unlock or an upload that did not work. |
| [Changelog](https://gamemoor.com/developer/docs/changelog) | What changed for developers in the last 90 days, and what is being removed. |

## Publishing

What to send, how a game moves from draft to live, how a new build reaches players, and how to upload from a script.

### The build

A build is a ZIP of static files that runs in the browser; nothing is executed on our side. The uploader checks these rules and refuses a build that breaks one:

- `index.html` sits at the _archive root_, spelled exactly that way. Zip the contents of your folder, not the folder. A zero-byte `index.html` counts as missing.
- The filename ends in `.zip`, in lower case.
- Limits: 30MB compressed, 200MB extracted and 2000 files.
- No entry's path contains `..` or starts with `/`.
- Internal references (images, stylesheets, scripts) are relative. See [Runtime](https://gamemoor.com/developer/docs/runtime#runtime-build-url).
- Nothing your game loads or calls comes from outside the build. See [Runtime](https://gamemoor.com/developer/docs/runtime#runtime-network).
- A file's content type comes from its extension. These are recognised: `.avif, .bmp, .css, .flac, .gif, .glb, .gltf, .htm, .html, .ico, .jpeg, .jpg, .js, .json, .m4a, .map, .mjs, .mp3, .mp4, .ogg, .opus, .otf, .png, .svg, .ttf, .txt, .wasm, .wav, .webm, .webmanifest, .webp, .woff, .woff2, .xml`. Anything else is served as `application/octet-stream`, which a browser downloads instead of running, so a module script or stylesheet with another extension fails to load. Do not ship pre-compressed files (`.br`, `.gz`, `.unityweb`): they are served as stored and will not load.
- Zero-byte files are dropped when the ZIP is extracted. A game that fetches one gets a 404.

### Artwork and screenshots

| Slot | Required | Shape | Minimum | Formats | Max file |
| --- | --- | --- | --- | --- | --- |
| Icon | Yes | 1:1 | 512 × 512 px | JPEG, PNG, WebP | 5MB |
| Thumb | Yes | 16:9 | 640 × 360 px | JPEG, PNG, WebP | 5MB |
| Hero | No | 16:9 | 1920 × 1080 px | JPEG, PNG, WebP | 10MB |
| Screenshots | No, 0 to 5 | Any | 1280 × 720 px | JPEG, PNG, GIF, WebP | 5MB each |
| Achievement badge | One per achievement | 1:1 | 256 × 256 px | JPEG, PNG, WebP | 2MB |

- The minimum applies to each side, not to the pixel count. A 1080 × 1920 px portrait image is refused for the hero, because its width is under 1920 px.
- An achievement badge must already be square.
- The thumb is your listing image in browse and search, so it has to read at small sizes. The hero heads your game page and is the share image, falling back to the thumb, then the icon.

### Rating, the content floor, and demos

Pick the PEGI band that matches your content. A game whose content does not match its band is sent back.

- **PEGI 3**: no violence or mature themes.
- **PEGI 7**: mild fantasy violence, or mildly scary content.
- **PEGI 12**: moderate violence, mild language or suggestive themes.
- **PEGI 16**: realistic violence, strong language or mature situations.
- **PEGI 18**: explicit adult content. It is accepted, behind an age gate.

**The content floor applies at every rating,** including PEGI 18: no sexual content, no real-money gambling, no hate speech, nothing illegal. It covers what your game links to as well as what it contains.

**Demos are welcome.** A demo is a game whose free part ends and points players elsewhere to continue. Four things must hold: the free part reaches a real ending (a finished round or a completion screen, not "you are out of lives, buy more"); the prompt appears only at that ending, never mid-session and never blocking a retry; the title and description say it is a demo; and the link goes to a purchase page, not to an ad network, a mailing list or a download. A demo is labelled as one in the catalogue, and a demo whose full version is sold off Gamemoor is never featured.

### Money

Games are free to play. The one money path is **tips**: a Stripe Checkout on your game page that pays your own Stripe account. There is no in-game purchase, and no checkout your game can open.

- You pick the country you are paid in before Stripe sets up your account, and it cannot be changed afterwards. Payouts go to the United States, the United Kingdom, the EEA, Canada and Switzerland. From anywhere else you can publish, but tips are not available.
- The tip button appears only once Stripe reports that your account can take charges and receive payouts. Finish the Stripe onboarding: tips can read as switched on in the portal while no button shows.

### Player feedback

Signed-in players can send you a private message from your game's page, once you switch feedback on for the game. It takes effect at once, with no review.

- A message carries its category, the date and the build the player was on. You see the player's username only if they chose to show it, and never their email address. There is no way to reply.
- A script can read the inbox with a token. See [Reading feedback from a script](https://gamemoor.com/developer/docs/publishing#feedback-export).
- Links in a message are shown as plain text. Report is for abuse, not for feedback you disagree with.

### Submitting, and what happens next

- Submitting moves the game to `review`. You are emailed the decision, either way.
- **You can withdraw a submission** while it is in `review`. The game goes back to `draft`. Uploading a build does the same.
- **A rejection returns the game to `draft`** with the reviewer's reason, which is emailed to you and shown on My games. Fix it and submit again.
- **Your release date is set once,** on the first approval. Unpublishing and coming back does not put you at the top of New releases again.
- **Your game's address is fixed once it has been live.** Renaming the game afterwards changes the title and leaves the address and the links to it alone.

### The lifecycle

| Status | Public | Listing edits | Build uploads | How it moves on |
| --- | --- | --- | --- | --- |
| `draft` | No | Saved directly. | The new build serves at once. | → In review: you submit it. |
| `review` | No | Not editable. | Allowed. The upload withdraws the game to draft. | → Live: Gamemoor approves it. → Scheduled: Gamemoor approves it for a release date. → Draft: Gamemoor rejects it with a reason, or you withdraw it or upload a build. → Suspended: Gamemoor takes it down. |
| `scheduled` | No. It goes public at its release time. | Not editable. | Allowed. The upload drops the release date and withdraws the game to draft. | → Live: its release time arrives, or Gamemoor releases it early. → In review: Gamemoor sends it back. The release date is dropped. → Draft: Gamemoor rejects it with a reason, or you upload a build. The release date is dropped. |
| `live` | Yes | Staged as a pending edit for review. The game stays live. | Staged. Players keep the approved build until Gamemoor promotes the new one. | → In review: Gamemoor moves it there. No developer action does. → Suspended: Gamemoor takes it down. → Unpublished: you unpublish it. |
| `archived` | No | Saved directly. | Refused. | → In review: you re-submit it, and it goes through review again. |
| `suspended` | No | Saved directly. | Refused. | → Live: Gamemoor reinstates it. You cannot. |

- **Only `live` games have a public page.** One exception: Moor's Club members can play a `scheduled` game 48 hours before its release date. Have your build ready by then.
- **A release date is optional.** With none, your game goes live as soon as it passes review. A date has to be at least 3 business days after you submit. You can change it while the game is in `review`; once the game is `scheduled`, only Gamemoor can, and you are emailed. If the date has passed by the time the game is approved, it goes live at once.

### Builds

Each upload on the **Builds** tab is kept as its own version. What an upload does depends on the game's status (see the table above).

- **On a `live` game the upload is staged:** players keep loading the approved build until Gamemoor promotes the new one. Promotion sends no email, so check the tab. _Open this build_ plays a staged build in your owner-only preview before it ships.
- **In `review`, an upload withdraws the game to `draft`,** so the build that is reviewed is the one that was submitted. No email is sent: check `withdrawnFromReview` in the upload response, and hold uploads while a review is open. A withdrawal is not a rejection.
- **Rolling back is yours; promoting is ours.** On a `draft` game, any build that was active before has _Roll back to this build_. On a `live` game, any build that was live before has it, and players load it on their next request. A build that was never live cannot be rolled back to: upload it again and it goes through review. Rolling back is not offered in `review` or `scheduled`.
- **Only the newest 3 builds keep their files,** staged builds included. An older build stays in the history without its files and cannot be activated or rolled back to. The build that is serving, and the newest build that was live before it, are always kept.
- **Treat every build you upload as public.** Do not upload anything embargoed, confidential or licensed elsewhere before you are ready to publish it.

### Scripts and CI

A developer access token lets a script do without a browser what you do in the portal up to review: create a game, fill in its listing and artwork, upload a build, and submit it. It can also read your players' feedback. Review, approval and release are the same as for a game you submit by hand. Create a token under **Access tokens** in the portal. It starts with `gmd_` and is shown once: a lost token is revoked and replaced, never recovered.

| Scope | Allows |
| --- | --- |
| `builds:write` | Uploads a build. |
| `listing:read` | Reads the two export documents and the achievement list. |
| `games:write` | Creates a draft and edits it, edits a listing, uploads artwork and screenshots, and adds achievements. |
| `games:submit` | Sends a draft, or an unpublished game, to review. |
| `feedback:read` | Reads the feedback players sent about your games, as your inbox shows it. |

- **Only the endpoints in the table below take a token.** Everything else needs a browser session: deleting a draft, withdrawing from review, unpublishing, release dates, rolling back builds, editing or retiring an achievement, switching, marking or reporting feedback, money, your profile, and tokens themselves.
- Send it in an `Authorization: Bearer` header and nowhere else: never a query string, cookie or form field. Revoking is immediate.
- A token expires after 90 days unless you tick _Never expires_. You can hold at most 5 active tokens; revoked and expired ones do not count.
- **Each token is limited to 10 requests a minute,** counted per token and not per IP address, so a shared runner does not share it. Pace your loop.
- `gameId` is the 26-character id in your game's portal URL, `/developer/games/<id>`, or the one `drafts/create` answers. A game that is not yours answers `404` with code `NOT_FOUND`, the same as an id that names no game.
- A token without the scope an endpoint needs is answered `403` with code `FORBIDDEN` and the scope named.
- A JSON body that is not JSON is answered `422` with code `INVALID_JSON`. One that breaks a rule is answered `422` with code `VALIDATION_ERROR`: the first problem in `error` as `field: message`, every problem in `details`.

### Endpoints a token reaches

Every answer is `{ success, data }` or `{ success: false, error, code }`, except the three exports, which answer a bare document when they succeed. Multipart uploads need no `Origin` header.

| Method | Path | Body | Scope |
| --- | --- | --- | --- |
| POST | `/api/developer/drafts/create` | JSON: the details below. Answers { gameId, slug }. | `games:write` |
| POST | `/api/developer/drafts/{gameId}/update` | JSON: the details below, all sent again. A draft only. | `games:write` |
| POST | `/api/developer/upload-icon?gameId={gameId}` | Multipart: file. The same for upload-thumb and upload-hero. Answers { url }. | `games:write` |
| POST | `/api/developer/upload-screenshot` | Multipart: file, pendingGameId, index (0 to 4). Answers { url }. | `games:write` |
| POST | `/api/developer/drafts/{gameId}/screenshots` | JSON: { screenshots: \[urls to keep\] }. Removes the others; adds nothing. | `games:write` |
| POST | `/api/developer/games/{gameId}/upload-achievement-icon` | Multipart: file. Answers { url } for icon\_url below. | `games:write` |
| POST | `/api/developer/games/{gameId}/achievements` | JSON: { title, description, icon\_url, trigger\_type, trigger\_value, slug? }. Creates a draft achievement. | `games:write` |
| GET | `/api/developer/games/{gameId}/achievements` | None. Lists the game’s achievements. | `listing:read or games:write` |
| POST | `/api/developer/games/{gameId}/update` | JSON: the details below, plus optional screenshots (a JSON array as a string) and icon\_url, thumb\_url, hero\_url from an upload. For a game past draft; on a live game the edit goes to review. | `games:write` |
| POST | `/api/developer/upload-game?gameId={gameId}` | Multipart: file (the ZIP). | `builds:write` |
| POST | `/api/developer/drafts/{gameId}/submit` | JSON: {}, or { release\_at?, early\_access? }. Answers { status: "review" }. | `games:submit` |
| POST | `/api/developer/games/resubmit` | JSON: { gameId }. An unpublished game only. | `games:submit` |
| GET | `/api/developer/games/{gameId}/export/listing and /export/achievements` | None. | `listing:read` |
| GET | `/api/developer/games/{gameId}/export/feedback` | None. Optional ?since= or ?cursor=. Answers one page of player feedback. | `feedback:read` |

- **The details:** `title` (up to 100 characters), `genre` (one of action, adventure, arcade, board, cards, casino, casual, creative, music, puzzle, racing, rpg, sim, sports, strategy, trivia, word), `pegi_rating` (3, 7, 12, 16 or 18), `tags` (a string, comma-separated or a JSON array of strings, at most 5), `short_description` (up to 160 characters), `description` (150 to 2000 characters) and `mobile_support` (`full`, `limited` or `disabled`). A draft may be saved incomplete; submitting checks it.
- **Submitting needs** complete details, a build, an icon and a thumbnail. Otherwise it answers `422` with the missing steps in `details.missing`. Screenshots and achievements are optional.
- On a draft, an upload is saved to the game as it lands. On a live game it is held until you send the listing through `games/{gameId}/update` with the returned URL, and it goes to review with that edit.
- `trigger_type` is `manual`, `score_threshold` or `play_count`. See [Achievements](https://gamemoor.com/developer/docs/integrating#achievements-authoring).

_details.json_

```
{
  "title": "Lantern",
  "genre": "puzzle",
  "pegi_rating": 7,
  "tags": "cozy, light",
  "short_description": "Light every room.",
  "description": "At least 150 characters…",
  "mobile_support": "full"
}
```

_Creating and submitting a game from a script_

```
# Create a game, fill it in and submit it for review.
# The token needs games:write, builds:write and games:submit.
AUTH="Authorization: Bearer $GAMEMOOR_TOKEN"
API="https://gamemoor.com/api/developer"

# 1. The draft. Keep the gameId.
GAME_ID=$(curl --fail-with-body -s -X POST -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d @details.json "$API/drafts/create" | jq -r .data.gameId)

# 2. Artwork: icon and thumbnail are required, the hero is not.
curl --fail-with-body -X POST -H "$AUTH" -F "file=@icon.png" "$API/upload-icon?gameId=$GAME_ID"
curl --fail-with-body -X POST -H "$AUTH" -F "file=@thumb.png" "$API/upload-thumb?gameId=$GAME_ID"
curl --fail-with-body -X POST -H "$AUTH" \
  -F "file=@shot-1.png" -F "pendingGameId=$GAME_ID" -F "index=0" "$API/upload-screenshot"

# 3. The build.
curl --fail-with-body -X POST -H "$AUTH" -F "file=@build.zip" "$API/upload-game?gameId=$GAME_ID"

# 4. Submit. A 422 lists what is still missing in details.missing.
curl --fail-with-body -X POST -H "$AUTH" \
  -H "Content-Type: application/json" -d '{}' "$API/drafts/$GAME_ID/submit"
```

_Uploading a build from CI_

```
# Upload a build from CI.
curl --fail-with-body -X POST \
  -H "Authorization: Bearer $GAMEMOOR_TOKEN" \
  -F "file=@build.zip" \
  "https://gamemoor.com/api/developer/upload-game?gameId=$GAMEMOOR_GAME_ID"

# {"success":true,"data":{"buildId":"01J…","activated":false,
#  "withdrawnFromReview":false,"releaseDateDropped":false,
#  "fileCount":42,"sizeBytes":1048576}}
```

- `activated` is `true` when the build is serving (a `draft`) and `false` on a live game, where it is staged. `withdrawnFromReview: true` means the upload took the game out of review. `releaseDateDropped: true` means it also dropped an approved release date.
- A failed upload is answered with a status and a code. See [Troubleshooting](https://gamemoor.com/developer/docs/troubleshooting#fix-ci-upload).

_Exporting your listing and achievements_

```
# Your published listing and your achievement definitions, as JSON.
# Both answer a bare document, not the { success, data } envelope.
curl -H "Authorization: Bearer $GAMEMOOR_TOKEN" \
  "https://gamemoor.com/api/developer/games/$GAMEMOOR_GAME_ID/export/listing" \
  -o listing.json

curl -H "Authorization: Bearer $GAMEMOOR_TOKEN" \
  "https://gamemoor.com/api/developer/games/$GAMEMOOR_GAME_ID/export/achievements" \
  -o achievements.json
```

Both exports are stable documents to commit next to your game: no timestamps and no generated ids, so an unchanged listing gives an identical file. The achievements export holds every achievement with its state, drafts and retired ones included. It holds definitions only, never who earned what. There is no import.

### Reading feedback from a script

_Reading your players' feedback_

```
# Player feedback sent after the newest message you already hold.
curl --fail-with-body -H "Authorization: Bearer $GAMEMOOR_TOKEN" \
  "https://gamemoor.com/api/developer/games/$GAMEMOOR_GAME_ID/export/feedback?since=2026-10-14T09:00:00Z"

# {"format":1,"game":{"id":"01J…","slug":"lantern"},
#  "messages":[{"id":"01J…","category":"bug","created_at":"2026-10-15T08:12:40.511Z",
#    "build_id":"01J…","body":"The jump does nothing on level two.","username":null}],
#  "has_more":false,"next":null}
```

- The feedback export holds the messages your inbox shows, archived ones included, oldest first. A message you reported, or one Gamemoor hid, is not in it. Reading does not mark a message read.
- Each message has its `id`, which never changes, `category` (`bug`, `idea` or `other`), `created_at`, `build_id` (the build that was serving when it was sent, or `null`), `body` and `username`. The username is there only when the player chose to show it, otherwise `null`. Nothing else about the player is.
- `since` is optional: an ISO-8601 time with its zone (`2026-10-14T09:00:00Z`) or a date (`2026-10-14`, midnight UTC). Only messages created after it are answered. Pass the newest `created_at` you hold to fetch what is new.
- One call answers at most 100 messages. When `has_more` is `true`, call again with `?cursor=` and the `next` value, without `since`, until it is `false`. A bad `since` or `cursor` is answered `422` with code `VALIDATION_ERROR`.
- Reading is all a token can do with feedback. Marking, archiving and reporting stay in the portal.

### The store listing

- **Editing a live listing does not take your game down.** The edit is staged as a pending revision for review. The game stays live on its current listing until the edit is approved, and a rejection leaves that listing as it was. You are emailed either way, and a second save replaces the pending edit.
- New art and screenshots on a live game go to review with the edit. Players keep seeing the current ones until it is approved.
- Limits: short description at most 160 characters, long description 150 to 2000 characters, at most 5 tags.

### Unpublishing and suspension

- **Unpublishing is yours,** from My games, and only from `live`. The game becomes `archived` (shown as Unpublished) and leaves public listings. Play history, scores and achievements are kept, and you can still edit the listing. Re-submitting puts it back into `review` for a full review, with its original release date.
- **You can delete only a `draft`.** Deleting removes the game, its builds, its achievements and its files. Once a game has plays, scores or tips it cannot be deleted, and your account cannot be deleted while you own a game.
- **Suspension is the one status you cannot leave.** You are emailed with the reason. You can still edit the listing; you cannot upload a build, unpublish or re-submit. Only Gamemoor can restore the game. Reply to the email to appeal or to ask.

## 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](https://gamemoor.com/developer/docs/integrating#protocol-reference) 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.

_index.html_

```
<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](https://gamemoor.com/developer/docs/integrating#gm-leaderboard-best-and-rank). |
| `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](https://gamemoor.com/developer/docs/integrating#saves). |
| `GM.loadGame()` | A promise for `{ ok, code?, signedIn, save }`. See [Saves](https://gamemoor.com/developer/docs/integrating#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. |

_Calling the SDK from your game_

```
// 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();
  });
}
```

> **What the SDK does when it is not on Gamemoor**
>
> - **Opened as a top-level page** (from disk, or on your own dev server): every call is a silent no-op. The promises resolve `{ ok: false, code: 'NOT_EMBEDDED' }`.
> - **Opened inside your own iframe harness** is not that case. `isEmbedded()` is `true`, the message goes to `https://gamemoor.com`, the browser drops it, and every promise resolves `TIMEOUT` after ten seconds with no error.
> - `onSession` and `onVisibility` never fire off-platform. A game that waits for either before its start screen is dead on your machine. On Gamemoor both arrive when your frame finishes loading, so if nothing has arrived a couple of seconds after load, start anyway.

### Scores

- **The player must be signed in.** A signed-out submission stores nothing and the reply is `ok: false` with `UNAUTHENTICATED`. Read `gm-session` on load and ask for sign-in _before_ a run starts: signing in reloads your game, and a run interrupted to sign in is lost.
- `score` is an **integer of 0 or more**. A float or a negative number is rejected with `VALIDATION_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_MAXIMUM` and 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.
- `metadata` is 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_LIMITED` and 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](https://gamemoor.com/developer/docs/publishing#artwork-slots) page.

- **Up to 10 per game.** Retiring one frees a slot, but its _slug stays reserved forever_: you cannot retire `first-blood` and then create a new `first-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-session` arrives with `preview: 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: false` with `UNAUTHENTICATED`. 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: true` with nothing new written, and the toast is not shown again.
- An unlock that comes back `NOT_FOUND` has several possible causes. See [Troubleshooting](https://gamemoor.com/developer/docs/troubleshooting#fix-unlock-silent).

### 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 with `VALIDATION_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_LARGE` or `SAVE_QUOTA_EXCEEDED`.
- **Signed-out players have no Gamemoor save.** `GM.loadGame()` answers `signedIn: false` and `GM.saveGame()` answers `UNAUTHENTICATED`. Keep saving to `localStorage` for 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, with `updatedAt: 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 says `overwrote: 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.

_Loading and saving_

```
// 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.parent` with target origin `https://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. Only `gm-ack`, `gm-leaderboard` and `gm-save` echo 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` |

_Sending a message without the SDK_

```
// 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.
- `signedIn` is all you learn about the player: never a name, an id or a tier.
- `preview` is `true` only 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-unlock` or `gm-save-write`. Payload: `{ for, ok, code?, requestId? }`, where `for` names the message being answered. A stored save adds `version` and `overwrote`.
- `ok: true` means the platform accepted it, not always that something was written: unlocking a badge the player already holds, and unlocking your own unpublished achievement, answer `ok: true` having stored nothing.
- `ok: false` carries exactly one `code`:

| 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](https://gamemoor.com/developer/docs/troubleshooting#fix-unlock-silent)). 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 gets `visible: false`, then `visible: true` when the ad closes. With no ad it gets `visible: true` at once.
- You may wait for `visible: true` before 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 `visibilitychange` event 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, call `GM.getLeaderboard()`.
- `top` is 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.
- `you` is the player's own best as `{ rank, score }`. It is `null` for a guest and for a player with no score in your game yet, never a zero: draw no rank when it is `null`.
- 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, call `GM.loadGame()`.
- Three answers, none of them empty: `signedIn: false` (a guest, no Gamemoor save), `save: null` (no save yet), or `save` as `{ data, version, updatedAt }`.
- A save is written with `gm-save-write` and answered with a `gm-ack`. See [Saves](https://gamemoor.com/developer/docs/integrating#saves).

_Listening without the SDK_

```
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;
  }
});
```

## 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-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](https://gamemoor.com/developer/docs/integrating#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.

| 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](https://gamemoor.com/developer/docs/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](https://gamemoor.com/developer/docs/integrating#gm-visibility-is-my-frame-on-screen).

_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();
});
```

## Troubleshooting

If your game sent a score, an unlock or a save and something went wrong, start with the code in the `gm-ack` reply: every message of a known type is answered, and the code is usually the whole diagnosis. The codes are in [gm-ack](https://gamemoor.com/developer/docs/integrating#gm-ack-did-it-land).

| Symptom | Go to |
| --- | --- |
| My game was rejected | [Publishing: submitting](https://gamemoor.com/developer/docs/publishing#submission-flow) |
| My game left the review queue | [Publishing: builds](https://gamemoor.com/developer/docs/publishing#shipping-builds) |
| Tips are switched on and no tip button shows | [Publishing: money](https://gamemoor.com/developer/docs/publishing#tips) |
| A script or stylesheet is refused, with a MIME type error in the console | [Publishing: the build](https://gamemoor.com/developer/docs/publishing#submission-requirements), file extensions |
| A file 404s | [Runtime: where your build lives](https://gamemoor.com/developer/docs/runtime#runtime-build-url), and zero-byte files in [the build](https://gamemoor.com/developer/docs/publishing#submission-requirements) |
| A request from my game is blocked | [Runtime: network](https://gamemoor.com/developer/docs/runtime#runtime-network) |

### My score is not on the leaderboard

Read the ack first. It names the reason, and the reasons are not interchangeable.

- `UNAUTHENTICATED`: the player is signed out. Nothing was stored and there is nothing to recover later. Ask for sign-in before a run starts.
- `VALIDATION_ERROR`: the score is not an integer of zero or more, or `metadata` is nested or over a limit. One bad key fails the whole submission. Nothing but a malformed submission gets this code, so read your own payload.
- `RATE_LIMITED`: the score was refused and not stored. Submit once per run, when the run ends, behind a flag your game loop cannot clear twice. Scores accepted earlier are untouched. Never resubmit in a loop.
- `SCORE_ABOVE_MAXIMUM`: the score is over the maximum on the game's Scores tab, and was not stored. Check the number your game sends, or raise or remove the maximum. Owner Preview refuses it the same way.
- `NETWORK_ERROR` and `INTERNAL_ERROR`: neither proves that nothing was stored. Treat them as unknown, not as failed: a resubmitted run is a second score.

If the ack said `ok: true` and the score is not shown: the leaderboard has one row per player, their personal best, and a tie does not replace it, so a second score lower than the first never appears. It counts only live games, and a new score can take a few minutes to show.

> **No reply at all**
>
> Three things are dropped without an ack: an unknown message `type`, an envelope whose `gm` is not exactly `true` or whose `version` is not exactly `1`, and a message posted to the wrong origin. The last is the one that catches people: see [Runtime: two origins](https://gamemoor.com/developer/docs/runtime#runtime-origins). Through the SDK the promise resolves `TIMEOUT` after ten seconds; hand-rolled, you get nothing.

### My unlock does nothing

Read the ack. Three codes, three unrelated problems.

- `UNAUTHENTICATED`: the player is signed out. **A signed-out unlock is never `NOT_FOUND`.** If you are looking at a `NOT_FOUND`, sign-in is not your problem.
- `RATE_LIMITED`: too many attempts. Fire an unlock when its condition is met, never on a timer or every frame. Re-firing a badge the player already holds counts as an attempt.
- `NOT_FOUND`: one code for several causes, deliberately. Work through the list below.

When an unlock comes back `NOT_FOUND`, it is one of these:

1. **The reference does not resolve.** Copy the exact call from the game's **Achievements** tab. The slug is stable and safe to hard-code; editing a title never changes it. The ULID also resolves.
2. **The achievement is not a `manual` one.** Score and play-count achievements are awarded by the platform and cannot be unlocked from inside a game.
3. **It is not published yet** and you are neither its author nor the owner of the game. A draft is testable by you and invisible to everyone else.
4. **It is retired.** Nobody can unlock it, including you.
5. **The player has not started the game recently.** Preview does not count. A draft you authored is exempt, but a published achievement tested from Preview needs you to have played the public game page first.

### My upload was refused

The archive is checked before anything is stored, and every refusal carries a stable code you can switch on. The limits are in [Publishing](https://gamemoor.com/developer/docs/publishing#submission-requirements).

| Code | Status | Cause |
| --- | --- | --- |
| `UPLOAD_INVALID_TYPE` | 400 | The filename does not end in .zip, in lower case. |
| `UPLOAD_TOO_LARGE` | 413 | The archive is over 30MB compressed, or extracts to more than 200MB. |
| `UPLOAD_INVALID_CONTENT` | 422 | The archive would not extract, holds more than 2000 files, has no index.html at its root, or holds a path containing .. or a leading slash. |
| `VALIDATION_ERROR` | 422 | The gameId is missing from the query string, or is not a 26-character id. |
| `NOT_FOUND` | 404 | The game is not one of yours. Another developer's game answers 404, never 403. |
| `FORBIDDEN` | 403 | The game is suspended or unpublished, or the token does not carry the builds:write scope. |
| `UPLOAD_FAILED` | 500 | Storage refused a write. No build is recorded: upload again. |

**`index.html` must sit at the archive root,** spelled exactly that way. `Index.html`, or an archive whose files sit one folder down, fails the same check with the same message, so the message cannot tell you which of the two mistakes you made: check both.

### My CI upload fails

Two failures a script sees are plain text, not JSON, so a script that parses every non-200 body as `{ success, error, code }` breaks on exactly the two it most needs to read. Switch on the status first, then the code. The upload codes are in the table above.

| Status | Code | Cause |
| --- | --- | --- |
| 403 | plain text, no code | An upload (a multipart POST) whose token is missing, malformed, expired or revoked, or whose account is suspended. It is refused before the route runs. |
| 429 | plain text, no code | The token's own rate limit. Pace the loop. |
| 401 | `UNAUTHENTICATED` | A JSON request or an export sent with no token. |
| 401 | `UNAUTHORIZED` | A JSON request or an export whose token is expired, revoked or unrecognised. The message says which of expired and revoked. |
| 403 | `FORBIDDEN` | The token is valid but lacks the scope the route needs, and the message names it; or the account is suspended. |
| 404 | `NOT_FOUND` | The game belongs to another developer, or does not exist. |

_Reading the status before the body, in CI_

```
# Read the status first, then the body. A bad token and a rate limit both
# answer plain text, not JSON.
status=$(curl -sS -o response.json -w '%{http_code}' \
  -H "Authorization: Bearer $GAMEMOOR_TOKEN" \
  -F "file=@build.zip" \
  "https://gamemoor.com/api/developer/upload-game?gameId=$GAME_ID")

case "$status" in
  200) # { "success": true, "data": { ... } }. Read data.activated and
       # data.withdrawnFromReview before calling this a successful deploy.
       ;;
  403) # JSON with code FORBIDDEN: the token lacks builds:write.
       # Plain text: the token is missing, expired or revoked, or the account is suspended.
       cat response.json; exit 1 ;;
  429) echo "rate limited: back off, then retry"; exit 1 ;;
  *)   cat response.json; exit 1 ;;
esac
```

A pipeline that stopped on a particular day with nothing else changed: check the token's expiry first. The limits on tokens are in [Scripts and CI](https://gamemoor.com/developer/docs/publishing#ci-uploads).

> **When none of these is it**
>
> Write to us from the [contact page](https://gamemoor.com/contact) with the game id, what you did, and what came back: an ack code, an HTTP status, or the text of a plain-text refusal. Account and billing questions go through [Account](https://gamemoor.com/account).

## Changelog

What changed for developers in the last 90 days, newest first. Read down to the date you last shipped: everything above it is something you may have to act on.

### Upcoming

| Date | Change |
| --- | --- |
| 2026-11-23 | Removing the ack code `SCORE_FLAGGED` from the protocol. It is no longer sent: a score sent too fast is refused with `RATE_LIMITED`. Drop any handling for it. See [gm-ack](https://gamemoor.com/developer/docs/integrating#gm-ack-did-it-land). |

### Changes

| Date | Change |
| --- | --- |
| 2026-11-16 | Added signed-out players' thumbs to a game's Overview in the developer portal: up and down counts beside the rating. They are not part of the rating, which still counts signed-in players only. |
| 2026-11-16 | Added a public Developers page at `/developers`, linked from the site header, with the docs, the review steps, how tips work and how to ask for access. The developer docs are now open to search engines. |
| 2026-11-03 | Removed the message names `score_submit` and `achievement_unlock`. Send `gm-score-submit` and `gm-achievement-unlock`; a message with an old name is dropped without a reply. See [Protocol reference](https://gamemoor.com/developer/docs/integrating#protocol-reference). |
| 2026-10-30 | Changed a link to a build's old address, `https://play.gamemoor.com/games/...`, to open the game's page on gamemoor.com. `https://play.gamemoor.com/shared/gamemoor-sdk.js` is unchanged. |
| 2026-10-24 | Fixed connecting Stripe for developers paid in the United States or Canada. |
| 2026-10-21 | Changed payout history on the dashboard to show a jam prize as a jam prize, not as earnings for a period. |
| 2026-10-20 | Changed withdrawing a pending listing edit to say why it failed, for example when your session has ended or the game was not found. |
| 2026-10-20 | Changed each error code to answer one status on every route. `VALIDATION_ERROR` is `422` where the uploads, drafts, tokens and achievements answered `400` or `409`, and a taken handle is `409` `DUPLICATE_ENTRY`, not `422`. See [My upload was refused](https://gamemoor.com/developer/docs/troubleshooting#fix-upload-refused). |
| 2026-10-19 | Changed payout amounts of €1,000 or more to show a thousands separator, and the portal to call your public page your studio page. |
| 2026-10-18 | Added the access token scope `feedback:read`, to read a game's player feedback from a script at `GET /api/developer/games/{gameId}/export/feedback`, with `since` for what is new. See [Reading feedback from a script](https://gamemoor.com/developer/docs/publishing#feedback-export). |
| 2026-10-11 | Changed the release date request to write times as `7 Oct 2026 at 17:00 UTC`. The earliest date, and the time shown as you pick one, are still in UTC. |
| 2026-10-09 | Changed a bad JSON body to answer `422` on every JSON API route, `INVALID_JSON` if it is not JSON and `VALIDATION_ERROR` naming the field otherwise. Another developer's game is `404` on unpublish, resubmit, update and revision. `tags` may be a JSON array. See [Endpoints a token reaches](https://gamemoor.com/developer/docs/publishing#token-endpoints). |
| 2026-10-09 | Changed deleting your account: your handle stays reserved, so nobody can claim it afterwards. |
| 2026-10-09 | Changed accepting an invite: an account that already has a developer profile cannot take a second one. |
| 2026-10-08 | Added deleting your account when you have published games. Your games are taken down and your developer page is removed; players keep their scores. |
| 2026-10-08 | Changed the docs to say what a game gets with the SDK and without it. The SDK stays optional: a game without it is listed and playable, with no scores, achievements or saves. See [With the SDK and without it](https://gamemoor.com/developer/docs/integrating#sdk-or-not). |
| 2026-10-08 | Changed the dashboard to show money only once you have some: tips, prizes or payouts. |
| 2026-10-08 | Fixed Connect Stripe to open a page, not raw text, when your Stripe account is already connected or you are signed out. |
| 2026-10-08 | Added a maximum score per game, set on the Scores tab. A score above it is refused and not stored, with the new ack code `SCORE_ABOVE_MAXIMUM`. See [Scores](https://gamemoor.com/developer/docs/integrating#scores). |
| 2026-10-08 | Changed the Achievements tab: Add opens its form beside the list and Edit opens on the row itself, with the cursor in the first field. A long list has a second Add under it, and retired achievements sit in their own group. |
| 2026-10-07 | Changed Connect Stripe to say what went wrong, with an error code, when Stripe's onboarding does not open. |
| 2026-10-06 | Changed the draft workspace, the Store listing, the Builds tab, the achievement editor and the tokens page to say what to do next when something is refused. |
| 2026-10-06 | Changed the full-screen play page for phones: your frame stays centred, and the Back control sits in the margin the frame leaves. Only where no margin is wide enough does the frame give up a little room. See [Frame shape](https://gamemoor.com/developer/docs/runtime#runtime-frame-shape). |
| 2026-10-06 | Added the access token scopes `games:write` and `games:submit`, to create a game, fill in its listing and artwork, and submit it for review from a script. See [Endpoints a token reaches](https://gamemoor.com/developer/docs/publishing#token-endpoints). |
| 2026-10-06 | Changed uploaded avatars to need a square image of at least 256×256, and an image that moderation flags is replaced with a library icon. |
| 2026-10-05 | Changed the developer docs into six pages. Old `/developer/docs#…` links go to the new page. See [the docs index](https://gamemoor.com/developer/docs). |
| 2026-10-05 | Added the whole docs as one Markdown file, at `/developer/docs.md`. |
| 2026-10-05 | Changed the full-screen play page for phones: the Back control has its own strip, so your frame is never under it, and a back swipe asks the player before leaving. See [Frame shape](https://gamemoor.com/developer/docs/runtime#runtime-frame-shape). |
| 2026-10-05 | Added withdrawing a game from review without uploading a build. See [Submitting](https://gamemoor.com/developer/docs/publishing#submission-flow). |
| 2026-10-04 | Added choosing a release date when you submit a game, at least 3 business days away. See [The lifecycle](https://gamemoor.com/developer/docs/publishing#status-lifecycle). |
| 2026-10-04 | Fixed replacing screenshots in one listing edit. |
| 2026-10-04 | Fixed the total plays on your public developer page to count live games only. |
| 2026-10-04 | Fixed Continue on the payout country page to open Stripe's onboarding. |
| 2026-10-04 | Changed the docs and this changelog to be readable without signing in. |
| 2026-10-04 | Added saves, one per signed-in player: `GM.saveGame(data)` and `GM.loadGame()` in SDK v1.4, or the messages `gm-save-write` and `gm-save-request`, with new ack codes `SAVE_TOO_LARGE` and `SAVE_QUOTA_EXCEEDED`. See [Saves](https://gamemoor.com/developer/docs/integrating#saves). |
| 2026-10-02 | Added play for Moor's Club members on a scheduled game 48 hours before its release date. See [The lifecycle](https://gamemoor.com/developer/docs/publishing#status-lifecycle). |
| 2026-09-30 | Changed each hosted game to be served from its own origin, `https://<game id>.gamemoorusercontent.com`, so browser storage written on the shared origin did not carry over. See [Origins](https://gamemoor.com/developer/docs/runtime#runtime-origins). |
| 2026-09-30 | Changed the game origin to enforce a Content-Security-Policy: requests from outside your build are blocked, service workers are refused, and a window opened with `window.open()` keeps the frame's sandbox. See [Network](https://gamemoor.com/developer/docs/runtime#runtime-network). |
| 2026-09-30 | Changed an achievement added after a game is approved for a scheduled release to need its own review. See [Testing and publishing achievements](https://gamemoor.com/developer/docs/integrating#achievements-lifecycle). |
| 2026-09-29 | Changed Roll back on a live game to offer only a build that was live before. See [Builds](https://gamemoor.com/developer/docs/publishing#shipping-builds). |
| 2026-09-29 | Changed tips to switch on only while Stripe can pay out to you. See [Money](https://gamemoor.com/developer/docs/publishing#tips). |
| 2026-09-28 | Added picking your payout country before you connect Stripe. See [Money](https://gamemoor.com/developer/docs/publishing#tips). |
| 2026-09-28 | Changed a new icon, thumbnail, hero or screenshot on a live game to go to review with the rest of the listing. See [The store listing](https://gamemoor.com/developer/docs/publishing#store-listing). |
| 2026-09-28 | Changed the suspension email and the game's Overview to give the reason. |
| 2026-09-27 | Changed games in review or scheduled to have no Roll back or Publish; upload a new build to change one. See [Builds](https://gamemoor.com/developer/docs/publishing#shipping-builds). |
| 2026-09-25 | Added frame shape, a setting on the Store listing tab. See [Frame shape](https://gamemoor.com/developer/docs/runtime#runtime-frame-shape). |
| 2026-09-24 | Added `GM.getLeaderboard()` in SDK v1.3 and the `gm-leaderboard-request` message, answered with `gm-leaderboard`. See [gm-leaderboard](https://gamemoor.com/developer/docs/integrating#gm-leaderboard-best-and-rank). |
| 2026-09-24 | Changed equal scores to rank by who set them first. |
| 2026-09-24 | Added approving a game for a release date: it shows as scheduled and goes live on its own. See [The lifecycle](https://gamemoor.com/developer/docs/publishing#status-lifecycle). |
| 2026-09-24 | Added player feedback, switched on per game. See [Player feedback](https://gamemoor.com/developer/docs/publishing#player-feedback). |
| 2026-09-23 | Changed `gm-visibility` to be always sent when your frame finishes loading. See [gm-visibility](https://gamemoor.com/developer/docs/integrating#gm-visibility-is-my-frame-on-screen). |
| 2026-09-23 | Changed scores sent too fast to be refused with `RATE_LIMITED` instead of flagged with `SCORE_FLAGGED`. |
| 2026-09-23 | Changed a platform failure while storing a score to be answered `INTERNAL_ERROR`, not `VALIDATION_ERROR`. |
| 2026-09-23 | Changed each access token to have its own rate limit, and capped a developer at 5 active tokens. See [Scripts and CI](https://gamemoor.com/developer/docs/publishing#ci-uploads). |
| 2026-09-23 | Changed the terms to say what you keep when you publish: your game stays yours, the licence to host and show it is non-exclusive, and we take it down within 14 days of your request. |
| 2026-09-21 | Changed a new draft's web address to come from its title, fixed once the game is published. |
| 2026-09-19 | Fixed build files with `.mjs` and other extensions to be served with the right content type. |
| 2026-09-19 | Fixed staging several builds so it no longer removes the build that Roll back offers. |
| 2026-09-18 | Changed uploading a build while a game is in review to withdraw it to draft. See [Builds](https://gamemoor.com/developer/docs/publishing#shipping-builds). |
| 2026-09-18 | Added developer access tokens, to upload a build and export your listing and achievements from CI. See [Scripts and CI](https://gamemoor.com/developer/docs/publishing#ci-uploads). |
| 2026-09-17 | Added withdrawing a pending listing edit, and an edit that was sent back reopens with the reviewer's reason and your text. |
| 2026-09-14 | Changed applying as a developer to need a verified email address. |
| 2026-09-13 | Changed editing a live game's listing to go to review without taking the game offline. See [The store listing](https://gamemoor.com/developer/docs/publishing#store-listing). |
| 2026-09-12 | Fixed screenshots uploaded together so they are all stored, in the order you dropped them. |
| 2026-09-11 | Changed a rejection to give the reviewer's reason and return the game to draft. See [Submitting](https://gamemoor.com/developer/docs/publishing#submission-flow). |
| 2026-09-11 | Added demo and trial games. See [Demos](https://gamemoor.com/developer/docs/publishing#content-policy). |
| 2026-09-02 | Added `gm-ack` replies to scores and unlocks, `gm-session` and `gm-visibility` messages, and SDK calls that return a promise. See [Protocol reference](https://gamemoor.com/developer/docs/integrating#protocol-reference). |
| 2026-09-02 | Changed message names to start with `gm-`, for example `gm-score-submit`. See [Protocol reference](https://gamemoor.com/developer/docs/integrating#protocol-reference). |
| 2026-09-02 | Added limits on the `metadata` of a score. See [Scores](https://gamemoor.com/developer/docs/integrating#scores). |
| 2026-09-02 | Changed the limit to 10 achievements per game. See [Creating an achievement](https://gamemoor.com/developer/docs/integrating#achievements-authoring). |
