@netforge/template-racer 0.0.0-stage → 0.1.0

package/client/stake.ts

@@ -0,0 +1,143 @@
+/**
+ * The buy-in run in the store panel (earn.stake, the mandatory sink loop).
+ * The player picks an amount inside the game's terms and stakes it: the Kit
+ * spends it under the reason "stake" (earned coins first, then the wallet),
+ * then the room is told. The room fixes the stake from its own ledger when
+ * the next run starts (or this one, if it only just began) and says so.
+ */
+import type { PotMessage, StakeMessage, StakeTermsView } from "@netforge/engine/net";
+import type { KitStoreBridge } from "../src/store.js";
+
+export interface StakeConn {
+  readonly welcome: { readonly stake?: StakeTermsView };
+  stake(amount?: number): void;
+  onStake(cb: (m: StakeMessage) => void): void;
+}
+
+const fmt = (n: number) => (Math.round(n * 100) / 100).toLocaleString("en-US");
+
+/** Wires #stake-amount, #stake-go and #stake-line; hides #stake-row when the game takes no stakes. */
+export function wireStake(conn: StakeConn, kit: KitStoreBridge, toast: (t: string) => void): void {
+  const row = document.getElementById("stake-row");
+  const input = document.getElementById("stake-amount") as HTMLInputElement | null;
+  const go = document.getElementById("stake-go") as HTMLButtonElement | null;
+  const line = document.getElementById("stake-line");
+  const terms = conn.welcome.stake;
+  if (!row || !input || !go || !line) return;
+  if (!terms) {
+    row.style.display = "none";
+    return;
+  }
+  const sym = kit.coins.symbol();
+  input.min = String(terms.min);
+  input.max = String(terms.max);
+  input.step = "any";
+  input.value = String(terms.min);
+  const idle = () => {
+    const a = Number(input.value) || terms.min;
+    line.textContent = `Up to ${fmt(a * terms.multiple)} ${sym} back`;
+  };
+  idle();
+  input.addEventListener("input", idle);
+  go.addEventListener("click", async () => {
+    const a = Number(input.value);
+    if (!(a >= terms.min && a <= terms.max)) return toast(`Stake ${fmt(terms.min)} to ${fmt(terms.max)} ${sym}`);
+    go.disabled = true;
+    try {
+      await kit.coins.spend(a, "stake");
+      conn.stake(a);
+    } catch {
+      toast(`Not enough ${sym}`);
+    } finally {
+      go.disabled = false;
+    }
+  });
+  conn.onStake((m) => {
+    if (m.state === "live") line.textContent = `Staked ${fmt(m.stake)}, up to ${fmt(m.ceiling ?? 0)} ${sym} this run`;
+    else if (m.state === "waiting") line.textContent = m.stake > 0 ? `Next run: ${fmt(m.stake)} ${sym}` : "Stake waits for tomorrow's cap";
+    else if (m.state === "closed") {
+      toast(`Stake ${fmt(m.stake)} ${sym}  ${fmt(m.paid ?? 0)} back${m.lost && m.lost.length > 0 ? `  ·  gear lost` : ""}`);
+      idle();
+    } else toast(m.reason === "sign in to stake" ? "Sign in to stake" : "Stake not taken");
+  });
+}
+
+/** One losable gear SKU (store.sku grants { gear, loseBelow }): a buy button and its loss line. Hides #gear-row without one. */
+export function wireGear(gear: { id: string; name: string; coins: number; loseBelow: number } | null, kit: KitStoreBridge, toast: (t: string) => void): void {
+  const row = document.getElementById("gear-row");
+  const name = document.getElementById("gear-name");
+  const line = document.getElementById("gear-line");
+  const buy = document.getElementById("gear-buy") as HTMLButtonElement | null;
+  if (!row || !name || !line || !buy) return;
+  if (!gear) {
+    row.style.display = "none";
+    return;
+  }
+  const sym = kit.coins.symbol();
+  name.textContent = gear.name;
+  line.textContent = `Staked runs only. Lost under ${Math.round(gear.loseBelow * 100)}% of a run's earn`;
+  const show = () => {
+    buy.textContent = kit.store.owns(gear.id) ? "Owned" : `${gear.coins} ${sym}`;
+    buy.disabled = kit.store.owns(gear.id);
+  };
+  show();
+  buy.addEventListener("click", async () => {
+    try {
+      await kit.store.buy(gear.id, { pay: "coins" });
+    } catch {
+      toast(`Not enough ${sym}`);
+    }
+    show();
+  });
+}
+
+/** The game's first gear SKU from its manifest, with its label. */
+export function gearOf(skus: ReadonlyMap<string, { coins?: number; grants?: unknown }>, names: Readonly<Record<string, string>>): { id: string; name: string; coins: number; loseBelow: number } | null {
+  for (const [id, s] of skus) {
+    const g = s.grants as { gear?: string; loseBelow?: number } | undefined;
+    if (g?.gear && typeof g.loseBelow === "number" && s.coins !== undefined) return { id, name: names[id] ?? id, coins: s.coins, loseBelow: g.loseBelow };
+  }
+  return null;
+}
+
+export interface PotConn {
+  readonly welcome: { readonly pot?: { readonly entry: number; readonly recycle: number } };
+  pot(): void;
+  onPot(cb: (m: PotMessage) => void): void;
+}
+
+/** The round's PvP pot: #pot-go pays the entry and tells the room; #pot-line shows the pot. Hides #pot-row without one. */
+export function wirePot(conn: PotConn, kit: KitStoreBridge, toast: (t: string) => void): void {
+  const row = document.getElementById("pot-row");
+  const go = document.getElementById("pot-go") as HTMLButtonElement | null;
+  const line = document.getElementById("pot-line");
+  const pot = conn.welcome.pot;
+  if (!row || !go || !line) return;
+  if (!pot) {
+    row.style.display = "none";
+    return;
+  }
+  const sym = kit.coins.symbol();
+  const idle = `${fmt(pot.entry)} ${sym} in. The round splits it`;
+  line.textContent = idle;
+  go.textContent = `${fmt(pot.entry)} ${sym}`;
+  go.addEventListener("click", async () => {
+    go.disabled = true;
+    try {
+      await kit.coins.spend(pot.entry, "pot");
+      conn.pot();
+    } catch {
+      toast(`Not enough ${sym}`);
+    } finally {
+      go.disabled = false;
+    }
+  });
+  conn.onPot((m) => {
+    if (m.state === "in") line.textContent = `In. Pot ${fmt(m.pot ?? m.entry)} ${sym}`;
+    else if (m.state === "waiting") line.textContent = "In the next round";
+    else if (m.state === "closed") {
+      toast(`Pot ${fmt(m.pot ?? 0)} ${sym}  ${fmt(m.paid ?? 0)} to you`);
+      line.textContent = idle;
+    } else toast(m.reason === "sign in to enter" ? "Sign in to enter" : "Not entered");
+  });
+}

