@indiegems/gem-web-sdk
v28.0.2
Published
postMessage bridge contract between gem-web and browser-playable games
Readme
@indiegems/gem-web-sdk
The SDK a browser game uses to run on the Gem Arcade: the signed-in player, their saved progress, leaderboards, currencies and items, rooms and matches, and the server a match runs. One dependency covers both halves of a game — the browser client and its dedicated server.
Everything you need to build against it is in this package. The guides are in docs/,
the full API reference is in docs/api/, and both describe the version you installed.
Read them here rather than guessing from the type declarations, which carry signatures only.
Start here
docs/getting-started.md— the install, the firstcreateGemcall, and getting a build in front of a player. The install is written out there and only there.docs/what-a-game-must-do.md— what is left for a game once the SDK has done its part.docs/platform-rules.md— the rules the platform enforces that no signature states. Read it before you debug matchmaking.
Looking something up
| You want | Read |
|---|---|
| a symbol on the browser side — createGem, gem.me, gem.match, every type | docs/api/api-reference-game.md |
| a symbol on the server side — defineServer and what a match's server is handed | docs/api/api-reference-server.md |
| a symbol inside a serverless function — createGem from /function, and the gem it returns | docs/api/api-reference-function.md |
| saving a player's progress | docs/saving-player-progress.md |
| asking the player to sign in | docs/player-sign-in.md |
| vibrating the player's device, the iPhone included | docs/vibration.md |
| WebGL or WebGPU: which renderer to make on this device | docs/graphics-route.md |
| leaderboards | docs/leaderboards.md |
| currencies, items, shops and loot | docs/inventory-and-catalogs.md, docs/game-economy-tutorial.md, docs/trading-and-gifting.md |
| Coins and achievements | docs/arcade-economy.md, docs/achievements.md, docs/brand-art.md |
| the Indie Gems logo, the Gem Arcade wordmark and the platform's currency marks, as the platform serves them now | docs/branding.md |
| linking to the Arcade app or your game's app, opening another game, games like yours, selling Gem packs, Boosts and passes for real money — the Arcade Store — and selling your game's own products for real money | docs/arcade-and-store.md |
| what to signal at every break in play — level complete, game over, back to menu | docs/platform-moments.md |
| daily challenges, async opponents, friends | docs/daily-challenges.md, docs/async-opponents.md, docs/friends.md |
| a button the player presses for a revive or an extra try — rewarded ads | docs/rewarded-ads.md |
| analytics | docs/analytics.md |
| multiplayer — rooms, matches, room shapes | docs/rooms-and-matches.md, docs/room-shapes.md, docs/match-session.md |
| a dedicated server for a match | docs/server-bundles.md, docs/dedicated-server-flow.md |
| peer-to-peer matches and parties | docs/p2p-and-parties.md |
| server-side logic without a game server | docs/serverless-functions.md, written in Rust; JavaScript functions are disabled for now, due to performance issues, and docs/serverless-functions-js.md covers one already published in JavaScript |
| when a deprecated surface stops working | docs/deprecation-policy.md |
| what changed between versions, and what to do about it | CHANGELOG.md |
Every guide is one Markdown file, so a search over docs/ finds the page that covers a term.
What is in this package
| Path | What it is |
|---|---|
| @indiegems/gem-web-sdk/sdk | The one import a game writes, in the browser and on its server alike. |
| @indiegems/gem-web-sdk/game, @indiegems/gem-web-sdk/server | The browser half and the server half on their own, for a build that wants only one. |
| @indiegems/gem-web-sdk/function | What a serverless function written in JavaScript imports. JavaScript functions are disabled for now, due to performance issues: a new one cannot be uploaded, and one already published keeps running. A function's build bundles it, and the starter's build resolves /sdk and /game to it as well. |
| @indiegems/gem-web-sdk/schema | The wire schema between a game and the Arcade page that hosts it. |
| @indiegems/gem-web-sdk/brand/* | The platform's Coins and trophy art, the fallback for when gem.branding cannot reach the platform — see docs/brand-art.md. |
| gem-sdk-stamp <build-directory> | Run after your bundler: records which SDK version a build carries, which a published web build has to say. |
| docs/ | The guides and the API reference. Not imported by anything, so none of it reaches a player's download. |
| docs/api/reference.json | The API reference as data: every exported symbol, its signature and its documentation. |
| docs/manifest.json | When each guide last changed, with its sha256. |
