Spindro

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

  1. 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.
  2. 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.
  3. 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.

The Tempo template game's start menu: a title, length and level buttons, how to play, and a Start button.
The template game, Tempo, in its start menu. The menu, the stars and the results screen come from the shared kit: you do not write them.

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.