package/llms.txt

@@ -0,0 +1,125 @@
+# TORQUEBAY: the racer template (NetNet game runtime, play style "racer")
+
+> Kart races for up to 8 players on harbour circuits, with seat bots filling
+> the grid. A round is one race of a few laps; the next round runs another
+> circuit. You change the game by editing src/game.ts only. The template
+> already has the kart physics (throttle, brakes, steering, grip, drift
+> mini-turbos in three tiers, boost pads, coins that raise top speed, grass,
+> barriers, kart bumps), laps through ordered checkpoints, the race clock and
+> places, bots that drive the racing line, netcode with client prediction at
+> 60 Hz, a streamed track (only the road near you is built), rendering in
+> every art style, keyboard, gamepad and touch controls, earn and the store.
+> Do not write renderers, netcode, physics or bot AI.
+
+## Files
+
+- src/game.ts: THE GAME. Declarations against @netforge/engine:
+  game(), upgrade(), system(), earn.rule(), earn.stake(), store.sku().
+- src/names.json: the title and every label players read.
+- Everything else is template machinery.
+
+## Rules the build enforces
+
+- game({ template: "racer", style: "lowpoly", 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.
+- Asset ids look like "style.lowpoly.kart_a", never URLs or paths, and must be in the asset library.
+- game({ style }) is the art style the creator picked: lowpoly, toon, ps1, pixel, voxel or handdrawn. Keep it.
+- Ids are lower_snake_case. Every game declares at least one earn.rule and one earn.stake (the buy-in run).
+- 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.
+
+## Units
+
+Seconds, metres, metres per second. The ground plane: x and z in metres.
+Tick rate 60 Hz. Default top speed 26 m/s; a kart is about 1.8 m long.
+
+## The loop
+
+Everyone lines up on a staggered grid behind the line. A 3 s countdown, then
+the race: W/Up accelerate, S/Down brake, A/D steer, hold Space or Shift
+while steering through a bend to drift (sparks turn blue, orange, then
+purple as the mini-turbo charges; release for a 0.5, 0.9 or 1.4 s boost).
+Boost pads boost; each coin held adds 1% top speed, up to 10. Grass slows,
+barriers bounce. Laps count through four quarter checkpoints in order. The
+round closes 25 s after the first person finishes (or at round.seconds);
+the results show, then the next circuit.
+
+## Building a track
+
+tracks: [{
+  name: "Harbour Loop",
+  laps: 3,
+  width: 14,                                 // asphalt, m (8 to 30)
+  points: [[0, 0], [90, 0], [150, 15], ...], // the closed centreline in driving order; a smooth curve runs through them
+  boosts: [[0.12, 0], [0.47, -0.4]],         // [lap fraction 0..1, lateral -1 (left) .. 1 (right)]
+  coins: [[0.04, 0.5], [0.046, 0.5]],        // same coordinates; each kart collects its own (at most 62)
+  verge: 4,                                  // optional grass before the barrier, m
+}]
+Rules of thumb: 500 to 900 m a lap at 14 m wide runs 25 to 40 s a lap; keep
+neighbouring points 20 m or more apart for smooth bends; a hairpin needs
+about 25 m of radius; put boosts on the exits of bends and coin rows on the
+racing line or slightly off it (a choice). Two to four laps a race.
+
+## Common changes
+
+### A new circuit
+Add a track to tracks. Circuits come one a round (the room draws one per round).
+
+### Tune the handling
+kart: { topSpeed: 30, turn: 2.6, grip: 10, driftGrip: 1.5 } (topSpeed 10-45,
+accel 8-80, turn 1-4, grip 3-20, driftGrip 0.5-6, grass 0.2-1, boostSpeed 1-1.8).
+
+### Round length and bots
+round: { seconds: 240 } (60 to 600). players.bots: 6 fills the grid up to 6
+with seat bots (0 turns them off). Bots drive the racing line, shaded by
+skill, never earn, and a win over a field of bots pays nothing extra.
+
+### Add an earn rule
+earn.rule("lap_leader", { when: "lap.completed", n: 2, pay: 3, oncePer: "run" });
+Events: player.finished (you finished the race), race.won (first, paid only
+with another person in the round), race.podium (top three, same),
+lap.completed, coin.collected, drift.boosted (a mini-turbo fired),
+drift.ultra (a full-charge one), kart.bumped (a hard wall hit),
+round.finished, run.started (unpaid), and anything you emit(). Each rule
+pays once per race per player, in coins; the room server is the referee.
+
+### Track something with a system
+system("clean_line", ({ on, emit }) => {
+  const scrapes = new Map<number, number>();
+  on("kart.bumped", (ids) => { for (const id of ids) scrapes.set(id, (scrapes.get(id) ?? 0) + 1); });
+  on("player.finished", (ids) => { const clean = ids.filter((id) => !scrapes.get(id)); if (clean.length) emit("race.clean", clean); });
+  on("run.started", (ids) => { for (const id of ids) scrapes.delete(id); });
+});
+Systems also have every, after, onTick, players(), random(), announce(text),
+upcoming(label, seconds) and end(). spawn and enemies are not part of this template.
+
+### The buy-in run (required)
+earn.stake({ min: 10, max: 100, multiple: 2 }); one top-level line. "stake" is reserved.
+
+### Losable gear (optional)
+store.sku("bumper_kit", { coins: 120, grants: { gear: "bumpers", loseBelow: 0.25 } });
+Owned in the profile, coins only; one level of its upgrade in every staked
+race; lost when that race makes less than loseBelow of its most earn.
+
+### Coins: earn and the store
+store.sku("turbo", { coins: 40 });                               // one level of the "turbo" upgrade for the race
+store.sku("skin_flame", { coins: 300, grants: { cosmetic: 1 } }); // a paint job, owned for good
+Keep the five SKUs the client is wired to (turbo, tuned_engine, soft_tyres,
+skin_flame, skin_chrome) at their prices, with the paints' grants (flame 1,
+chrome 2). PvP pots are not part of this template.
+
+### Change the karts (the asset library)
+players: { prefab: "style.lowpoly.race_car", ... } (any vehicle: kart_a..e,
+race_car, race_car_future, buggy-like speeder_a..c). Seat bots drive
+kart_b..e; the pixel style draws its own kart sprites.
+
+## Test
+
+engine.test.run({ ticks: 60 * 240, bots: 4, assert: [...] }) runs races on
+the server sim with 4 playtest drivers plus seat bots and reports rounds
+(wave), runs.won (races every playtest driver finished), scorers (drivers
+that finished at least once), deaths (hard wall hits), earned by rule,
+softlock and ms per tick.

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@netforge/template-racer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "TORQUEBAY: a racer template of the NetNet game runtime, kart races on harbour circuits with drift mini-turbos, boost pads, coins and laps at 60 Hz, a streamed track and seat-filling bots. The game module, its browser client and its playtest bots.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/manifest.ts",
+    "./store": "./src/store.ts"
+  },
+  "files": [
+    "src",
+    "client",
+    "!client/vite.config.ts",
+    "llms.txt",
+    "README.md",
+    "NOTICE",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/netnetdev/net-forge.git",
+    "directory": "packages/template-racer"
+  },
+  "homepage": "https://github.com/netnetdev/net-forge/tree/main/packages/template-racer#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "three": "0.186.1",
+    "@netforge/asset-library": "0.1.0",
+    "@netforge/engine": "0.1.0",
+    "@netforge/engine-sim": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "@types/three": "0.186.0",
+    "tsx": "4.23.0",
+    "typescript": "5.8.3",
+    "vite": "6.4.3",
+    "vitest": "3.2.7"
+  },
+  "bugs": {
+    "url": "https://github.com/netnetdev/net-forge/issues"
+  },
+  "scripts": {
+    "build": "node ../engine/scripts/fresh-dist.mjs && vite build --config client/vite.config.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "dev": "vite --config client/vite.config.ts",
+    "preview": "vite preview --config client/vite.config.ts"
+  }
 }

