Starter templates

The starter templates are a web app (web-app), five small games and a server-code starter (functions-starter). You do not need a template: in your own project folder, run kumodeck init or ask your AI agent to set it up.

Web app#

web-app is a small private notes app built the way most AI tools build apps: React + Vite + TypeScript + Tailwind, with KUMODeck sign-in (guest first, then email), its own server code and database (Functions + D1: each user sees only their own notes), and real page URLs (/notes/123) that can be shared and reloaded ("web": { "spaFallback": true }).

kumodeck create my-app --template web-app && cd my-app
kumodeck init                                    # writes your publishable keys into public/kumo-config.js
npm install && kumodeck config push
npm run build                                   # → dist/ (deployDir "dist" is saved in kumo.json)
kumodeck deploy --env development

Its README.md and AGENTS.md cover the server code (kumodeck functions deploy) and local development.

Games#

Complete, playable games you can copy, change and publish with one command. Each one uses guest sign-in, a cloud save for the player's best score, a Share on X button with challenges, and keeps working offline. Want a leaderboard? Ask your AI agent (Claude Code, Codex, Cursor, …): the leaderboard Skill that comes with each template builds one in your own database and Functions.

Template	Engine	Game	Multiplayer
`vanilla-canvas`	none (plain `<canvas>`)	Star Catch — 30-second arcade round	—
`phaser`	Phaser 4.2.1	Dune Runner — endless runner	—
`pixi`	PixiJS 8.21.0	Bubble Pop — combo tapping	—
`three`	three.js 0.186.1	Orb Garden — 3D rolling-ball collector	shared garden (up to 8)
`multiplayer-starter`	none	Cursor Party — lobby, room codes, synced positions, shared state	yes

The game templates are zero-build: engines load from a pinned CDN URL, and the public/ folder is the site.

Use one#

kumodeck create my-runner --template phaser && cd my-runner
kumodeck init                                    # writes your publishable keys into public/kumo-config.js
kumodeck config push --env development
kumodeck deploy --env development                # deployDir "public" is saved in kumo.json
kumodeck share on                                # optional: X cards + share links

Without --template you get vanilla-canvas. create copies from the templates bundled with the CLI, so it works offline and does not touch the server; init is the step that creates the project. kumodeck create my-game --init does both when you are signed in.

kumo.config.json stays outside public/, so project details are never served to players. If you add a bundler, deploy its output folder instead (kumodeck deploy dist, or change deployDir in kumo.json).

Layout#

my-game/
  kumo.config.json    master data (not deployed)
  README.md
  AGENTS.md           instructions for AI coding assistants (commands, rules, SDK examples; not deployed)
  CLAUDE.md           one line, `@AGENTS.md`, so Claude Code reads the same file
  GEMINI.md           one line, `@./AGENTS.md`, so Gemini CLI reads the same file
  .agents/skills/     Skills (recipes) for your AI agent: INDEX.md lists them, e.g. leaderboard/SKILL.md (not deployed)
  .claude/skills/     the same Skills, where Claude Code looks
  public/             deployed as-is
    index.html
    kumo-boot.js      finds the API, loads the SDK, signs in, never blocks play
    kumo-config.js    public: apiUrl + publishable keys
    game.js

kumo-config.js holds one publishable key per environment. kumodeck init fills it in while it still says REPLACE_ME; a file you edited yourself is left alone. kumo-boot.js picks the development key on <slug>--dev URLs and on localhost, and the production key everywhere else. A single projectKey: 'pk_…' (older setup) still works.

public/kumo-config.js

window.KUMO_CONFIG = {
  apiUrl: '',                                  // '' = the origin the page is served from (right for kumodeck deploy)
  projectKeys: {
    development: 'pk_dev_…',
    production: 'pk_live_…'                    // publishable: safe in the browser. Never put an sk_ key here.
  }
};

AGENTS.md tells an assistant (Claude Code, Codex, Cursor, …) how to work on the game: the commands to run, that the account is created by you in the terminal (the assistant never handles your password), and that players never see the backend's name. It also points the assistant to the Skills (the list is in INDEX.md): the same files are in .agents/skills/ (Codex, Cursor and most other agents look there) and .claude/skills/ (Claude Code). Edit it like any other file.

Every template has a Share on X button on the result screen. It calls kumo.share({ kind: 'challenge', score }) with the player's score. When someone opens the game from that post, the menu shows "Challenge: beat N!" (kumo.share.incoming()). Offline or with sharing off, the button still opens X's post screen, just without a share id. Nothing is turned on in kumo.config.json — run kumodeck share on when you want the card image and share links. See Sharing on X.

URL flags every template understands: ?player=2 (a second guest in the same browser — test multiplayer against yourself), ?offline=1, and ?api=…&key=… to override kumo-config.js.

Server code#

functions-starter is not a game but the starting point for your own server code and SQL database, for an app or a game: a small API that verifies the calling user (a player in the API), writes to its own database and runs an hourly job. See Functions.