@netforge/template-platformer 0.0.0-stage → 0.2.0

package/AGENTS.md

@@ -0,0 +1,65 @@
+# Extending SKYLEDGE
+
+SKYLEDGE is the platformer template of the Net Forge game engine. This file tells a coding agent how to change the game safely. `llms.txt` in this package has the full recipe book for this genre, and `llms-full.txt` adds the whole `src/game.ts` as a worked example.
+
+## The one file to edit
+
+Change the game by editing `src/game.ts` only. It holds declarations, not engine code. src/names.json holds the title and every label players read (upgrades, earn rules, store items). Everything else (the client, the manifest, the store hooks, the simulation, the netcode) is template machinery.
+
+## Import only @netforge/engine
+
+`src/game.ts` imports from `@netforge/engine` and nothing else. The template's game imports:
+
+```ts
+import { earn, game, store, system, upgrade } from "@netforge/engine";
+```
+
+Also available for this genre: `economy`. `earn` has `earn.rule(...)` and `earn.stake(...)`; `store` has `store.sku(...)`. `system(id, ctx => ...)` gets the systems API described in `llms.txt`. The renderer, input, netcode and physics live elsewhere and are not reachable from game code.
+
+## Rules the build enforces
+
+- Ids are lower_snake_case.
+- Every game declares at least one `earn.rule(...)` (mandatory earn) and one `earn.stake(...)` (the buy-in run), on one top-level line. A game without either does not build.
+- Asset ids are library ids such as `style.lowpoly.turret`, never URLs or file paths, and must exist in the asset library.
+- `game({ template: "platformer", style, levels: [...] })` with 1 to 8 levels.
+- No `weapon()`, `director()`, `keeper()` or enemy prefabs: the challenge is the course.
+- Every course must be finishable: the route planner runs from the start to the flag on every level, and a level with no route fails the build.
+- Upgrades raise one of: speed (run speed), amount (extra air jumps), magnet (coin reach, m), maxHealth (shield hits per life), haste (dash cooldown).
+- 4 players plus seat bots must all reach the flag, and an earn rule must fire, in a 4-minute playtest.
+- `game({ style })` is the art style the creator picked (lowpoly, toon, ps1, pixel, voxel or handdrawn). Keep it.
+- Keep the store SKUs the client is wired to, at their prices: feather, sprint, shield, skin_sunset and skin_frost (with the outfits' grants: sunset 1, frost 2). "stake" is reserved and is never a SKU id.
+
+## Validate
+
+- With the MCP server (`npx -y @netforge/mcp`, bin `netforge-mcp`): call `netforge_validate_game` on the game. It returns one line per problem.
+- In this package: `npx vitest run` runs `test/harness.test.ts`, `test/host.test.ts`, `test/race.test.ts`, `test/store.test.ts`. A bad declaration throws `GameDefinitionError` with a line you can act on.
+
+## Playtest
+
+- With the MCP server: call `netforge_run_playtest`.
+- In code: `import { engine } from "@netforge/engine"` and run `engine.test.run({ ticks: 60 * 240, bots: 4, assert: [] })`. It reports rounds (wave), runs.won (rounds every playtest climber finished), scorers, deaths (falls), earned by rule, softlock, ms per tick and fun.routes (the planner's route per course).
+
+## Play locally
+
+```sh
+mkdir -p my-game/src && cd my-game
+npm init -y && npm install @netforge/kit-play @netforge/engine @netforge/template-platformer
+cp node_modules/@netforge/template-platformer/src/game.ts src/
+echo '{"template":"platformer"}' > netnet.json
+npx kit-play        # opens http://127.0.0.1:4663
+```
+
+The MCP tool `netforge_play_locally` does the same. Coins are play money; nothing pays out and no chain or wallet is involved. Edit `src/game.ts` and run it again to try a change.
+
+## What not to do
+
+- Do not write renderers, netcode, physics or bot AI. The template already has them.
+- Do not use asset URLs or file paths. Use library ids.
+- Do not import anything other than `@netforge/engine` in `src/game.ts`.
+- Do not edit `client/`, `src/manifest.ts` or `src/store.ts`.
+- Do not rename or reprice the store SKUs the client is wired to.
+- Do not add weapons, enemies or a director; build challenge into the course instead.
+
+## Docs
+
+https://forge.netnet.capital/docs/templates/platformer

package/CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md
+
+Read AGENTS.md before changing this game.
+
+The five hard rules:
+
+1. Edit only `src/game.ts`.
+2. Import only `@netforge/engine`.
+3. Ids are lower_snake_case.
+4. Declare at least one `earn.rule(...)` and exactly one `earn.stake(...)`.
+5. No renderers, netcode, physics or asset URLs.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NetNet Capital Management
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,34 @@
+@netforge/template-platformer (SKYLEDGE)
+Copyright (c) 2026 NetNet Capital Management
+
+An original game. No names, characters, maps, models, sounds or code from
+any other game or franchise.
+
+Art and sound
+- Models come from the per-style asset library
+  (@netforge/asset-library): CC0 1.0 models by Quaternius (via Poly
+  Pizza: the climbers and the coin) and Kenney (Nature Kit: trees, rocks,
+  bushes), each pack listed with its
+  source URL and licence verification in that package's NOTICE and
+  manifest/packs.json. The files are fetched and built, never committed
+  here; the build copies only the models this game uses.
+- Blocks, ledges, thorns, springs, flags and the fallback climber
+  (client/scene.ts) are generated from three.js primitives; all textures
+  are drawn on a canvas at load. Sounds are the library's CC0 samples with
+  WebAudio-synthesized fallbacks (client/audio.ts).
+
+Dependencies (unmodified, via npm)
+- three.js 0.186.1 (https://github.com/mrdoob/three.js), MIT.
+- @netforge/engine and @netforge/engine-sim (this repository);
+  see their NOTICE files (bitECS MPL-2.0, Rapier Apache-2.0, Colyseus MIT,
+  zod MIT).
+
+Patterns (ideas only)
+- The platformer genre's general mechanics (run, jump, checkpoints, coins,
+  springs, moving platforms, a flag at the end, racing to it). Mechanics,
+  not expression; no level, character or text was copied from any game.
+- Jump feel (coyote time, jump buffering, variable jump height, apex hang,
+  fall gravity, corner correction) as described in public game-feel talks
+  and articles (e.g. "Math for Game Programmers: Building a Better Jump",
+  GDC 2016; Maddy Thorson's public notes on Celeste's forgiveness
+  mechanics). Implemented from scratch in engine-sim src/platform.ts.

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @netforge/template-platformer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A multiplayer platformer game template for Net Forge: a side-view race to the flag for up to 8 players over cliffside courses (SKYLEDGE).
+
+Climbers run, jump (hold for height, tap for a hop), dash across gaps, ride moving platforms, bounce off springs and stay off the thorns. Each climber collects their own coins. A round is one course, and the next round runs the next course. Seat bots fill empty places, so one person alone still has a race.
+
+The simulation is the engine's deterministic platform mode: swept box movement on a 1/1024 m grid at 60 Hz, so a predicting client replays its own climber bit for bit. Climbers are ghosts to each other and coins are per climber, so nothing another player does can make your prediction wrong.
+
+Jump feel: coyote time (0.1 s), a jump buffer (0.13 s), variable jump height, a lighter apex while Jump is held, a heavier fall, ceiling corner nudges and an air dash.
+
+The race runner owns rounds (countdown, race, results, next course). It pays `player.finished` for your own finish, and `race.won` and `race.podium` only with another person in the round. Seat bots run routes found by the route planner and never earn. Every course must have a planner route to the flag, or the build fails.
+
+## Install
+
+```sh
+npm install @netforge/template-platformer
+```
+
+You normally do not import this package yourself. `kit play` runs it on your own computer, and the Net Forge MCP server and studio copy its `src/game.ts` as the starting point for a new game.
+
+## Play it locally
+
+```sh
+mkdir -p my-game/src && cd my-game
+npm init -y && npm install @netforge/kit-play @netforge/engine @netforge/template-platformer
+cp node_modules/@netforge/template-platformer/src/game.ts src/
+echo '{"template":"platformer"}' > netnet.json
+npx kit-play        # opens http://127.0.0.1:4663
+```
+
+Coins are play money and nothing pays out. Real-token earning, stakes and claims run only on the hosted Net Forge server.
+
+## Change the game
+
+Courses run three minutes and three seat bots fill the room. Field more bots and give each course a little longer:
+
+```ts
+players: { prefab: "style.lowpoly.rogue", max: 8, bots: 5 },
+round: { seconds: 210 },
+```
+
+Save `src/game.ts` and run `npx kit-play` again.
+
+## Files
+
+| Path | What |
+|---|---|
+| `src/game.ts` | The game, declarations only: three courses, three round upgrades, earn rules, stake, store. |
+| `src/manifest.ts` | Loads and compiles the game; `platformerAdapter()` and `platformerGame()` for the room host and the client. |
+| `src/store.ts` | Store hooks on the Kit's names: three round upgrades (40, 40, 60 coins), two outfits (300, 500) and the shield charm gear (120). |
+| `client/` | The browser client: a side-view three.js scene in every art style, HUD, input (keys, gamepad, touch), game feel. |
+| `scripts/plan.ts` | The route planner run on every course (how long a good run takes). |
+| `test/` | Playtest bots through `engine.test.run`, the race rules, prediction, the local host and the store. |
+| `llms.txt` | How to change the game, for agents. |
+
+## Controls
+
+Keys: A D or arrows run, Space W or Up jump, Shift dash, Down plus Jump drops through a ledge, R or Enter readies the next course. The backquote key shows stats.
+
+## For AI agents
+
+Read `AGENTS.md` and `llms.txt` in this package before changing the game. `llms-full.txt` adds the whole `src/game.ts` as a worked example.
+
+Agents can also drive this template through the Net Forge MCP server: run `npx -y @netforge/mcp` (package `@netforge/mcp`, bin `netforge-mcp`). Its tools are `netforge_list_templates`, `netforge_create_game`, `netforge_explain_api`, `netforge_search_docs`, `netforge_validate_game`, `netforge_run_playtest` and `netforge_play_locally`.
+
+To set up a coding agent in a game project, run `npx netforge setup agent`. It writes AGENTS.md, CLAUDE.md, Cursor rules and `.mcp.json` into the project. In Claude Code you can also add the server directly with `claude mcp add netforge -- npx -y @netforge/mcp`.
+
+## Docs
+
+- https://forge.netnet.capital/docs/templates/platformer
+- `llms.txt` and `llms-full.txt` in this package (also exported as `@netforge/template-platformer/llms.txt` and `@netforge/template-platformer/llms-full.txt`)
+
+## License
+
+MIT. See `LICENSE` and `NOTICE`.

package/client/audio.ts

@@ -0,0 +1,34 @@
+/**
+ * SKYLEDGE's sound cues on the engine's FeelAudio. Coins, landings, dashes
+ * and falls play the asset library's CC0 samples (PLATFORM_SAMPLES, loaded
+ * by the engine's SoundPlayer with a music loop); jumps stay synthesized so
+ * a jump and an air jump are told apart by pitch. Every cue keeps a synth
+ * recipe as the fallback when a sample cannot load.
+ */
+import type { FeelAudio } from "@netforge/engine/runtime";
+
+/** Cue name -> library sound id (soundBank's `cues` overrides). */
+export const PLATFORM_SAMPLES: Readonly<Record<string, string>> = {
+  coin: "audio.sfx.coin",
+  land: "audio.sfx.land",
+  dash: "audio.sfx.dash",
+  fall: "audio.sfx.downed",
+  checkpoint: "audio.sfx.confirm",
+  finish: "audio.sfx.level_up",
+  shield: "audio.sfx.hit",
+};
+
+export function definePlatformCues(a: FeelAudio): void {
+  a.define("jump", { wave: "square", f0: 320, f1: 720, ms: 110, gain: 0.32 }, { minGapMs: 50, voices: 2, pitchVar: 0.03 });
+  a.define("airjump", { wave: "square", f0: 520, f1: 1100, ms: 120, gain: 0.32 }, { minGapMs: 50, voices: 2, pitchVar: 0.03 });
+  a.define("coin", { wave: "triangle", f0: 1320, f1: 1980, ms: 90, gain: 0.45 }, { minGapMs: 30, voices: 3, pitchVar: 0.06 });
+  a.define("land", { wave: "triangle", f0: 160, f1: 60, ms: 90, gain: 0.5 }, { minGapMs: 80, voices: 1 });
+  a.define("dash", { wave: "sawtooth", f0: 900, f1: 200, ms: 140, gain: 0.35 }, { minGapMs: 80, voices: 1 });
+  a.define("spring", { wave: "sine", f0: 200, f1: 900, ms: 260, gain: 0.55 }, { minGapMs: 120, voices: 1 });
+  a.define("fall", { wave: "sawtooth", f0: 420, f1: 60, ms: 520, gain: 0.6 }, { minGapMs: 300, voices: 1 });
+  a.define("checkpoint", { wave: "triangle", f0: 660, f1: 990, ms: 160, gain: 0.6 }, { minGapMs: 120, voices: 1, pitchVar: 0 });
+  a.define("finish", { wave: "triangle", f0: 523, f1: 1046, ms: 420, gain: 0.7 }, { minGapMs: 400, voices: 1, pitchVar: 0 });
+  a.define("shield", { wave: "square", f0: 300, f1: 200, ms: 120, gain: 0.45 }, { minGapMs: 100, voices: 1 });
+  a.define("tick", { wave: "square", f0: 880, f1: 880, ms: 70, gain: 0.35 }, { minGapMs: 200, voices: 1, pitchVar: 0 });
+  a.define("go", { wave: "square", f0: 1320, f1: 1320, ms: 200, gain: 0.4 }, { minGapMs: 200, voices: 1, pitchVar: 0 });
+}

package/client/decor.ts

@@ -0,0 +1,22 @@
+/**
+ * Library models the SKYLEDGE scene draws on its own (template machinery,
+ * not game content). The build copies these with the models game.ts uses,
+ * in every art style.
+ */
+/** Seat bots: a different climber from the players' model. */
+export const BOT_MODEL = "style.lowpoly.mini_female_c";
+/** Every course's coins. */
+export const COIN_MODEL = "style.lowpoly.coin";
+/** Climbers are drawn this tall, m (the body box is 1.4 m). */
+export const PLAYER_HEIGHT = 1.45;
+
+/** Scenery on the cliff tops behind the course: [library id, height m, how far back it may stand m]. */
+export const BACKDROP: readonly (readonly [string, number, number])[] = [
+  ["style.lowpoly.tree_pine", 4.2, 2.5],
+  ["style.lowpoly.tree_oak", 3.6, 2.5],
+  ["style.lowpoly.rock_small", 0.7, 2],
+  ["style.lowpoly.bush", 0.9, 1.5],
+  ["style.lowpoly.mushroom_red", 0.5, 1],
+];
+
+export const SCENE_MODELS: readonly string[] = [BOT_MODEL, COIN_MODEL, ...BACKDROP.map(([id]) => id)];

package/client/host.ts

@@ -0,0 +1,96 @@
+/**
+ * Net Forge as host. Framed by Net Forge, the page URL carries
+ * the Kit flags and the host posts one message; played on its own, none of
+ * this applies and the game behaves exactly as before.
+ *
+ *   ?host=netnet       the host draws Invite and sign-in; the game hides its own
+ *   ?coin=TICKER       the coin the HUD names (2 to 6 capitals or digits)
+ *   ?title=NAME        the game's own name for the wordmark and the tab title
+ *   ?player=guest      no wallet is connected: play pays nothing, and the HUD
+ *                      says "not earning" instead of a balance
+ *   ?player=play       the token has not launched: coins are play money
+ *
+ * The player flag changes while the game runs (a wallet connects), so the
+ * host also posts { kind: "netnet-kit", type: "player", mode }. Only the
+ * parent window is listened to, and only when the URL says it is the host.
+ */
+
+export type PlayerMode = "earning" | "guest" | "play";
+
+export interface HostFlags {
+  /** Framed by Net Forge. */
+  readonly framed: boolean;
+  /** The coin's ticker, when the host names one. */
+  readonly coin: string | null;
+  /** The game's own name, when the host names one. */
+  readonly title: string | null;
+  /** What play pays the person at the screen. Standalone play is "earning" (the game's own kit decides). */
+  readonly player: PlayerMode;
+}
+
+const TICKER_RE = /^[A-Z0-9]{2,6}$/;
+
+export function hostFlags(params: URLSearchParams): HostFlags {
+  const framed = params.get("host") === "netnet";
+  const coin = params.get("coin");
+  // eslint-disable-next-line no-control-regex
+  const title = (params.get("title") ?? "").replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim().slice(0, 40);
+  const player = params.get("player");
+  return {
+    framed,
+    coin: coin && TICKER_RE.test(coin) ? coin : null,
+    title: title || null,
+    player: framed && (player === "guest" || player === "play") ? player : "earning",
+  };
+}
+
+/**
+ * The player mode the host named on the URL, or null when it named none (a
+ * connected player on a live game gets no flag, only the posted message) or
+ * the page is not framed by Net Forge.
+ */
+export function namedPlayer(params: URLSearchParams): PlayerMode | null {
+  if (params.get("host") !== "netnet") return null;
+  const player = params.get("player");
+  return player === "earning" || player === "guest" || player === "play" ? player : null;
+}
+
+/**
+ * The store's note under its prices, from one source of truth. Once the host
+ * has named the player mode (on the URL or in a message), that mode decides,
+ * exactly as it does for the coin box: a live game never calls its coins play
+ * money. Standalone play, or a host that names no mode (the studio's drafts),
+ * keeps the room's own word (`welcome.earnLive`).
+ */
+export function storeNote(hostMode: PlayerMode | null, earnLive: boolean, symbol: string): string {
+  if (hostMode === "play") return "Play money until launch";
+  if (hostMode === "guest") return `Connect a wallet to earn ${symbol}`;
+  if (hostMode === "earning") return "";
+  return earnLive ? "" : "Play money until launch";
+}
+
+/** A host message, checked: anything else is ignored. */
+export function playerFrom(data: unknown): PlayerMode | null {
+  if (typeof data !== "object" || data === null) return null;
+  const m = data as Record<string, unknown>;
+  if (m["kind"] !== "netnet-kit" || m["type"] !== "player") return null;
+  const mode = m["mode"];
+  return mode === "earning" || mode === "guest" || mode === "play" ? mode : null;
+}
+
+/** Calls `cb` with each player mode the host posts. Framed pages only. */
+export function onHostPlayer(flags: HostFlags, cb: (mode: PlayerMode) => void): void {
+  if (!flags.framed || window.parent === window) return;
+  window.addEventListener("message", (e: MessageEvent<unknown>) => {
+    if (e.source !== window.parent) return;
+    const mode = playerFrom(e.data);
+    if (mode) cb(mode);
+  });
+}
+
+/** Tells the host the game is up, so it can post the current player mode. */
+export function postReady(flags: HostFlags): void {
+  if (!flags.framed || window.parent === window) return;
+  // The host's origin is not known to an opaque-origin frame; the message is one public flag.
+  window.parent.postMessage({ kind: "netnet-kit", type: "ready" }, "*");
+}

package/client/hud.ts

@@ -0,0 +1,217 @@
+/**
+ * SKYLEDGE's HUD (plain DOM over the canvas): the course and everyone's
+ * place along it, your coins, the race clock and your place, the countdown,
+ * the standings, the results with what this round paid, the coin box and
+ * toasts. Text updates are throttled to ten a second.
+ */
+import { PF } from "@netforge/engine/game";
+import type { CompiledGame, RaceInfo } from "@netforge/engine/game";
+import { BOT_PLAYER_BASE, platformCoinCount } from "@netforge/engine-sim";
+import { RULE_NAMES } from "./names.js";
+import type { SceneEntity } from "./scene.js";
+import { climberColor } from "./scene.js";
+
+const $ = <T extends HTMLElement = HTMLElement>(id: string): T => {
+  const el = document.getElementById(id);
+  if (!el) throw new Error(`missing #${id}`);
+  return el as T;
+};
+const ord = (n: number) => `${n}${n % 10 === 1 && n % 100 !== 11 ? "st" : n % 10 === 2 && n % 100 !== 12 ? "nd" : n % 10 === 3 && n % 100 !== 13 ? "rd" : "th"}`;
+const clockText = (s: number) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(2, "0")}`;
+const nameOf = (id: number, self: number) => (id === self ? "You" : id >= BOT_PLAYER_BASE ? `Climber ${id - BOT_PLAYER_BASE + 1}` : `Player ${id}`);
+
+export interface HudActions {
+  invite(): void;
+  toggleStore(): void;
+  toggleSound(): boolean;
+  ready(): void;
+}
+
+export class Hud {
+  private symbol = "";
+  private mode: "earning" | "guest" | "play" = "earning";
+  private lastText = 0;
+  private toastTimer = 0;
+  private lastRun = -1;
+  private readonly earnedThisRun = new Map<string, number>();
+  private readonly markers = new Map<number, HTMLElement>();
+  private lastCount = -1;
+  private lastAnnounce = 0;
+
+  constructor(
+    private readonly game: CompiledGame,
+    private readonly self: number,
+    actions: HudActions,
+  ) {
+    $("invite").addEventListener("click", () => actions.invite());
+    $("store-btn").addEventListener("click", () => actions.toggleStore());
+    $("store-close").addEventListener("click", () => actions.toggleStore());
+    $("ready").addEventListener("click", () => actions.ready());
+    $("sound").addEventListener("click", (e) => {
+      const muted = actions.toggleSound();
+      (e.currentTarget as HTMLElement).textContent = muted ? "Sound off" : "Sound on";
+    });
+  }
+
+  coin(name: string, symbol: string, logo: string | null): void {
+    this.symbol = symbol;
+    const img = $<HTMLImageElement>("coin-logo");
+    if (logo) {
+      img.src = logo;
+      img.alt = name;
+      img.hidden = false;
+    } else img.hidden = true;
+    $("coin-name").textContent = name;
+  }
+
+  title(name: string): void {
+    $("title").textContent = name.toUpperCase();
+  }
+
+  /** What play pays the person at the screen (guest: "not earning"; play money: a caption). */
+  player(mode: "earning" | "guest" | "play"): void {
+    this.mode = mode;
+    const box = $("coin-box");
+    box.classList.toggle("guest", mode === "guest");
+    box.classList.toggle("play", mode === "play");
+    box.title = mode === "guest" ? `Connect a wallet to earn ${this.symbol}` : mode === "play" ? `${this.symbol} has not launched: coins are play money` : "";
+    this.lastText = 0;
+  }
+
+  private balanceText(balance: number): string {
+    if (this.mode === "guest") return `${this.symbol} · not earning`;
+    return `${Math.floor(balance).toLocaleString("en-US")} ${this.symbol}`;
+  }
+
+  earned(rule: string, units: number): void {
+    this.earnedThisRun.set(rule, (this.earnedThisRun.get(rule) ?? 0) + units);
+    const pay = this.game.manifest.earnRules.get(rule)?.pay ?? 0;
+    const name = RULE_NAMES[rule] ?? rule;
+    this.toast(this.mode === "guest" ? `${name}  Connect to earn ${pay * units} ${this.symbol}` : `${name}  +${pay * units} ${this.symbol}`);
+  }
+
+  toast(text: string): void {
+    const t = $("toast");
+    t.textContent = text;
+    t.classList.add("show");
+    clearTimeout(this.toastTimer);
+    this.toastTimer = window.setTimeout(() => t.classList.remove("show"), 2400);
+  }
+
+  /** Every frame: `self` our predicted climber, `everyone` all climbers in view. */
+  update(now: number, self: SceneEntity | undefined, everyone: readonly SceneEntity[], run: (RaceInfo & { level?: string | null }) | null, balance: number, buffs: string): void {
+    if (run && run.run !== this.lastRun) {
+      this.lastRun = run.run;
+      this.earnedThisRun.clear();
+    }
+    // The countdown is big and immediate: update it every frame.
+    const count = $("count");
+    const counting = run?.phase === "countdown";
+    count.classList.toggle("show", counting);
+    if (counting && run && run.countdown !== this.lastCount) {
+      this.lastCount = run.countdown;
+      $("count-n").textContent = run.countdown > 0 ? String(run.countdown) : "GO";
+      $("count-sub").textContent = run.level ? run.level.toUpperCase() : "";
+    }
+    // A system's announce() (and the finish window) shows as a toast.
+    if (run?.announce && run.announce.id !== this.lastAnnounce) {
+      this.lastAnnounce = run.announce.id;
+      this.toast(run.announce.text);
+    }
+    if (now - this.lastText < 100) return;
+    this.lastText = now;
+    $("coin-balance").textContent = this.balanceText(balance);
+    $("buffs").textContent = buffs;
+    const platformer = this.game.platformer;
+    const course = run?.course ?? 0;
+    const level = platformer?.levels[course];
+    $("course").textContent = run?.level ?? platformer?.names[course] ?? "";
+    if (self && level) {
+      const n = platformCoinCount({ coinsLo: self.values[PF.coinsLo] ?? 0, coinsHi: self.values[PF.coinsHi] ?? 0 });
+      $("coin-count").textContent = String(n);
+      $("coin-total").textContent = `/ ${level.coins.length}`;
+    }
+    // Everyone's place along the course: a marker on the track bar.
+    const track = $("track");
+    const seen = new Set<number>();
+    for (const p of run?.players ?? []) {
+      seen.add(p.id);
+      let m = this.markers.get(p.id);
+      if (!m) {
+        m = document.createElement("i");
+        m.style.setProperty("--c", `#${climberColor(p.id).toString(16).padStart(6, "0")}`);
+        track.append(m);
+        this.markers.set(p.id, m);
+      }
+      m.classList.toggle("me", p.id === this.self);
+      m.style.left = `${Math.min(100, p.progress * 100).toFixed(1)}%`;
+    }
+    for (const [id, m] of this.markers) {
+      if (seen.has(id)) continue;
+      m.remove();
+      this.markers.delete(id);
+    }
+    // Clock and place.
+    const timer = $("timer");
+    if (run) {
+      const left = run.left;
+      timer.textContent = run.phase === "racing" ? (left !== null ? clockText(left) : clockText(run.seconds)) : run.phase === "countdown" ? "READY" : "DONE";
+      timer.classList.toggle("low", run.phase === "racing" && left !== null && left <= 15);
+      const me = run.players.find((p) => p.id === this.self);
+      $("place").textContent = me ? (me.place !== null ? `FINISHED ${ord(me.place).toUpperCase()} · ${me.time?.toFixed(2)} s` : `${ord(me.rank).toUpperCase()} OF ${run.players.length}`) : "";
+      // Standings.
+      const board = $("board");
+      board.replaceChildren(
+        ...run.players.slice(0, 8).map((p) => {
+          const li = document.createElement("li");
+          if (p.id === this.self) li.className = "me";
+          li.style.setProperty("--c", `#${climberColor(p.id).toString(16).padStart(6, "0")}`);
+          li.innerHTML = `<em></em><span class="dot"></span><span></span><b></b>`;
+          (li.children[0] as HTMLElement).textContent = String(p.rank);
+          (li.children[2] as HTMLElement).textContent = nameOf(p.id, this.self);
+          (li.children[3] as HTMLElement).textContent = p.place !== null ? `${p.time?.toFixed(1)}s` : `${Math.round(p.progress * 100)}%`;
+          return li;
+        }),
+      );
+      this.results(run);
+    }
+    void everyone;
+  }
+
+  private results(run: RaceInfo & { level?: string | null }): void {
+    const end = $("end");
+    const show = run.phase === "results";
+    end.classList.toggle("show", show);
+    if (!show) return;
+    const me = run.players.find((p) => p.id === this.self);
+    $("end-title").textContent = me?.place === 1 ? "FIRST TO THE FLAG" : me?.place !== null && me?.place !== undefined ? `${ord(me.place).toUpperCase()} PLACE` : "OUT OF TIME";
+    $("end-board").replaceChildren(
+      ...run.players.map((p) => {
+        const li = document.createElement("li");
+        if (p.id === this.self) li.className = "me";
+        li.innerHTML = `<em></em><span></span><b></b>`;
+        (li.children[0] as HTMLElement).textContent = p.place !== null ? String(p.place) : "-";
+        (li.children[1] as HTMLElement).textContent = nameOf(p.id, this.self);
+        (li.children[2] as HTMLElement).textContent = p.time !== null ? `${p.time.toFixed(2)} s` : "did not finish";
+        return li;
+      }),
+    );
+    const mine = run.coins.find((c) => c.id === this.self)?.rules ?? [...this.earnedThisRun].map(([rule, units]) => ({ rule, units }));
+    $("end-earned").replaceChildren(
+      ...mine.map((r) => {
+        const li = document.createElement("li");
+        if (this.mode === "guest") li.className = "guest";
+        const pay = (this.game.manifest.earnRules.get(r.rule)?.pay ?? 0) * r.units;
+        li.innerHTML = `<span></span><b></b>`;
+        (li.children[0] as HTMLElement).textContent = RULE_NAMES[r.rule] ?? r.rule;
+        (li.children[1] as HTMLElement).textContent = this.mode === "guest" ? `${pay} ${this.symbol} (connect to earn)` : `+${pay} ${this.symbol}`;
+        return li;
+      }),
+    );
+    $("end-next").textContent = run.nextRunIn !== null ? `NEXT COURSE IN ${run.nextRunIn}` : "";
+  }
+
+  stats(text: string): void {
+    $("stats").textContent = text;
+  }
+}