package/src/game.ts

@@ -0,0 +1,96 @@
+/**
+ * TORQUEBAY: the racer template (play style "racer").
+ * Up to eight karts race laps around harbour circuits: hold the throttle,
+ * drift through the bends to charge a mini-turbo (release for the boost),
+ * hit the boost pads, collect coins (every coin you hold adds 1% top speed,
+ * up to ten) and keep off the grass. A round is one race; the next round runs
+ * another circuit. Seat bots fill the grid so a race always has a field.
+ *
+ * This file is the whole game as the model writes it: declarations only,
+ * against the typed API in @netforge/engine. Everything else (the kart
+ * physics, netcode, renderer, track streaming, bots, referee) is the
+ * template's machinery.
+ *
+ * Track coordinates are metres on the ground (x right, z down the screen's
+ * map). points is the closed centreline in driving order; boosts and coins
+ * are [lap fraction 0..1, lateral -1..1 of the half width].
+ */
+import { earn, game, store, system, upgrade } from "@netforge/engine";
+
+/** Coins in a row: n coins from lap fraction f, `gap` of a lap apart, at one lateral. */
+const coinRow = (f: number, lateral: number, n: number, gap = 0.006): [number, number][] => Array.from({ length: n }, (_, i) => [f + i * gap, lateral]);
+
+export default game({
+  template: "racer",
+  style: "lowpoly",
+  tickRate: 60,
+  places: { harbour: { chunks: "places/harbour", spawn: [0, 0, 0] } },
+  players: { prefab: "style.lowpoly.kart_a", max: 8, bots: 6 },
+  round: { seconds: 240 },
+  tracks: [
+    {
+      name: "Harbour Loop",
+      laps: 3,
+      width: 14,
+      points: [[0, 0], [90, 0], [150, 15], [175, 65], [150, 120], [90, 135], [50, 175], [-20, 190], [-85, 160], [-110, 100], [-90, 35]],
+      boosts: [[0.12, 0], [0.47, -0.4], [0.78, 0.4]],
+      coins: [...coinRow(0.04, 0.5, 5), ...coinRow(0.3, -0.5, 5), ...coinRow(0.6, 0, 5), ...coinRow(0.88, -0.3, 5)],
+    },
+    {
+      name: "Crane Yard",
+      laps: 3,
+      width: 13,
+      points: [[0, 0], [70, -10], [120, 10], [130, 60], [95, 85], [60, 70], [30, 95], [45, 140], [5, 175], [-55, 160], [-75, 105], [-50, 60], [-75, 20]],
+      boosts: [[0.08, 0], [0.38, 0.3], [0.7, -0.3]],
+      coins: [...coinRow(0.15, 0, 5), ...coinRow(0.45, 0.4, 5), ...coinRow(0.62, -0.4, 5), ...coinRow(0.85, 0, 5)],
+    },
+    {
+      name: "Lighthouse Run",
+      laps: 2,
+      width: 15,
+      points: [[0, 0], [120, -15], [200, 10], [235, 70], [210, 140], [140, 170], [80, 150], [40, 190], [-30, 210], [-95, 175], [-115, 105], [-80, 40]],
+      boosts: [[0.05, 0], [0.25, 0.35], [0.5, -0.35], [0.8, 0]],
+      coins: [...coinRow(0.1, -0.4, 6), ...coinRow(0.35, 0.4, 6), ...coinRow(0.66, 0, 6), ...coinRow(0.9, 0.3, 6)],
+    },
+  ],
+});
+
+// Round upgrades sold in the store (one level each, for the race). Racer upgrades raise speed
+// (top speed), haste (drift charge), might (boost length), armor (grass and wall losses) or magnet (coin reach).
+upgrade("turbo", { stat: "might", step: 0.25, maxLevel: 1 });
+upgrade("tuned_engine", { stat: "speed", step: 0.05, maxLevel: 1 });
+upgrade("soft_tyres", { stat: "haste", step: 0.3, maxLevel: 1 });
+upgrade("bumpers", { stat: "armor", step: 0.3, maxLevel: 1 });
+
+// A clean race: finish without scraping a wall hard.
+system("clean_line", ({ on, emit }) => {
+  const scrapes = new Map<number, number>();
+  on("kart.bumped", (ids) => {
+    for (const id of ids) scrapes.set(id, (scrapes.get(id) ?? 0) + 1);
+  });
+  on("player.finished", (ids) => {
+    const clean = ids.filter((id) => (scrapes.get(id) ?? 0) === 0);
+    if (clean.length > 0) emit("race.clean", clean);
+  });
+  on("run.started", (ids) => {
+    for (const id of ids) scrapes.delete(id);
+  });
+});
+
+// Earn (mandatory). Pays the game's coins (1 coin = 1 token), once per race each.
+// Seat bots never earn, and winning a field of bots pays nothing extra. Values are PLACEHOLDER.
+earn.rule("hot_lap", { when: "drift.boosted", n: 3, pay: 4, oncePer: "run" });
+earn.rule("chequered", { when: "player.finished", n: 1, pay: 10, oncePer: "run" });
+earn.rule("clean_line", { when: "race.clean", n: 1, pay: 12, oncePer: "run" });
+earn.rule("pole_to_flag", { when: "race.won", n: 1, pay: 25, oncePer: "run" });
+// Buy-in run (the mandatory sink loop). PLACEHOLDER.
+earn.stake({ min: 10, max: 100, multiple: 2 });
+
+// Store (the Kit), priced in coins: round upgrades and two paint jobs owned for good.
+store.sku("turbo", { coins: 40 });
+store.sku("tuned_engine", { coins: 40 });
+store.sku("soft_tyres", { coins: 60 });
+store.sku("skin_flame", { coins: 300, grants: { cosmetic: 1 } });
+store.sku("skin_chrome", { coins: 500, grants: { cosmetic: 2 } });
+// Losable gear: bumpers in every staked race, lost when that race makes less than loseBelow of its most earn. PLACEHOLDER.
+store.sku("bumper_kit", { coins: 120, grants: { gear: "bumpers", loseBelow: 0.25 } });

