@netforge/template-racer 0.0.0-stage → 0.2.0

package/AGENTS.md

@@ -0,0 +1,65 @@
+# Extending TORQUEBAY
+
+TORQUEBAY is the kart racer 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. 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: "racer", style, tracks: [...] })` with 1 to 8 tracks.
+- No `weapon()`, `director()`, `keeper()` or enemy prefabs.
+- A track has 4 to 64 control points at least 6 m apart and is at least 200 m round.
+- Upgrades raise one of: speed (top speed), haste (drift charge rate), might (boost length), armor (grass and wall losses), magnet (coin reach, m).
+- 4 players plus seat bots must all finish a race, 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: turbo, tuned_engine, soft_tyres, skin_flame and skin_chrome (with the paints' grants: flame 1, chrome 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 (races every playtest driver finished), scorers, deaths (hard wall hits), earned by rule, softlock and ms per tick.
+
+## Play locally
+
+```sh
+mkdir -p my-game/src && cd my-game
+npm init -y && npm install @netforge/kit-play @netforge/engine @netforge/template-racer
+cp node_modules/@netforge/template-racer/src/game.ts src/
+echo '{"template":"racer"}' > 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; tune the tracks and handling instead.
+
+## Docs
+
+https://forge.netnet.capital/docs/templates/racer

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,33 @@
+@netforge/template-racer (TORQUEBAY)
+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 Kenney (Car Kit: the
+  karts and trucks; Nature Kit: trees; City Kit Commercial: buildings;
+  Space Kit: barrels) and Quaternius
+  (via Poly Pizza: the coin), 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.
+- The road, kerbs, barriers, boost pads, the start line and the fallback
+  kart (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 kart racing genre's general mechanics (laps, drifting to charge a
+  boost, boost pads, coins, a grid of rivals). Mechanics, not expression;
+  no track, vehicle, character or text was copied from any game.
+- Arcade vehicle handling (forward and sideways velocity, grip, drift) as
+  described in common public write-ups on arcade car physics. Implemented
+  from scratch in engine-sim src/kart.ts.

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @netforge/template-racer
 
