@netforge/template-racer 0.1.0 → 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/README.md

@@ -1,55 +1,75 @@
-# TORQUEBAY (racer template)
+# @netforge/template-racer
 
-Up to eight karts race laps round harbour circuits: 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; the next round runs another
-circuit. Seat bots fill the grid, so one person alone still has a field.
+A kart racer game template for Net Forge: up to 8 players on harbour circuits, with seat bots filling the grid (TORQUEBAY).
 
-| Path | What |
-|---|---|
-| `src/game.ts` | The game, as the model writes it (declarations only): three circuits, round upgrades, earn rules, stake, store. |
-| `src/manifest.ts` | Loads and compiles it; `racerAdapter()` for the room server and the client. Room template `racer`. |
-| `src/store.ts` | Store hooks on the Kit's API names: three round upgrades (40, 40, 60 coins), two paint jobs (300, 500), bumper kit gear (120); mock until the token is live. |
-| `client/` | The browser client: chase camera, a streamed track, HUD with minimap, keyboard/gamepad/touch, game feel. |
-| `test/` | Playtest bots through `engine.test.run`, the race rules, prediction, the store. |
-| `llms.txt` | How to change the game (for agents). |
-
-## How it plays on the server
-
-- The sim is `@netforge/engine-sim`'s kart mode (`src/kart.ts`): arcade
-  vehicle physics on a 1/1024 grid at 60 Hz. Velocity splits into forward
-  and sideways parts each tick: the engine pushes the forward part toward
-  top speed, grip bleeds the sideways part (much less while drifting), and
-  steering turns with speed. A held drift charges a mini-turbo in three
-  tiers. Laps count through four quarter checkpoints in order. A client
-  predicts its own kart alone; kart bumps run only on the room server and
-  the next snapshot corrects them.
-- The track streams: the client builds the road,
-  kerbs, barriers and scenery in chunks of about 40 m within 170 m of the
-  camera, two chunks a frame, nearest first, and drops chunks behind.
-- The race runner (`@netforge/engine/game` `RaceRunner`, shared with
-  SKYLEDGE) 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 never earn.
-- Seat bots drive the racing line, pass the kart ahead, hold drifts through
-  long bends, and are shaded by skill (top speed and line).
-
-## Run it
-
-This template runs on your own computer with play money through
-`kit play` (`@netforge/kit-play`). From the repository root:
+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
-pnpm install --frozen-lockfile && pnpm build
-mkdir -p play-racer/src && cp packages/template-racer/src/game.ts play-racer/src/
-echo '{"template":"racer"}' > play-racer/netnet.json
-node packages/kit-play/dist/cli.js play-racer       # opens http://127.0.0.1:4663
+npm install @netforge/template-racer
 ```
 
-Edit `play-racer/src/game.ts` and run it again to try a change. Real-token
-earning, stakes and claims run only on the hosted Net Forge server.
+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
 
-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. ` shows stats.
+MIT. See `LICENSE` and `NOTICE`.

package/client/main.ts

@@ -137,7 +137,7 @@ async function main(): Promise<void> {
   if (friendRoomId && conn.roomId !== friendRoomId) setTimeout(() => hud.toast("Room full, new room"), 500);
   if (conn.welcome.version !== GAME_VERSION) setTimeout(() => hud.toast("Update ready. Reload."), 800);
   const linkFor = (base: string) =>
-    `${base}?room=${conn.roomId}${place !== PLACE ? `&place=${encodeURIComponent(place)}` : ""}${params.has("server") ? `&server=${encodeURIComponent(endpoint)}` : ""}`;
+    `${base}?room=${conn.roomId}${place !== PLACE ? `&place=${encodeURIComponent(place)}` : ""}${params.has("server") ? `&server=${encodeURIComponent(endpoint)}` : ""}${params.has("game") ? `&game=${encodeURIComponent(params.get("game") ?? "")}` : ""}`;
   history.replaceState(null, "", `${linkFor(location.pathname)}${autopilot ? `&autopilot=${autopilotMode}` : ""}${params.has("webgl") ? "&webgl=1" : ""}${params.has("stats") ? "&stats=1" : ""}${params.has("style") ? `&style=${encodeURIComponent(params.get("style") ?? "")}` : ""}${params.has("preview") ? "&preview=1" : ""}`);
 
   const libraryBase = params.get("library") ?? env.VITE_LIBRARY_URL ?? "./library";

package/llms-full.txt

@@ -0,0 +1,236 @@
+# Net Forge racer template (TORQUEBAY)
+
+> 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.
+
+## Worked example: src/game.ts
+
+The whole game as the template ships it. Every change starts from this file.
+
+```ts
+/**
+ * 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 } });
+```
+
+## Validate and playtest
+
+- Validate: the MCP tool `netforge_validate_game` builds `src/game.ts` and returns one actionable line per problem (an unknown asset id, a missing earn.stake, a bad id). The same checks throw `GameDefinitionError` when the module is imported.
+- Playtest: the MCP tool `netforge_run_playtest`, or in code `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.
+- Template tests: test/harness.test.ts, test/host.test.ts, test/race.test.ts, test/store.test.ts, run with `npx vitest run` in this package.
+- Play locally: put `src/game.ts` and a `netnet.json` of `{"template":"racer"}` in a folder, install `@netforge/kit-play` and `@netforge/engine`, and run `npx kit-play` (or the MCP tool `netforge_play_locally`). It opens http://127.0.0.1:4663 with play money.
+- Docs: https://forge.netnet.capital/docs/templates/racer

package/llms.txt

@@ -1,4 +1,4 @@
-# TORQUEBAY: the racer template (NetNet game runtime, play style "racer")
+# Net Forge racer template (TORQUEBAY)
 
 > 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

package/package.json

@@ -1,12 +1,31 @@
 {
   "name": "@netforge/template-racer",
-  "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.",
+  "version": "0.2.0",
+  "description": "Kart racer game template for Net Forge: harbour circuits with drift mini-turbos, boost pads, coins and laps at 60 Hz, with seat-filling bots (TORQUEBAY).",
+  "keywords": [
+    "game-template",
+    "multiplayer",
+    "browser-game",
+    "html5-game",
+    "threejs",
+    "game-engine",
+    "typescript",
+    "gamedev",
+    "ai-agents",
+    "mcp",
+    "net-forge",
+    "kart-racer",
+    "racing",
+    "physics"
+  ],
   "license": "MIT",
   "type": "module",
   "exports": {
     ".": "./src/manifest.ts",
-    "./store": "./src/store.ts"
+    "./store": "./src/store.ts",
+    "./package.json": "./package.json",
+    "./llms.txt": "./llms.txt",
+    "./llms-full.txt": "./llms-full.txt"
   },
   "files": [
     "src",
@@ -15,25 +34,36 @@
     "llms.txt",
     "README.md",
     "NOTICE",
-    "LICENSE"
+    "LICENSE",
+    "llms-full.txt",
+    "AGENTS.md",
+    "CLAUDE.md"
+  ],
+  "sideEffects": [
+    "./src/game.ts",
+    "./src/manifest.ts",
+    "./client/**"
   ],
   "publishConfig": {
     "access": "public"
   },
+  "homepage": "https://forge.netnet.capital/docs/templates/racer",
+  "bugs": {
+    "url": "https://github.com/netnetdev/net-forge/issues"
+  },
   "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"
+    "@netforge/asset-library": "0.2.0",
+    "@netforge/engine-sim": "0.2.0",
+    "@netforge/engine": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "22.20.1",
@@ -43,9 +73,6 @@
     "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",