Build a game
A Spindro game is one folder, one registry entry and its text strings. The repository has a template game, a guide that goes from a fresh clone to a game on your screen in about 15 minutes, an API reference, design rules, and a bot that checks your game.
Three steps
- Copy the template folder: the template game is js/games/template/tempo.js, copied to js/games/<your id>/index.js, with its name and id replaced.
- Add one entry to the registry in js/games/registry.js. While the game is not ready, mark it dev so it only shows in developer mode.
- Add your strings (name, desc, help) in the five files locales/en, it, fr, es and de.json, and run the i18n check.
The 15-minute path
You need Node 22 and git. There is no build step. This is the start of the guide:
git clone https://github.com/C1aud1o/Spindro.git && cd Spindro
git checkout -b game/mygame beta
npm ci
npm run dev
# then open http://127.0.0.1:5173/index.html?game=tempo&demo=1
mkdir js/games/mygame
cp js/games/template/tempo.js js/games/mygame/index.js
# add one line to js/games/registry.js, add games.mygame.* to the 5 locale files
npm run game:check -- mygame
The demo flag replaces the trainer with a simulated rider with sliders for power and cadence, so you can play without a trainer. Reload the page after each change.

What the kit gives you
- Rider data
- hooks.stats() returns power, cadence, gear and heart rate; hooks.ftp() returns the FTP. Targets are fractions of FTP, never fixed watts.
- Menu and results
- One start menu (length, level) and one results screen for every game: long-press + or pedal to start, then stars and personal bests.
- Workout mode
- If hooks.workout() returns a plan, the workout decides the targets and the length.
- HUD helpers
- Text and panel helpers in the kit's hud.js for readable on-screen numbers.
- Input
- input(dir) receives exactly +1 or −1, from a Zwift Click or the keyboard. Every game must be playable with + / − and the pedals alone.
- 3D starter
- A three.js starter, js/games/template/skeleton3d.js, with the shared stage, sky, lights and cyclist.
Check it with the bot
The check plays your game at 0.6, 0.8, 1.0 and 1.2 times FTP with the demo rider. It prints the stars earned, the time to the first event, the longest gap without an event, events per minute and milliseconds per frame, and when a rule is broken it says which one and how to fix it.
The rules a game follows
- A run is a workout of 5, 10 or 20 minutes, with intensity as a percentage of the rider's FTP, so it is fair at 120 W and at 320 W.
- Three levels (easy, normal, hard) and a difficulty that adapts a little after failed or successful efforts.
- Something to do within eight seconds, and never more than five seconds without an event that asks or rewards something.
- Playable without touching the screen: watts and cadence do the work, + and − do one thing.
- Whoever stops pedalling pauses the game; nobody is punished for pushing harder.
Before you send it
- Add the files your game imports to the ASSETS list in sw.js and bump the cache name.
- Assets need a clear licence (CC0, MIT, OFL, or made for the project) and a credit in the README and the licences page.
- A genre or a mechanic is fine; a clone of an existing commercial game is not.
- Open a pull request against the beta branch, with the checklist from the design rules and the bot's table.