-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 kart racer game template for Net Forge: up to 8 players on harbour circuits, with seat bots filling the grid (TORQUEBAY).
+
+Hold the throttle, drift through the bends to charge a mini-turbo (release it for the boost), hit the boost pads, collect coins (each one held adds 1% top speed, up to ten) and keep off the grass. A round is one race, and the next round runs another circuit.
+
+The simulation is the engine's kart mode: arcade vehicle physics on a 1/1024 grid at 60 Hz. A held drift charges a mini-turbo in three tiers. Laps count through four quarter checkpoints in order. A client predicts its own kart, and kart bumps run only on the room host, corrected by the next snapshot.
+
+The client streams the track: it builds road, kerbs, barriers and scenery in chunks of about 40 m within 170 m of the camera and drops chunks behind.
+
+The race runner owns rounds (countdown, race, results). `player.finished` pays your own finish; `race.won` and `race.podium` pay only with another person in the round. Seat bots drive the racing line, pass the kart ahead, hold drifts through long bends and never earn.
+
+## Install
+
+```sh
+npm install @netforge/template-racer
+```
+
+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-racer
+cp node_modules/@netforge/template-racer/src/game.ts src/
+echo '{"template":"racer"}' > 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
+
+Races are three laps and six seat bots fill the grid. Run a shorter race with a smaller field on the Harbour Loop:
+
+```ts
+players: { prefab: "style.lowpoly.kart_a", max: 8, bots: 4 },
+// in tracks[0], the Harbour Loop:
+laps: 2,
+```
+
+Save `src/game.ts` and run `npx kit-play` again.
+
+## Files
+
+| Path | What |
+|---|---|
+| `src/game.ts` | The game, declarations only: three circuits, round upgrades, earn rules, stake, store. |
+| `src/manifest.ts` | Loads and compiles the game; `racerAdapter()` and `racerGame()` 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 paint jobs (300, 500) and the bumper kit gear (120). |
+| `client/` | The browser client: chase camera, a streamed track, HUD with minimap, keyboard, gamepad and touch, game feel. |
+| `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: W or Up accelerate, S or Down brake, A D or arrows steer, hold Space or Shift through a bend to drift (release for the boost), R or Enter readies the next race. 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/racer
+- `llms.txt` and `llms-full.txt` in this package (also exported as `@netforge/template-racer/llms.txt` and `@netforge/template-racer/llms-full.txt`)
+
+## License
+
+MIT. See `LICENSE` and `NOTICE`.

package/client/audio.ts

@@ -0,0 +1,26 @@
+/**
+ * TORQUEBAY's sound cues on the engine's FeelAudio. Coins, boosts and bumps
+ * play the asset library's CC0 samples (KART_SAMPLES); the drift screech and
+ * the countdown stay synthesized. Every cue keeps a synth fallback.
+ */
+import type { FeelAudio } from "@netforge/engine/runtime";
+
+/** Cue name -> library sound id (soundBank's `cues` overrides). */
+export const KART_SAMPLES: Readonly<Record<string, string>> = {
+  coin: "audio.sfx.coin",
+  boost: "audio.sfx.dash",
+  bump: "audio.sfx.impact",
+  lap: "audio.sfx.confirm",
+  finish: "audio.sfx.level_up",
+};
+
+export function defineKartCues(a: FeelAudio): void {
+  a.define("coin", { wave: "triangle", f0: 1320, f1: 1980, ms: 90, gain: 0.45 }, { minGapMs: 30, voices: 3, pitchVar: 0.06 });
+  a.define("drift", { wave: "sawtooth", f0: 520, f1: 470, ms: 260, gain: 0.25 }, { minGapMs: 200, voices: 1, pitchVar: 0.05 });
+  a.define("boost", { wave: "sawtooth", f0: 180, f1: 900, ms: 320, gain: 0.5 }, { minGapMs: 150, voices: 1 });
+  a.define("bump", { wave: "square", f0: 140, f1: 50, ms: 140, gain: 0.55 }, { minGapMs: 120, voices: 2 });
+  a.define("lap", { wave: "triangle", f0: 660, f1: 990, ms: 180, gain: 0.6 }, { minGapMs: 300, 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("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,27 @@
+/**
+ * Library models the TORQUEBAY 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 drive the other karts of the set. */
+export const BOT_MODELS: readonly string[] = ["style.lowpoly.kart_b", "style.lowpoly.kart_c", "style.lowpoly.kart_d", "style.lowpoly.kart_e"];
+export const COIN_MODEL = "style.lowpoly.coin";
+/** Karts are drawn this tall, m. */
+export const KART_HEIGHT = 1.1;
+/** The kart models face -z; the scene drives along +x. */
+export const MODEL_YAW = -Math.PI / 2;
+
+/** Scenery past the barriers: [library id, height m, every n samples (~2 m each)]. */
+export const SCENERY: readonly (readonly [string, number, number])[] = [
+  ["style.lowpoly.tree_palm", 6, 7],
+  ["style.lowpoly.tree_oak", 5, 9],
+  ["style.lowpoly.building_c", 12, 22],
+  ["style.lowpoly.barrels", 1.3, 11],
+  ["style.lowpoly.truck_flat", 2.6, 19],
+];
+
+/** The pixel style's own karts (the low-poly karts have no pixel twins). */
+export const PIXEL_PLAYER = "style.pixel.kart";
+export const PIXEL_BOTS: readonly string[] = ["style.pixel.buggy", "style.pixel.sports_car", "style.pixel.car", "style.pixel.taxi"];
+
+export const SCENE_MODELS: readonly string[] = [...BOT_MODELS, COIN_MODEL, ...SCENERY.map(([id]) => id), PIXEL_PLAYER, ...PIXEL_BOTS];

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,257 @@
+/**
+ * TORQUEBAY's HUD (plain DOM and one canvas over the scene): lap and place,
+ * the race clock, a minimap of the circuit with every kart, speed, the drift
+ * charge, the countdown, standings, results with what this race paid, the
+ * coin box and toasts. Text updates are throttled to ten a second.
+ */
+import { KF } from "@netforge/engine/game";
+import type { CompiledGame, RaceInfo } from "@netforge/engine/game";
+import { BOT_PLAYER_BASE, kartCoinCount } from "@netforge/engine-sim";
+import type { KartTrack } from "@netforge/engine-sim";
+import { RULE_NAMES } from "./names.js";
+import type { SceneEntity } from "./scene.js";
+import { kartColor } 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 ? `Driver ${id - BOT_PLAYER_BASE + 1}` : `Player ${id}`);
+const css = (c: number) => `#${c.toString(16).padStart(6, "0")}`;
+
+export interface HudActions {
+  invite(): void;
+  toggleStore(): void;
+  toggleSound(): boolean;
+  ready(): void;
+}
+
+type Info = RaceInfo & { level?: string | null; laps?: number };
+
+export class Hud {
+  private symbol = "";
+  private mode: "earning" | "guest" | "play" = "earning";
+  private lastText = 0;
+  private toastTimer = 0;
+  private lastRun = -1;
+  private lastCount = -1;
+  private lastAnnounce = 0;
+  private readonly earnedThisRun = new Map<string, number>();
+  private mapTrack: KartTrack | null = null;
+  private mapBox = { minX: 0, minZ: 0, scale: 1 };
+
+  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();
+  }
+
+  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: our predicted kart, every kart in view, the run info, the drawn track. */
+  update(now: number, self: SceneEntity | undefined, everyone: readonly SceneEntity[], run: Info | null, balance: number, buffs: string, track: KartTrack | null): void {
+    if (run && run.run !== this.lastRun) {
+      this.lastRun = run.run;
+      this.earnedThisRun.clear();
+    }
+    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() : "";
+    }
+    if (run?.announce && run.announce.id !== this.lastAnnounce) {
+      this.lastAnnounce = run.announce.id;
+      this.toast(run.announce.text);
+    }
+    // The drift charge bar and the speed read every frame.
+    if (self) {
+      const flags = self.values[KF.flags] ?? 0;
+      const charge = (self.values[KF.timers] ?? 0) & 0xfff;
+      const drift = $("drift");
+      drift.classList.toggle("on", (flags & 1) !== 0);
+      const bar = drift.firstElementChild as HTMLElement | null;
+      if (bar) {
+        bar.style.width = `${Math.min(100, (charge / 120) * 100).toFixed(0)}%`;
+        bar.style.setProperty("--c", charge >= 120 ? "#d16bff" : charge >= 72 ? "#ffa53a" : charge >= 33 ? "#5fc8ff" : "#bbbbbb");
+      }
+      const v = Math.hypot((self.values[KF.vx] ?? 0) / 1024, (self.values[KF.vz] ?? 0) / 1024);
+      $("kmh").textContent = String(Math.round(v * 3.6 * 1.6));
+    }
+    this.drawMap(track, self, everyone);
+    if (now - this.lastText < 100) return;
+    this.lastText = now;
+    $("coin-balance").textContent = this.balanceText(balance);
+    $("buffs").textContent = buffs;
+    $("course").textContent = run?.level ?? "";
+    const laps = run?.laps ?? 3;
+    if (self && track) {
+      const lap = (((self.values[KF.track] ?? 0) >>> 16) & 0xff) + 1;
+      $("lap").textContent = `LAP ${Math.min(laps, lap)}/${laps}`;
+      $("coin-count").textContent = String(kartCoinCount({ coinsLo: self.values[KF.coinsLo] ?? 0, coinsHi: self.values[KF.coinsHi] ?? 0 }));
+      $("coin-total").textContent = `/ ${track.coinAt.length}`;
+    }
+    const timer = $("timer");
+    if (run) {
+      const left = run.left;
+      timer.textContent = run.phase === "racing" ? 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 ? `${ord(me.place).toUpperCase()}` : `${ord(me.rank).toUpperCase()}/${run.players.length}`) : "";
+      $("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", css(kartColor(p.id)));
+          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` : `L${Math.min(laps, Math.floor(p.progress * laps) + 1)}`;
+          return li;
+        }),
+      );
+      this.results(run);
+    }
+  }
+
+  /** The circuit as a line and every kart as a dot (ours larger). */
+  private drawMap(track: KartTrack | null, self: SceneEntity | undefined, everyone: readonly SceneEntity[]): void {
+    const cv = document.getElementById("map") as HTMLCanvasElement | null;
+    const g = cv?.getContext("2d");
+    if (!cv || !g || !track) return;
+    if (track !== this.mapTrack) {
+      this.mapTrack = track;
+      let minX = Infinity;
+      let maxX = -Infinity;
+      let minZ = Infinity;
+      let maxZ = -Infinity;
+      for (let i = 0; i < track.count; i++) {
+        minX = Math.min(minX, track.x[i] ?? 0);
+        maxX = Math.max(maxX, track.x[i] ?? 0);
+        minZ = Math.min(minZ, track.z[i] ?? 0);
+        maxZ = Math.max(maxZ, track.z[i] ?? 0);
+      }
+      const scale = (cv.width - 40) / Math.max(maxX - minX, maxZ - minZ, 1);
+      this.mapBox = { minX: minX - 20 / scale, minZ: minZ - 20 / scale, scale };
+    }
+    const { minX, minZ, scale } = this.mapBox;
+    const px = (x: number) => (x - minX) * scale;
+    const pz = (z: number) => (z - minZ) * scale;
+    g.clearRect(0, 0, cv.width, cv.height);
+    g.lineJoin = "round";
+    g.strokeStyle = "rgba(255,255,255,0.85)";
+    g.lineWidth = 9;
+    g.beginPath();
+    for (let i = 0; i <= track.count; i++) {
+      const k = i % track.count;
+      if (i === 0) g.moveTo(px(track.x[k] ?? 0), pz(track.z[k] ?? 0));
+      else g.lineTo(px(track.x[k] ?? 0), pz(track.z[k] ?? 0));
+    }
+    g.stroke();
+    for (const e of [...everyone, ...(self ? [self] : [])]) {
+      const mine = e === self;
+      g.fillStyle = css(kartColor(e.owner));
+      g.beginPath();
+      g.arc(px((e.values[KF.x] ?? 0) / 1024), pz((e.values[KF.z] ?? 0) / 1024), mine ? 11 : 7, 0, Math.PI * 2);
+      g.fill();
+      if (mine) {
+        g.strokeStyle = "#fff";
+        g.lineWidth = 3;
+        g.stroke();
+      }
+    }
+  }
+
+  private results(run: Info): 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 ? "CHEQUERED FLAG: FIRST" : me?.place !== null && me?.place !== undefined ? `${ord(me.place).toUpperCase()} PLACE` : "DID NOT FINISH";
+    $("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 RACE IN ${run.nextRunIn}` : "";
+  }
+
+  stats(text: string): void {
+    $("stats").textContent = text;
+  }
+}