quickstart

follow these steps to register a game, install the SDK and run the counter example locally.

requirements

you need a computer, a browser, a code editor and Node.js. install Node.js 24 LTS (22 or newer is supported), then reopen your terminal: PowerShell on Windows, Terminal on macOS or Linux. run each command below on its own line. basic HTML, CSS and JavaScript will help; TypeScript adds checks to JavaScript, and the starter does not require React.

1
2node --version
npm --version

install Node.js learn HTML, CSS and JavaScript setup troubleshooting

1. register

sign in to the developer dashboard, register a game and submit its details for admin approval. you can develop and upload packages while waiting, but registration approval is required before submitting a build. copy the assigned game ID for the setup command below. this identifier is public and does not grant account access. every game must support 1–20 players; sometimes controls these limits. previews are implemented in your game code.

2. create your project

open a terminal in the folder where you keep projects. replace GAME_ID with the ID you copied, without angle brackets. my-game must be a new folder. npm may ask to install the SDK; accept that prompt. cd moves into your project, and npm install downloads its dependencies.

1
2
3
4npm exec --package=https://sometimeschat.com/game-sdk/v1/sometimes-games-1.0.2.tgz -- sometimes-game init my-game --id GAME_ID
cd my-game
npm install
npm run dev

3. develop and test

leave the terminal running and open the http://127.0.0.1 address it prints. you should see two players, each with a counter at 0. click add one: both counters should become 1. these are simulated players; you do not need a second account or a deployed server. stop with Ctrl+C. after saving code, run npm run dev again and reload the browser; there is no automatic reload.

make your first change

4. upload a build

set the version, description, player limits and capabilities in game.json. run npm run build, then upload the generated output/game.sometimes.json file on your game's dashboard.

1npm run build

5. submit and publish

inspect the verification report, then submit for review. an admin tests the exact build, approves it, and separately publishes it. publication adds it to games in the chat plus menu.