@indiegems/gem-web-sdk 7.4.0 → 7.4.1

package/docs/getting-started.md

@@ -0,0 +1,552 @@
+# Getting started
+
+From nothing to a game you can play in the Gem Arcade. Everything else in this section
+assumes you have finished this page.
+
+The platform is browser games: HTML, JavaScript and WebAssembly, served by the arcade and
+played in a sandboxed frame. There is no engine to install and no editor to learn. If you
+already have a web game, you are most of the way here.
+
+## 1. Install gemctl and sign in
+
+`gemctl` is the platform from the command line — it registers your game, serves it while you
+work, and publishes it when you are ready. Ask the platform team where to get it; it is not
+on npm.
+
+Once it is installed, sign in:
+
+```bash
+gemctl auth login
+gemctl auth status   # who you are, and which games you can reach
+```
+
+The session lives in your OS keyring rather than in a file. If `auth status` shows no games,
+that is an access problem rather than an empty account — ask whoever administers your
+organisation before assuming you need to create one.
+
+## 2. Point the directory at your game
+
+Every command below is scoped to one game, identified by a UUID.
+
+```bash
+gemctl game list                      # the games this account can reach
+gemctl settings set game_id <uuid>    # bind this directory to one
+```
+
+`gemctl settings` reports the id it resolved **and where it came from**, which is the first
+thing to check if a command acts on the wrong game.
+
+## 3. Add the SDK
+
+The SDK is what connects your game to the platform — the signed-in player, their saved
+progress, rooms and matches.
+
+**It ships inside your game.** One dependency, and your bundler compiles it in like anything
+else. The same install covers every part of the SDK — the browser client, and `defineServer`
+if your game's matches run server logic of their own. You do not choose between them at
+install time; a room template in your game config decides, and the code you write is the same
+either way.
+
+```jsonc
+// package.json
+"dependencies": {
+  "@indiegems/gem-web-sdk": "7.4.1"
+}
+```
+
+```js
+import { createGem, text } from '@indiegems/gem-web-sdk/sdk';
+```
+
+That is the whole of it. **Nothing goes into your HTML** — there is no `<script>` tag for
+the SDK, and if you are editing `index.html` while wiring this up, you are on the wrong
+path. It is a public package on npm, so no account, no credential and no repository access
+is involved, and nothing is built when you install.
+
+**`/sdk` is the import, from every seat.** It carries the whole surface, so client code, a
+dedicated server bundle and a listen host all import the same path and the same names.
+`.`, `/game` and `/server` stay published as narrow doors over the same modules — a game
+wants none of them unless it knows why.
+
+**`dependencies`, not `devDependencies`.** The SDK is part of what your game ships — your
+bundler compiles it into the browser build and into the server bundle — so a `--production`
+install still has to resolve it. In `devDependencies` it works on your machine and fails in
+whatever builds your release.
+
+### Upgrading, and the lockfile
+
+**Pin an exact version — `X.Y.Z`, not `^X.Y.Z`.** A range lets an ordinary install move you
+to a release you did not choose, and the client build and the server bundle can then end up
+on different ones. With an exact pin, `npm update` leaves you where you are. To upgrade, change
+the version, install again, and commit the lockfile. `npm outdated` tells you when a newer
+release exists.
+
+**Commit the lockfile.** npm and pnpm both record the package's hash on the first install;
+**install from that lockfile** — `npm ci`, or `pnpm install --frozen-lockfile` — and every
+install afterwards either gets the same bytes or fails. An install that re-resolves (a changed
+`package.json`, `pnpm update`, a missing lockfile) records the hash again from whatever it
+fetches. Uncommitted, the record is thrown away on every clone.
+
+**Projects set up before 5.9.0 name a download URL instead** —
+`https://downloads.gemarcade.com/sdk/vX.Y.Z/gem-web-sdk.tgz`. That URL keeps working, and it
+is the same package byte for byte, but new releases are announced as npm versions. To move
+over, replace the URL with the version number, install again, and commit the lockfile.
+
+Each release's package is also published beside its hash on that download host, if you want to
+check it by hand.
+[`server-bundles.md`](server-bundles.md#where-the-server-half-of-the-sdk-comes-from) has the
+recipe, and what that check does and does not prove.
+
+### The first connect is not instant, and that is normal
+
+The Arcade offers your game a connection on a repeating schedule rather than once, because it
+cannot know when your code is ready to hear one. A game that boots through a module graph
+connects on the first offer that lands after its listener attaches — **usually well under a
+second, and up to about two in the worst case.** Nothing is wrong, nothing is retrying, and
+the Arcade never gives up.
+
+**That time is not a stall unless you make it one.** Call `gem.frame.ready()` and put your
+own boot screen up first, then spend the wait loading assets.
+[The boot phase](what-a-game-must-do.md#the-boot-phase-settle-the-bridge-before-the-heavy-bundle)
+is where that time is either spent on work you owed anyway or wasted staring at a blank
+screen, and it is the one part of this you own.
+
+## 4. Connect
+
+```js
+import { createGem } from '@indiegems/gem-web-sdk/sdk';
+
+const gem = createGem();
+
+// Before loading your main bundle. The arcade re-offers the connection until
+// your game answers, but a busy main thread delays delivery of one that has
+// already arrived.
+await gem.awaitBridge();
+
+// Who is playing, once sign-in completes. A room call made before this lands
+// waits for it on its own (SDK 3.8.0 and later; before that it throws), so
+// await it when you want the ids rather than as a gate you must pass first.
+const me = await gem.awaitIdentity();
+```
+
+Two things about that call are worth getting right the first time.
+
+**You do not list who may embed your game.** The Gem Arcade's website and app are always
+allowed, and so is a dev host on your own machine (`gemctl serve`, the Gem Editor) while your
+game is served from loopback. `allowedEmbedders` exists only for a page beyond those — see
+[the embedder allowlist](what-a-game-must-do.md#1-the-embedder-allowlist) — and it adds to the
+arcade's origins rather than replacing them.
+
+**You do not declare your version.** The arcade routed this player to one of your builds, so it
+knows which build that is and tells your game — and that is what every room and match call
+reports. A `clientVersion` option still exists and is deprecated; see
+[what a game must do](what-a-game-must-do.md#2-your-version-number-which-you-no-longer-declare)
+for when an older arcade still needs it.
+
+**One more line if you render with WebGL**, and it is not part of `createGem`:
+
+```js
+const gl = canvas.getContext('webgl2', { preserveDrawingBuffer: true });
+```
+
+Players can attach a screenshot to a bug report, and without that flag the browser may clear
+your drawing buffer before the platform can read it. The SDK detects that and refuses rather
+than sending your team **a fully black image with no error attached** — but the cost is that
+your reports arrive with no picture. Two-dimensional canvas games need nothing here.
+[The full section](what-a-game-must-do.md#bug-reports-players-send-you-and-the-one-webgl-flag-that-decides-them)
+covers overriding the capture and attaching your own debug state, which is the part actually
+worth spending effort on.
+
+**There is no offline mode.** A game must be framed by an arcade page to reach the platform:
+unframed it still constructs and runs, but the bridge never connects and anything needing a
+token waits forever. To run framed without publishing, open your served build in the Gem
+Arcade app (step 6 below), or use the SDK repository's `examples/dev-harness/` — a local
+parent page that frames your dev server and completes a real handshake.
+
+## 5. Tell the arcade when you are ready
+
+The arcade shows a loading state until your game says it is playable. If you never say so, a
+player watches a spinner over a game that is already running.
+
+```js
+gem.frame.progress(loaded, total); // while assets load
+gem.frame.ready(); // once the player can actually play
+```
+
+And give players a way out — a visible control that calls `gem.exit()`. A game a player
+cannot leave is one they leave by closing the tab.
+
+## 6. Play it
+
+```bash
+gemctl serve start
+```
+
+Add `--tls` to open it in the Gem Arcade app. This serves your build and prints a link. Open it on this machine, or on a phone from the
+arcade website, with no link to copy and no token to type.
+
+### The developer panel
+
+The arcade carries a panel that renders over your game, **inside your game's frame**, and your
+game does not have to do anything for it. It shows identity, preferences, the bridge and its
+boot timeline, the token, rooms, characters, your game's declared config — room templates and
+save slots — and this player's saves, settings, inventory and currencies. It can **act**, not only
+read: it writes against those values, and its frame controls can end the session. Treat it as a
+console, not an inspector.
+
+Add `devtools=1` to the query string of the play URL — `&devtools=1` if the link already has
+one:
+
+```
+https://gemarcade.com/play/<uuid>?devtools=1
+```
+
+That is the arcade **website's** play page, and the flag is read there. A build you are serving
+locally is framed by the Gem Arcade app — a different parent — so if you need the panel before
+you publish, `gem.devtools.open()` from your own code is the route that does not depend on
+which parent framed you.
+
+It opens a round trip after your game first asks for a token: the permission rides that grant,
+not the handshake.
+
+**The value must be exactly `1`.**
+
+**It opens only for Contributor or above on that game** — the account signed into the arcade
+_in that tab_, which is not necessarily the one `gemctl` holds. That is why the flag is safe to
+leave in a link.
+
+**If it does not appear**, open the console on the **arcade page — the top frame, not your
+game's** — and read the lines prefixed `[play]`, plus any `[GameBridge]` ones. **You will see
+exactly one of these**, so stop once you have matched it:
+
+- **A `[play]` line about the value**, immediately, when it is not exactly `1`.
+- **A `[play]` line saying the frame declined**, on the first grant, when the published build's
+  SDK predates the panel — v2.4.1 or newer carries it. Following this page you are already on a
+  newer one; this binds a build you published earlier.
+- **A `[play]` line after 15 seconds** naming three causes it cannot tell apart: the account may
+  not have developer access on this game, the game may never have connected to the arcade or
+  never asked it for a token, or that build's SDK may predate the panel. A `[GameBridge]` line
+  about a refused mint, or a `handshake_timeout`, tells the second from the first — and
+  [the handshake is caught, not awaited](what-a-game-must-do.md#3-the-handshake-is-caught-not-awaited)
+  is where a game that never connects is usually losing.
+- **A `[play]` line saying the panel was asked for, and then nothing on screen.** The request
+  arrived and the panel itself failed to load. That is reported in **your game's** frame console
+  and network tab, under `gem-web-sdk.devtools.min.js` — the SDK pins that file by hash, so a
+  blocked or altered fetch fails closed.
+
+Once it is open:
+
+- **Escape closes it** while it has focus; your game's own Escape handler still gets the key
+  otherwise. There is a close control too.
+- **Closing it is final for that page load** — for the panel the arcade opened. Reload to get
+  it back, or call `gem.devtools.open()` from your own code, which can reopen it.
+- **Fullscreen covers it.** Leave fullscreen to see it again.
+
+The panel is also reachable from inside your game — see
+[GemDevTools.open](https://gemarcade.com/developer/api/game#gemdevtools-open), which answers
+`false` for a session that was not granted it rather than throwing — though it does reject if a
+panel it _is_ allowed to open fails to load, so catch it either way.
+
+If you put your own button on it, gate the button on
+[`onDevToolsPermissionChange`](https://gemarcade.com/developer/api/game#gemoptions-ondevtoolspermissionchange)
+rather than checking anything at boot:
+
+```js
+// Hidden until told otherwise. This never fires for a player, so nothing will
+// hide it for you — a button that starts visible is one every player has and
+// nobody can use.
+let debugButtonVisible = false;
+
+createGem({
+  onDevToolsPermissionChange: (canOpen) => setDebugButtonVisible(canOpen),
+});
+```
+
+The permission rides your session's first token, which arrives a round trip _after_ the game
+connects — so anything you read while starting up is read before the answer exists, and a
+developer would get no button. It is called again if the permission is withdrawn, so the button
+disappears rather than staying on screen doing nothing.
+
+`gem.devtools.open()` is what the button calls. It answers `false` rather than throwing for a
+session that was not granted the panel, but it does **reject** if a permitted panel fails to
+load — so catch it.
+
+### Linking to your game
+
+The play URL takes your own query parameters, and the arcade passes them into your game's
+frame. So a game can hand a friend a link to itself — to a puzzle, a board or a level — and
+read the values back when the link is opened.
+
+**Ask the arcade to share the link.** Give your Share button to `gem.share.request`, with the
+parameters the link should open your game with:
+
+```js
+// Show the button only where the arcade shares, and ask again on the click:
+// `request` throws once `available` has gone false.
+shareButton.hidden = !gem.share.available;
+shareButton.addEventListener('click', () => {
+  if (!gem.share.available) return;
+  gem.share.request({ params: { jar: 'JAR-K7P3QXM', n: '2', beat: '812' } });
+});
+```
+
+The arcade builds the link, which unfurls with your game's own card, and shares it through the
+player's share sheet, a copy, or its own Share panel. Your game is told nothing back — not
+whether the player shared, cancelled, or closed the panel — and `request` returns nothing.
+Where the arcade handles it, `gem.share.available` is true; outside the arcade, before the
+bridge is up, and anywhere the arcade does not share your game, it is false.
+
+`request` checks every parameter against the rules below **before** anything is sent, and
+throws on the first one the arcade would refuse, naming it: more than 16, a key that breaks the
+key rule or is one of the arcade's own, or a value that is not a string, is too long, or holds
+a character a link cannot carry. A mistake shows up at your desk, not as a Share button that
+does nothing for players — try it in the SDK's `examples/dev-harness/` with **share** ticked.
+
+**Where `available` is false, build the link yourself.** Use the `/games/<id>` page with
+`play=1`, which opens straight into your game and unfurls with its card, and hand it to the
+browser's own share sheet where there is one:
+
+```
+https://gemarcade.com/games/<id>?play=1&jar=JAR-K7P3QXM&n=2&beat=812
+```
+
+```js
+// GAME_ID: your game's id, as in its page's address on the arcade.
+const url = new URL(`https://gemarcade.com/games/${GAME_ID}`);
+url.search = new URLSearchParams({ play: '1', jar: 'JAR-K7P3QXM', n: '2', beat: '812' }).toString();
+// Cancelling the share sheet rejects with AbortError; that is a normal outcome.
+if (navigator.share) await navigator.share({ url: url.href }).catch(() => {});
+```
+
+Either way, read the values back from your own `location.search` — asking for the keys you
+defined, and checking each value before it does anything:
+
+```js
+const launch = new URLSearchParams(location.search);
+
+// Read only the keys you defined. Parse each into the type you expect and check
+// it against the range you expect; anything else counts as "the link had none".
+const jarRaw = launch.get('jar');
+const jar = jarRaw && /^JAR-[A-Z0-9]{7}$/.test(jarRaw) ? jarRaw : null;
+
+const n = Number(launch.get('n'));
+const jarIndex = Number.isInteger(n) && n >= 1 && n <= JAR_COUNT ? n : null;
+```
+
+That is the whole contract for your own keys. The bridge carries no launch message, and the SDK
+has no API for them: the arcade does the forwarding, so a build you published on any SDK version
+gets it without a code change. The one key that is not yours is the platform's `gemChallenge`
+(below), which belongs to [friend challenges](friends.md#friend-challenges): never define it, and
+never parse it yourself. The SDK will read it for you, and that is the only launch key it will
+ever read: the method ships in a later release, and until then a game has nothing to do with it.
+
+What reaches the frame:
+
+- **The query only.** A fragment (`#…`) is never forwarded.
+- **Not the arcade's own keys.** These are stripped and never reach the game, and they are the
+  only keys the arcade keeps for itself; it never interprets yours:
+  - Store and play-page switches: `play`, `channel`, `purchase`.
+  - Platform switches: `devtools`, `devLocale`, `playOverlay`.
+  - The arcade's own sign-in return marker: `social`.
+  - Attribution and campaign keys, which the arcade keeps out of every game: `_s`, `utm_*`
+    (every key with that prefix, matched case-sensitively, so UTM_X and utmost are yours),
+    `fbclid`, `ttclid`, `gclid`, `msclkid`.
+  - `embedder`, which stays what
+    [the embedder allowlist](what-a-game-must-do.md#1-the-embedder-allowlist) says: never read
+    from the URL — a link cannot even try.
+
+  A key starting with `_` can never be one of yours: the key rule below requires a leading
+  letter, so the arcade keeps that space for itself.
+
+- **One platform key.** `gemChallenge` does reach the frame — the arcade adds it when a player
+  opens a friend challenge — but it is the platform's, not yours. Do not define a key of that
+  name, and treat every key beginning with `gem` as reserved: a friend-challenge template refuses
+  a param named that way.
+- **Bounded.** At most 16 parameters. A key is a letter followed by up to 63 letters, digits,
+  `_` or `-`. A value is at most 512 characters with no control or format characters. An entry
+  that breaks a rule is dropped on its own; the rest of the link still arrives.
+
+Four things to hold onto when you share:
+
+**Call `request` synchronously from your own Share button's click handler.** Never from a
+timer, after an `await`, or on a game event such as a win: the arcade only shares on the
+player's own click, and anywhere else it opens its Share panel instead, if it does anything.
+
+**Never gate progress or a reward on sharing.** You cannot tell whether a player shared — the
+arcade does not say, by design — so a reward for sharing is a reward for pressing a button.
+
+**Put no personal identifiers in the parameters.** No player id, name, email or anything that
+leads back to a person: the link is public, and it is handed to whoever the player sends it to.
+Name the puzzle, not the player.
+
+**The share text is the arcade's own.** It is the arcade's "Play {game} on Gem Arcade", in the
+player's language, and your game supplies none.
+
+And four things to hold onto when a link opens your game:
+
+**Read only the keys you defined, and validate every value before it does anything.** Ignore
+the rest of `location.search`, unknown keys included. For each key you do read, parse the
+value into the type you expect and check it against the range you expect — an index is an
+integer within the count you have, a code matches the shape of the codes you issue — and
+treat anything else exactly as if the link had carried nothing. The arcade's bounds above are
+containment, not validation: they keep a value from being enormous or unprintable and say
+nothing about whether it makes sense to your game.
+
+**Every value is text written by whoever made the link.** Render it as text, never as markup —
+`textContent`, not `innerHTML`, and never inside a template that becomes HTML. And do not
+trust it as a fact: `beat=812` means the link _says_ there is a score of 812 to beat, not that
+anyone reached it. "Beat 812" is a claim, and the score is a number someone typed.
+
+**Any dev or debug switch your game reads from its own URL is now one shared link away.** A
+`?cheats=1` that used to need a developer typing it can be sent to anyone. Gate such switches
+on a build flag, not the URL.
+
+**The link replays.** The parameters stay in the store page's URL after the game exits, and the
+frame is mounted with them again on the next press of Play. A game that must not act on a link
+twice — one that grants something, or opens a challenge meant to be accepted once — should
+remember, per tab, that it consumed it. `sessionStorage` is that scope.
+
+## 7. Publish
+
+### First, say which SDK the build was made with
+
+**A published web build has to say which gem-web-sdk it was made with.** That is how a game
+left on a version the platform has stopped supporting gets found and its author told, instead
+of a player finding out.
+
+The SDK ships a command that records it. Run it after your bundler, on the directory you
+upload:
+
+```jsonc
+// package.json
+"scripts": {
+  "build": "vite build && gem-sdk-stamp dist"
+}
+```
+
+It writes one file, `gem-web-sdk.json`, at the root of that directory, and that is where the
+version is read from:
+
+```json
+{
+  "schema_version": 1,
+  "sdk_version": "X.Y.Z"
+}
+```
+
+**You do not pass the version.** It is read from the copy of the package your bundler compiled
+in, so upgrading the dependency is the only thing that changes it and the two can never
+disagree. Running it twice is safe — it replaces what it finds.
+
+**Your bundler does not matter.** It is a command rather than a plugin, so anything that ends
+with a directory you upload can run it, including a build you assembled by hand.
+
+### Then upload and promote
+
+```bash
+gemctl build upload --dir <your-build-output> --platform web --version 1.0.0
+gemctl build promote 1.0.0 --platform web --channel dev
+```
+
+**`--platform` is required and has no default**, and `web` is the one a browser game
+publishes to — `universal` and `mobile` no longer accept new builds at all. **`--version`** is
+a semver string of your choosing that has never been used for this game and platform, not even
+by a build since deleted: to change what players get, upload a new version and promote it rather
+than replacing one in place. Promote names the version too, because that is also how you roll
+back — point the channel at the previous one.
+
+This `--version` is the number the arcade reports to your game when it routes a player to this
+build, and the number every room and match call is then checked against. Nothing in your source
+has to agree with it.
+
+A game appears in a channel's list only when **both** a build and a store page are assigned
+to that channel — see the store page commands for the second half.
+
+Start on `dev`, move to `test` for a wider group, and `release` when it is ready for players.
+
+**A game may hold 25 builds per platform by default, and you do not have to manage that.** The
+ceiling is per game and per platform rather than across either, and support can raise or lower
+it. An upload at the ceiling still succeeds: the platform removes the least recently used build
+that nothing is using — one per upload, never more — and `gemctl build upload` and the Gem Editor
+say which one. A build was last used when it was uploaded or when it last left a channel, so one
+that left `release` last week counts as used last week however long ago it was uploaded.
+
+**Some builds are never removed:** a build on any channel; the two most recent builds to leave
+`release`, so there is always one to roll back to; anything uploaded in the last 30 minutes; a
+server build a live match may still need; and a blacklisted build. An upload made with a CI or
+service-client credential removes only builds that same credential uploaded.
+
+**A removed build is a deleted build.** Support can recover it for 30 days, as with one you delete
+yourself, and its version number cannot be used again — upload a new version instead, which
+`--version next` picks for you. An upload is refused (`build_count_exceeded`) only when nothing
+can be removed, and the refusal says when the next slot frees up — or that only deleting a build
+yourself will. A ceiling lowered below what you already hold never removes builds for you:
+uploads are refused until you are back under it.
+
+### Deleting a version you no longer want
+
+A game config and a store page are versioned the way a build is — every upload is a new version,
+and a channel points at one — and an old version of either can be deleted the same way:
+
+```bash
+gemctl config list --all                 # every config version, and the channel serving each
+gemctl config delete <version> --yes
+
+gemctl store list --all                  # every store-page version, and the channel showing each
+gemctl store delete <version> --yes
+```
+
+**You never have to.** A version no channel points at reaches nobody. Delete one to clear out
+versions you will not promote again.
+
+**A delete is recoverable for 30 days, but not by you.** The version leaves the list at once and
+can no longer be promoted. Support can restore it for 30 days; after that it is removed for good,
+and a store-page version takes its images and trailers with it. That is why the command asks for
+`--yes`. To see deleted versions and when each one is removed, add `--include-deleted`:
+
+```bash
+gemctl config list --all --include-deleted
+gemctl store list --all --include-deleted
+```
+
+**Take it off its channels first.** A version a channel still points at cannot be deleted, and
+the refusal names the channels. Promote another version to each of them, or
+`gemctl config unassign --channel <channel>` / `gemctl store unassign --channel <channel>` to
+leave the channel with nothing, then delete.
+
+**Deleting is not how you roll back.** Rolling back is promoting the earlier version, exactly as
+it is for a build. Deleting a version changes nothing a player sees, because a version players
+can see is one the platform will not let you delete.
+
+When a delete is refused, nothing has changed, and the refusal's code says why:
+
+| Code                          | Why                                                              | What to do                                                               |
+| ----------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `version_assigned_to_channel` | A channel still points at this version                           | Promote another version to that channel, or unassign it, then delete     |
+| `version_pending`             | A config version that is still being validated                   | Wait until `gemctl config view <version>` shows it settled               |
+| `revision_processing`         | A store-page version that is still being processed               | Wait until `gemctl store view <version>` shows `ready` or `failed`       |
+| `revision_in_experiment`      | A store-page experiment that has not concluded uses this version | Conclude the experiment, or unassign the channel it runs on, then delete |
+| `not_found`                   | There is no such version, or it is already deleted               | `--include-deleted` shows which                                          |
+
+Promoting a deleted version is refused too (`cannot_assign_deleted_version`), and so is using a
+deleted store-page version in an experiment. Upload it again to get a new version, or ask support
+to restore the old one while its 30 days last.
+
+Deleting takes your own sign-in, with an Owner, Admin or Contributor role on the game. A
+credential made for a build pipeline can upload and promote, and cannot delete.
+
+## What to read next
+
+- **[What a game still has to do for itself](what-a-game-must-do.md)** — the parts of the
+  integration the SDK does not do for you, and which gaps you will hit first.
+- **[The platform rules a game finds out for itself](platform-rules.md)** — the rules the
+  backend enforces that no client-side signature states. Read it before you debug
+  matchmaking.
+- **[Saving a player's progress](saving-player-progress.md)** — if your game has anything
+  worth keeping between sessions.
+- **[Inventory and catalogs](inventory-and-catalogs.md)** — if it has an economy: currencies,
+  items, shops or loot. Start with **[the shop tutorial](game-economy-tutorial.md)** to build one.
+- **[Rooms and the match lifecycle](rooms-and-matches.md)** — if it is multiplayer.
+
+The [API reference](https://gemarcade.com/developer/api) has every symbol the SDK publishes,
+with signatures and descriptions.