package/src/manifest.ts

@@ -0,0 +1,44 @@
+/**
+ * Loads the game module once per process and compiles it. The room server,
+ * the client, the bots and the tests all start here.
+ */
+import { collectManifest, compileGame, kartAdapter } from "@netforge/engine/game";
+import type { CompiledGame, CompiledRacer, KartRoomWorld, RaceRunnerOptions } from "@netforge/engine/game";
+import type { SimAdapter } from "@netforge/engine/net";
+import type { InputCommand } from "@netforge/engine-sim";
+import "./game.js";
+
+/** Content version: bump with any change to game.ts (hot swap compares it). */
+export const GAME_VERSION = "torquebay-0.1.0";
+export const GAME_NAME = "torquebay";
+/** Room template (as the Net Forge room server names it) and place used by the client and the bots. */
+export const TEMPLATE = "racer";
+export const PLACE = "harbour";
+
+const MANIFEST = collectManifest();
+let compiled: CompiledGame | null = null;
+
+/** The compiled game (tracks, handling, upgrades). */
+export function racerGame(): CompiledGame & { readonly racer: CompiledRacer } {
+  compiled ??= compileGame(MANIFEST);
+  if (!compiled.racer) throw new Error('TORQUEBAY: game.ts must declare template "racer"');
+  return compiled as CompiledGame & { readonly racer: CompiledRacer };
+}
+
+/** The SimAdapter for this game. `runner` options are server-side timing overrides (tests). */
+export function racerAdapter(runner?: RaceRunnerOptions): SimAdapter<KartRoomWorld, InputCommand> {
+  const g = racerGame();
+  return kartAdapter({
+    name: GAME_NAME,
+    version: GAME_VERSION,
+    manifest: g.manifest,
+    compiled: g.racer,
+    tickRate: g.tickRate,
+    bots: g.bots,
+    roundSeconds: g.round?.seconds ?? null,
+    ...(runner ? { runner } : {}),
+  });
+}
+
+/** Cosmetic ids for store SKUs (0 is the kart's own paint). */
+export const COSMETICS: Readonly<Record<string, number>> = { skin_flame: 1, skin_chrome: 2 };

package/src/store.ts

@@ -0,0 +1,109 @@
+/**
+ * Store hooks (the Coins model): every
+ * game has coins, 1 coin = 1 game token, shown under the token's own name,
+ * symbol and logo. TORQUEBAY sells three round upgrades (a store command
+ * named after the upgrade grants one level for the rest of the round) and
+ * two cosmetic finishes (permanent), all priced in coins.
+ *
+ * `KitStoreBridge` is the slice of @netforge/kit's `Kit` this game
+ * calls, with the Kit's own names (`kit.coins.*`, `kit.store.owns/buy`), so
+ * the real Kit drops in unchanged. Until a game's token is live `mockKit()`
+ * stands in, in memory. Earned coins are spent first (off chain, no wallet
+ * prompt), then the wallet, exactly as the Kit does.
+ */
+export interface KitStoreBridge {
+  readonly store: {
+    owns(id: string): boolean;
+    count(id: string): number;
+    buy(id: string, opts?: { pay?: "usdg" | "token" | "coins" }): Promise<unknown>;
+  };
+  readonly coins: {
+    /** The token's own name, symbol and logo (its metadata). Never a generic "COIN". */
+    name(): string;
+    symbol(): string;
+    logo(): string | null;
+    /** Whole coins: earned (unclaimed) plus the wallet. */
+    balance(): number;
+    /** Earned first, then the wallet. `key` proves the paid room command (sent as the command's `proof`). */
+    spend(amount: number, reason: string): Promise<{ key: string | null }>;
+  };
+}
+
+/** Coin prices the client is wired to (they match store.sku(...) in game.ts; the generator's gate keeps them). */
+export const COIN_PRICES = { turbo: 40, tuned_engine: 40, soft_tyres: 60, skin_flame: 300, skin_chrome: 500 } as const;
+export type SkuId = keyof typeof COIN_PRICES;
+/** Round upgrades: spent, applied by the room for the rest of the round. */
+export const UPGRADE_SKUS = ["turbo", "tuned_engine", "soft_tyres"] as const;
+/** Cosmetic finishes: bought once, owned for good. */
+export const COSMETIC_SKUS = ["skin_flame", "skin_chrome"] as const;
+
+/** The template's own coin, as its token metadata names it until a creator renames it. */
+export const TORQ_COIN = {
+  name: "Torq",
+  symbol: "TORQ",
+  logo: "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Ccircle cx='16' cy='16' r='15' fill='%23ff5a1f'/%3E%3Ccircle cx='16' cy='16' r='9' fill='none' stroke='%23fff3d6' stroke-width='3'/%3E%3Cpath d='M16 7v6M16 19v6M7 16h6M19 16h6' stroke='%23fff3d6' stroke-width='3'/%3E%3C/svg%3E",
+} as const;
+
+export interface SkuPrice {
+  readonly coins?: number;
+  readonly usdg?: number;
+}
+
+export interface MockKit extends KitStoreBridge {
+  /** Dollars left (mock only). */
+  usdg(): number;
+  /** Earned, unclaimed coins left (mock only). */
+  earned(): number;
+}
+
+/** An in-memory Kit for local play and tests: starting balances, prices from game.ts. */
+export function mockKit(
+  start: { earned: number; wallet: number; usdg: number },
+  prices: Readonly<Record<string, SkuPrice>>,
+  coin: { name: string; symbol: string; logo: string | null } = TORQ_COIN,
+): MockKit {
+  let earned = start.earned;
+  let wallet = start.wallet;
+  let usdg = start.usdg;
+  const owned = new Map<string, number>();
+  let spends = 0;
+  /** Earned first, then the wallet: the Kit's order. */
+  const spend = (amount: number, reason: string) => {
+    if (!Number.isInteger(amount) || amount <= 0 || earned + wallet < amount) throw new Error(`cannot spend ${amount} for ${reason}`);
+    const fromEarned = Math.min(earned, amount);
+    earned -= fromEarned;
+    wallet -= amount - fromEarned;
+    return { fromEarned, onChain: amount - fromEarned, key: `mock-spend-${++spends}` };
+  };
+  return {
+    usdg: () => usdg,
+    earned: () => earned,
+    store: {
+      owns: (id) => (owned.get(id) ?? 0) > 0,
+      count: (id) => owned.get(id) ?? 0,
+      async buy(id, opts) {
+        const p = prices[id];
+        if (!p) throw new Error(`no SKU "${id}"`);
+        const payUsdg = opts?.pay === "usdg" || (opts?.pay === undefined && p.coins === undefined);
+        if (payUsdg) {
+          if (p.usdg === undefined || usdg < p.usdg) throw new Error("not enough USDG");
+          usdg -= p.usdg;
+        } else {
+          if (p.coins === undefined) throw new Error(`"${id}" has no coin price`);
+          spend(p.coins, id);
+        }
+        owned.set(id, (owned.get(id) ?? 0) + 1);
+        return { id };
+      },
+    },
+    coins: {
+      name: () => coin.name,
+      symbol: () => coin.symbol,
+      logo: () => coin.logo,
+      balance: () => earned + wallet,
+      async spend(amount, reason) {
+        return spend(amount, reason);
+      },
+    },
+  };
+}