@netforge/template-arena 0.1.0 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,75 @@
+# Extending VOLTYARD
+
+VOLTYARD is the arena shooter template of the Net Forge game engine. The template already has loadouts, aiming, projectiles, lag-compensated beams, death and respawn, heal drops, rounds, a scoreboard, seat bots, netcode, rendering, touch and gamepad controls, earn and the store. You change the game by changing declarations. Read `llms.txt` for every field, and `llms-full.txt` for the complete worked example.
+
+## The one file to edit
+
+- `src/game.ts` is the whole game. Change declarations in place.
+- `src/names.json`, next to it, holds the title and every label players read (weapons, upgrades, earn rules, store items). Add a label there for every new id.
+- Everything else (`src/manifest.ts`, `src/store.ts`, `client/`, `test/`, `scripts/`) is template machinery. Do not edit it.
+
+## Imports
+
+`src/game.ts` imports only from `@netforge/engine`. The shipped game uses:
+
+```ts
+import { earn, game, prefab, store, system, upgrade, weapon } from "@netforge/engine";
+```
+
+Also available for this genre: `economy` and `metaUpgrade` (opt-in permanent upgrades, capped by the engine), and `earn.pot` (an optional PvP pot, arena only).
+
+## Declarations
+
+- `game({ template: "arena", style, places, players: { prefab, max, bots, loadout, respawn, drop }, arena: { halfSize, pillars, spawns }, round: { seconds, frags } })`.
+- `weapon(id, { kind, damage, cooldown, range, ... })` with kind `"blaster"`, `"beam"` or `"nova"` only.
+- `prefab(id, { model, kind: "pickup", value })` for the heal cell and other pickups. A declared enemy prefab spawned by a system chases the nearest player.
+- `upgrade(id, { stat, step, maxLevel })` for round upgrades the store sells.
+- `system(id, (ctx) => { ... })` with `every`, `after`, `onTick`, `spawn`, `spawnRing`, `alive`, `players`, `emit`, `on`, `end`, `random`, `tick`, `time`.
+- `earn.rule(id, { when, n, pay, oncePer: "run" })`. Events: `opponent.killed`, `player.died`, `round.top`, `round.finished`, `run.won`, and anything a system emits.
+- `earn.stake({ min, max, multiple })`, exactly one, on one top-level line.
+- `store.sku(id, { coins, grants? })`.
+
+## Rules the build enforces
+
+- Ids are lower_snake_case.
+- Every game declares at least one `earn.rule` and exactly one `earn.stake`. A game without them does not build. `"stake"` and `"pot"` are reserved and are never a SKU or upgrade id.
+- `players.loadout` names 1 to 4 declared weapons. Arena weapons are `blaster`, `beam` or `nova`, never `bolt` or `orbit`. Keep beam cooldowns at 0.8 s or more.
+- Pillars fit on the floor. Spawns sit 1 m inside the floor and 1 m clear of pillars.
+- Asset ids are library ids such as `"style.lowpoly.mini_male_f"`, never URLs or paths, and must exist in the asset library.
+- Keep `game({ style })` as the creator picked it: lowpoly, toon, ps1, pixel, voxel or handdrawn.
+- Bots never earn, and killing a bot pays no earn rule.
+- In a 4-minute playtest, 4 players plus seat bots must all score kills and an earn rule must fire. A round should end within about 4 minutes.
+- Keep the five SKUs the client is wired to at their prices: `plating`, `servo`, `capacitor`, `skin_neon` (cosmetic 1) and `skin_chrome` (cosmetic 2).
+
+## Validate
+
+- With the MCP server (`npx -y @netforge/mcp`), call `netforge_validate_game` on `src/game.ts`. It returns one actionable line per problem.
+- In this package, run the tests with vitest: `test/harness.test.ts`, `test/host.test.ts`, `test/newcomer.test.ts` and `test/store.test.ts`.
+- A bad declaration throws `GameDefinitionError` with a line that says what to change.
+
+## Playtest
+
+- With the MCP server, call `netforge_run_playtest`.
+- In code, import the game module and run the headless harness:
+
+```ts
+import { engine } from "@netforge/engine";
+import "./src/game.js";
+
+const report = await engine.test.run({ ticks: 60 * 240, bots: 4, seed: 1 });
+console.log(report.kills, report.deaths, report.earned, report.softlock);
+```
+
+The report has kills, deaths, rounds (`runs.won`), `topScore`, `scorers`, earn by rule, softlock and ms per tick.
+
+## Play locally
+
+In a folder with `netnet.json` (`{"template":"arena"}`) and `src/game.ts`, with `@netforge/kit-play` and `@netforge/engine` installed, run `npx kit-play`. It opens http://127.0.0.1:4663 with play money. The MCP tool `netforge_play_locally` gives the same steps.
+
+## Do not
+
+- Do not write renderers, netcode, physics or bot AI. The template has them.
+- Do not reference assets by URL or file path.
+- 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 SKUs the client is wired to.

package/CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md
+
+This package is VOLTYARD, a Net Forge game template. Read AGENTS.md before changing this game. It lists the declarations this genre has, the rules the build enforces, and how to validate, playtest and play the game locally.
+
+The five hard rules:
+
+1. Edit only src/game.ts (and src/names.json for the labels players read).
+2. Import only from @netforge/engine.
+3. Ids are lower_snake_case.
+4. Declare at least one earn.rule and exactly one earn.stake.
+5. Never write renderers, netcode, physics or bot AI, and never reference assets by URL or file path (use library ids such as "style.lowpoly.frog").

package/README.md

@@ -1,64 +1,83 @@
-# VOLTYARD (Template 2: arena shooter)
+# @netforge/template-arena
 
-Wirejacks duel at night in a yard of humming transformers. Twin-stick: move
-with one hand, aim with the other, hold fire. Swap between an arc rifle, a
-scatter coil and a rail lance. Every kill drops a heal cell. Rounds last
-three minutes or end at 25 kills; the top of the board takes the round.
-Bots fill empty seats, so one player alone still gets a fight.
+An arena shooter game template for Net Forge: a twin-stick shooter for up to 16 players, with bots that fill empty seats (VOLTYARD).
+
+Wirejacks duel at night in a yard of humming transformers. Players move with one hand, aim with the other and hold fire, swapping between an arc rifle, a scatter coil and a rail lance. Every kill drops a heal cell. A round lasts three minutes or ends at 25 kills, and the top of the board takes the round. Bots fill empty seats, so one player alone still gets a fight.
+
+## Install
+
+```sh
+npm install @netforge/template-arena
+```
+
+You rarely import this package directly. kit play (`@netforge/kit-play`) and the Net Forge MCP server use it to build and run a game whose `src/game.ts` you write.
+
+## Play it locally
+
+```sh
+mkdir -p my-game/src && cd my-game
+npm init -y && npm install @netforge/kit-play @netforge/engine @netforge/template-arena
+cp node_modules/@netforge/template-arena/src/game.ts src/
+echo '{"template":"arena"}' > netnet.json
+npx kit-play        # opens http://127.0.0.1:4663
+```
+
+Open the Invite link (`?room=<id>`) in another tab to play together, or start with `--host 0.0.0.0` and open it on a phone on the same network. Coins are play money. Real-token earning, stakes and claims run only on the hosted Net Forge server.
+
+## Change the game
+
+Edit `src/game.ts` and run `npx kit-play` again. For example, make the arc rifle hit harder and fire a little slower:
+
+```ts
+weapon("arc_rifle", { kind: "blaster", damage: 16, cooldown: 0.2, range: 26, speed: 44, knockback: 0 });
+```
+
+Or shorten the round and lower the kill target in `game({ ... })`:
+
+```ts
+round: { seconds: 120, frags: 15 },
+```
+
+## How it plays on the server
+
+- Server-authoritative at 60 Hz. Your own wirejack is predicted (move, aim, weapon, cooldowns), and everyone else is drawn about 100 ms in the past.
+- The rail lance is a hitscan resolved with lag compensation: the server rewinds the other players to what you saw, capped at 200 ms. Rifle and scatter shots are server projectiles.
+- Seat bots (`players.bots`) join while at least one person is in the room and leave as people join. They adapt to each person's record in the round, ease off when they lead, never earn and never reach the frag limit. Killing a bot scores and shows in the feed but pays no earn rule.
+- Spawns are out of every opponent's sight and 12 m clear, with 2 s of protection on joining, respawning and each new round.
+- Earn: kills of people (3 and 12 in a round), a five-kill streak, and topping the board with another person in the round. Bot kills and a board of bots pay nothing. The room server is the referee.
+
+## Files
 
 | Path | What |
 |---|---|
-| `src/game.ts` | The game, as the model writes it (declarations only). |
-| `src/manifest.ts` | Loads and compiles it; `arenaAdapter()` for the room server and client. Room template `shooter`. |
-| `src/store.ts` | Store hooks on the Kit's API names (`kit.coins.*`, `kit.store.*`): three round upgrades (40, 40, 60 coins) and two finishes (300, 500 coins), shown under the token's own symbol and logo; mock until the token is live. |
+| `src/game.ts` | The game, as declarations only. This is the file you edit. |
+| `src/manifest.ts` | Loads and compiles the game; `arenaAdapter()` for the room host and the client. |
+| `src/store.ts` | Store hooks on the Kit's API names (`kit.coins.*`, `kit.store.*`): three round upgrades and two finishes. |
 | `client/` | The browser client: three.js scene, HUD, twin-stick input (keys and mouse, gamepad, touch), game feel. |
-| `test/` | Playtest bots through `engine.test.run`, and the store. |
-| `llms.txt` | How to change the game (for agents). |
+| `test/` | Playtest bots through `engine.test.run`, the newcomer test and the store test. |
+| `llms.txt`, `llms-full.txt` | How to change the game, for agents. |
 
-## How it plays on the server
+## Controls
+
+WASD to move, mouse to aim, click to fire, 1 2 3 or Q to change weapon, Space to dash, Tab for the board. On touch, the left stick moves, the right stick aims and fires, and SWAP and DASH are buttons. The backtick key shows stats.
 
-- Server-authoritative at 60 Hz. Your own wirejack is predicted (move, aim,
-  weapon, cooldowns); everyone else is drawn ~100 ms in the past.
-- The rail lance is a hitscan resolved with lag compensation: the server
-  rewinds the other players to what you saw (capped at 200 ms). Rifle and
-  scatter shots are server projectiles.
-- Seat bots (`players.bots`) join while at least one person is in the
-  room and leave as people join. Against a person they react late, aim
-  loose and fire in bursts by that person's record this round, sharpening
-  as the person wins. A bot level with or ahead of the best person eases
-  off (looser aim, slower reactions, and it would rather fight other bots),
-  but bots never stop shooting and never earn. Killing a bot scores and
-  shows in the feed but pays no earn rule. Only a person reaches the frag
-  limit.
-- Spawns: out of every opponent's sight (physics raycasts) and 12 m clear,
-  with 2 s of protection on joining, respawning and each new round.
-- `test/newcomer.test.ts` plays a deliberately weak new player alone with
-  the seat bots over 10 rounds: first kill within about 20 s, no deaths
-  within 3 s of spawning, top half in most rounds without winning every
-  one, no bot reaching the frag limit. It also reports what the newcomer
-  earns per round, which alone with bots is nothing.
-- Earn: kills of people (3 and 12 in a round), a five-kill streak, and
-  topping the board with another person in the round. Bot kills and a board
-  of bots pay nothing, enforced by the engine's
-  `GameRunner` for every arena game. The room server is the referee; before graduation earn is credited
-  as points, after it the game's own coins under its own name.
-
-## Run it
-
-This template runs on your own computer with play money through
-`kit play` (`@netforge/kit-play`). From the repository root:
+## For AI agents
+
+Read `AGENTS.md` and `llms.txt` before editing. The Net Forge MCP server gives a coding agent the templates, the API and a playtest loop:
 
 ```sh
-pnpm install --frozen-lockfile && pnpm build
-mkdir -p play-arena/src && cp packages/template-arena/src/game.ts play-arena/src/
-echo '{"template":"arena"}' > play-arena/netnet.json
-node packages/kit-play/dist/cli.js play-arena       # opens http://127.0.0.1:4663
+npx -y @netforge/mcp
 ```
 
-Edit `play-arena/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.
+The package is `@netforge/mcp` and its bin is `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/arena
+- `llms.txt` and `llms-full.txt` in this package. The full file includes the complete `src/game.ts` and the validate and playtest steps.
+
+## License
 
-Open the Invite link in another tab or on a phone on the same network to
-play together (`?room=<id>`). Keys: WASD, mouse aim, click fire, 1 2 3 or Q
-weapon, Space dash, Tab board. Touch: left stick moves, right stick aims and
-fires, SWAP and DASH buttons. ` shows stats.
+MIT. See LICENSE and NOTICE.

package/client/main.ts

@@ -146,7 +146,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") ?? "")}` : ""}`);
 
   // The asset library: real models by library id (./library next to the page, or the published CID). ?shapes=1 draws the fallback shapes only.

package/llms-full.txt

@@ -0,0 +1,346 @@
+# Net Forge arena shooter template (VOLTYARD)
+
+> A twin-stick arena shooter for up to 16 players, with bots filling empty
+> seats. Rounds last a few minutes; the top of the board takes the round.
+> You change the game by editing src/game.ts only. The template already has
+> loadouts, aiming, projectiles, lag-compensated beams, death and respawn,
+> heal drops, rounds, a scoreboard, bots, netcode, rendering, touch and
+> gamepad 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(), prefab(), weapon(), upgrade(), system(), earn.rule(), store.sku().
+- src/names.json: the title and every label players read (weapons,
+  upgrades, earn rules, store items).
+- Everything else is template machinery.
+
+## Rules the build enforces
+
+- game({ template: "arena", style: "lowpoly" }) with players.loadout (1 to 4
+  declared weapons), an arena { halfSize, pillars, spawns } and a round.
+- Arena weapons are kind "blaster", "beam" or "nova" (never bolt or orbit).
+- Asset ids look like "style.lowpoly.mini_male_f", 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. The template draws everything in it, and a "style.lowpoly.<name>" id draws as that style's own model of the same name when the style has one.
+- Ids are lower_snake_case. Every game declares at least one earn.rule and one earn.stake (the buy-in run).
+- Pillars fit on the floor; spawns sit 1 m inside the floor and 1 m clear of pillars.
+- 4 players plus seat bots must all score kills, and an earn rule must fire,
+  in a 4-minute playtest. A round should end within about 4 minutes.
+
+## Units
+
+Seconds, metres, metres per second, hit points (players have 100).
+Tick rate 60 Hz (shooters). Yaw 0 aims up the screen (-z).
+
+## The loop
+
+Players spawn at a spawn point no opponent can see and at least 12 m from
+all of them (a floor point when no declared spawn qualifies), with 2 s of
+protection on joining, on respawn and at each new round (firing ends it). They move with one stick or WASD, aim with the
+other or the mouse, hold fire, and pick weapons with 1 2 3 (or cycle).
+A killed player drops players.drop (a heal cell), waits players.respawn
+seconds and comes back. A round ends after round.seconds, or when someone
+reaches round.frags kills; the end screen shows the board, then a new round.
+
+## Common changes
+
+### Tune a weapon
+weapon("arc_rifle", { kind: "blaster", damage: 12, cooldown: 0.15, range: 26, speed: 44 });
+blaster: count projectiles fanned over spread degrees at speed m/s for range m.
+beam: an instant hit to range m (pillars stop it); the server rewinds what
+the shooter saw (lag compensation), so keep cooldown at 0.8 s or more.
+nova: hits every opponent within range m (a short-range blast).
+
+### Add a weapon to the loadout
+weapon("ion_cannon", { kind: "blaster", damage: 40, cooldown: 1.2, range: 30, speed: 22, pierce: 2 });
+players.loadout: ["arc_rifle", "scatter_coil", "rail_lance", "ion_cannon"] (at most 4; slot 4 is reached by cycling).
+Add its label to names.json weapons.
+
+### Change the yard
+arena: { halfSize: 26, pillars: [[x, z, radius], ...], spawns: [[x, z], ...] }.
+Smaller halfSize and more pillars make closer fights. Keep spawns spread out.
+
+### Change round length or the kill target
+round: { seconds: 180, frags: 25 }. 120 to 300 seconds plays well.
+
+### More or fewer bots
+players.bots: 6 fills a room up to 6 players with bots (0 turns them off).
+Bots never earn, and killing a bot pays no earn rule (it still scores and
+shows in the kill feed). players.max caps humans in one room. Bots go easy on a
+person with a poor record and sharpen as they win, ease off once they
+lead the best person (they never stop shooting), and never take the round
+(only a person reaches round.frags; the end screen names the best person).
+
+### Faster respawn, bigger heals
+players.respawn: 2; prefab("volt_cell", { ..., kind: "pickup", value: 50 }).
+
+### Add an earn rule
+earn.rule("first_blood", { when: "opponent.killed", n: 1, pay: 2, oncePer: "run" });
+Events: opponent.killed (credits the killer), player.died (credits the one
+who died), round.top (the top fragger when a round ends), round.finished
+(everyone present at the end), run.won, and anything you emit(). A run is a
+round. Each rule pays once per round per player, in coins; the room server
+is the referee; bots never earn. Bot kills never pay: opponent.killed for a
+bot's death, and anything a system emits while handling it (a streak that a
+bot kill completes), score but count toward no earn rule. round.top pays
+only when another person was in the round, never for topping a board of
+bots. Alone with bots a player earns nothing from kills or the board.
+
+### The buy-in run (required)
+earn.stake({ min: 10, max: 100, multiple: 2 });
+Every game declares one, on one top-level line; a game without it does not
+build. A player stakes coins at the start of a run (the Kit spends them as
+coins.spend(amount, "stake"), then the client calls conn.stake()). The room
+fixes the stake when the next run starts. A staked run pays its normal earn
+plus a share of stake x multiple: the share is the part of the run's most
+earn the player makes. What it does not win back stays in the reward pool.
+multiple is 1 to 2. "stake" is reserved: never a SKU or meta upgrade id.
+
+### PvP pot (optional, arena only)
+earn.pot({ entry: 20, recycle: 0.05 });
+Each entrant pays the entry (coins.spend(entry, "pot"), then conn.pot()) and
+joins the next round's pot. At the round's end the pot, less the recycle
+share that stays in the reward pool, is split by the earn each entrant made.
+A round where no entrant earned recycles the whole pot. "pot" is reserved.
+
+### Losable gear (optional)
+store.sku("plating_kit", { coins: 120, grants: { gear: "plating", loseBelow: 0.25 } });
+Gear is owned in the player's profile and sells for coins only. It brings one
+level of its declared upgrade into every staked run, and is lost when that run
+makes less than loseBelow of its most earn. Its coins stay in the reward pool.
+
+### Track something with a system
+system("streaks", ({ on, emit }) => {
+  const streak = new Map<number, number>();
+  on("opponent.killed", (ids) => { for (const id of ids) { const n = (streak.get(id) ?? 0) + 1; streak.set(id, n); if (n === 5) emit("streak.five", [id]); } });
+  on("player.died", (ids) => { for (const id of ids) streak.set(id, 0); });
+});
+emit(event, ids) credits those players; emit(event) credits everyone present.
+players() gives each player's id, position, health, alive, kills, deaths, bot.
+
+### Coins: earn and the store
+
+Every game has coins: 1 coin = 1 of the game's own token, and players see
+them under the token's own name, symbol and logo (never "coins" or "tokens"
+as a label). Earn rules pay coins (pay is whole coins). The recommended
+coin model (the default) sells in-round consumables and looks, never
+permanent stat power:
+
+store.sku("plating", { coins: 40 });                                  // one level of the "plating" upgrade for the round
+store.sku("skin_neon", { coins: 300, grants: { cosmetic: 1 } });      // a finish, owned for good (saved in the player's profile)
+
+A store item named after a declared upgrade(...) is a round upgrade: the
+room grants one level of it when a player pays. Keep the five SKUs the
+client is wired to (plating, servo, capacitor, skin_neon, skin_chrome) at
+their prices, with the finishes' grants (neon 1, chrome 2). "Cosmetics only":
+economy({ store: "cosmetics" }). Permanent upgrades are opt-in:
+economy({ metaUpgrades: true }) and metaUpgrade(...), capped by the engine
+at +15% a stat and +30% in all (see GAME-DESIGN.md). Price against what a round pays (the four rules here pay up
+to 51): an upgrade under a round, a finish a few rounds. Before the game
+launches coins are play money; the Kit switches by itself.
+
+### Change who the players are (the asset library)
+players.prefab is a real CC0 character by id; each player is drawn in their
+colour holding a blaster, and plays its walk, run and shoot animations.
+players: { prefab: "style.lowpoly.soldier", ... } or a dressed original:
+players: { prefab: "style.lowpoly.blocky_g", appearance: { tint: "#16e0ff", parts: ["antenna"] }, ... }
+appearance: { tint: "#rrggbb", accent: "#rrggbb", scale: 0.4 to 3, parts: up to 4 }.
+The heal cell is prefab("volt_cell", { model: "style.lowpoly.cell_heal", ... });
+any pickup model works (style.lowpoly.gem_pink, style.lowpoly.coin, style.lowpoly.burger).
+
+## Systems API
+
+every(seconds, n => ...), after(seconds, fn), onTick(fn), spawn(prefab, [x,y,z]),
+spawnRing(prefab, { count, radius, around? }), alive(prefab?), players(),
+emit(event, ids?), on(event, ids => ...), end("won" | "lost"), random(),
+tick(), time(). Enemies are optional in the arena: a declared enemy prefab
+spawned by a system chases the nearest player and can be shot.
+
+## Test
+
+engine.test.run({ ticks: 60 * 240, bots: 4, assert: [...] }) plays the game
+on the server sim with 4 players plus seat bots and reports kills, deaths,
+rounds (runs.won), topScore, scorers, earned by rule, softlock and ms per tick.
+
+## Worked example: src/game.ts
+
+This is the template's complete src/game.ts as it ships. A new game on this
+template starts from this file and changes declarations in place.
+
+```ts
+/**
+ * VOLTYARD: the arena shooter template.
+ *
+ * Wirejacks duel at night in a yard of humming transformers. Move with one
+ * hand, aim with the other, swap between a rifle, a scatter coil and a rail
+ * lance. Every kill drops a cell that heals. Rounds last three minutes or
+ * end at 25 kills; the top of the board takes the round. Bots fill empty
+ * seats so a round always has a fight.
+ *
+ * This file is the whole game as the model writes it: declarations only,
+ * against the typed API in @netforge/engine. Everything else (sim,
+ * netcode, lag compensation, renderer, bots, referee) is the template's
+ * machinery.
+ */
+import { earn, game, prefab, store, system, upgrade, weapon } from "@netforge/engine";
+
+export default game({
+  template: "arena",
+  style: "lowpoly",
+  tickRate: 60,
+  places: { yard: { chunks: "places/yard", spawn: [0, 1, 0] } },
+  players: {
+    prefab: "style.lowpoly.mini_male_f",
+    max: 16,
+    loadout: ["arc_rifle", "scatter_coil", "rail_lance"],
+    bots: 6,
+    respawn: 3,
+    drop: "volt_cell",
+  },
+  // The yard: 52 m square. Pillars are transformers, [x, z, radius]; spawns are [x, z].
+  arena: {
+    halfSize: 26,
+    pillars: [
+      [0, 0, 2.6],
+      [9, 9, 1.4],
+      [-9, 9, 1.4],
+      [9, -9, 1.4],
+      [-9, -9, 1.4],
+      [0, 16, 1.8],
+      [0, -16, 1.8],
+      [16, 0, 1.8],
+      [-16, 0, 1.8],
+      [18, 18, 1.2],
+      [-18, 18, 1.2],
+      [18, -18, 1.2],
+      [-18, -18, 1.2],
+    ],
+    spawns: [
+      [22, 22],
+      [-22, -22],
+      [22, -22],
+      [-22, 22],
+      [0, 22],
+      [0, -22],
+      [22, 0],
+      [-22, 0],
+    ],
+  },
+  round: { seconds: 180, frags: 25 },
+});
+
+// The heal cell a downed wirejack drops: walking over it restores 35 health.
+prefab("volt_cell", { model: "style.lowpoly.cell_heal", health: 1, speed: 0, kind: "pickup", value: 35 });
+
+// The loadout. Damage in hit points (players have 100), cooldowns in seconds, ranges in metres.
+weapon("arc_rifle", { kind: "blaster", damage: 12, cooldown: 0.15, range: 26, speed: 44, knockback: 0 });
+weapon("scatter_coil", { kind: "blaster", damage: 9, cooldown: 0.75, range: 11, speed: 34, count: 7, spread: 26, knockback: 0 });
+weapon("rail_lance", { kind: "beam", damage: 60, cooldown: 1.4, range: 40, knockback: 0 });
+
+// Upgrades sold in the store, one level each, for the rest of the round.
+upgrade("plating", { stat: "maxHealth", step: 25, maxLevel: 1 });
+upgrade("servo", { stat: "speed", step: 0.08, maxLevel: 1 });
+upgrade("capacitor", { stat: "haste", step: 0.12, maxLevel: 1 });
+
+// Streaks: five kills without dying.
+system("streaks", ({ on, emit }) => {
+  const streak = new Map<number, number>();
+  on("opponent.killed", (ids) => {
+    for (const id of ids) {
+      const n = (streak.get(id) ?? 0) + 1;
+      streak.set(id, n);
+      if (n === 5) emit("streak.five", [id]);
+    }
+  });
+  on("player.died", (ids) => {
+    for (const id of ids) streak.set(id, 0);
+  });
+  // A player's earning run started over (signed in, or staked): the streak does too.
+  on("run.started", (ids) => {
+    for (const id of ids) streak.set(id, 0);
+  });
+});
+
+// Earn (mandatory). Pays the game's coins (1 coin = 1 token), once per round each. Bots never earn; bot kills and a board of bots pay nothing.
+earn.rule("live_wire", { when: "opponent.killed", n: 3, pay: 4, oncePer: "run" });
+earn.rule("long_shift", { when: "opponent.killed", n: 12, pay: 10, oncePer: "run" });
+earn.rule("overload", { when: "streak.five", n: 1, pay: 12, oncePer: "run" });
+earn.rule("top_of_the_yard", { when: "round.top", n: 1, pay: 25, oncePer: "run" });
+// Buy-in run (the mandatory sink loop): stake coins at run start to earn above free play.
+// A staked run also pays up to stake x multiple, by the share of this run's earn the player makes.
+// What it does not win back stays in the reward pool. Values are PLACEHOLDER.
+earn.stake({ min: 10, max: 100, multiple: 2 });
+// PvP pot: each entrant pays the entry before a round; the round splits the pot by the earn each entrant
+// makes, and the recycle share stays in the reward pool. Values are PLACEHOLDER.
+// Declared, not enabled: add `enabled: true` to run it (R-16 approved 2026-10-23).
+earn.pot({ entry: 20, recycle: 0.05 });
+
+// Store (the Kit), priced in coins (the default coin model): three round upgrades
+// used in a round, and two cosmetic finishes owned for good (kept in the profile).
+store.sku("plating", { coins: 40 });
+store.sku("servo", { coins: 40 });
+store.sku("capacitor", { coins: 60 });
+store.sku("skin_neon", { coins: 300, grants: { cosmetic: 1 } });
+store.sku("skin_chrome", { coins: 500, grants: { cosmetic: 2 } });
+// Losable gear: owned for good until lost. It brings one level of its upgrade into every staked run,
+// and is lost when that run makes less than loseBelow of its most earn. Values are PLACEHOLDER.
+store.sku("plating_kit", { coins: 120, grants: { gear: "plating", loseBelow: 0.25 } });
+```
+
+## Validate and playtest
+
+### With the MCP server
+
+Run `npx -y @netforge/mcp` (package @netforge/mcp, bin netforge-mcp) and
+connect it to your coding agent. 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.
+
+- netforge_validate_game checks src/game.ts against the engine's schemas and this
+  template's rules, and returns one actionable line per problem.
+- netforge_run_playtest plays the game headless with bots and returns the report.
+- netforge_play_locally gives the steps to open the game in a browser with kit play.
+
+### In code
+
+Import the game module first so its declarations register, then run the
+headless harness. This plays 4 players plus seat bots for 4 minutes at 60 Hz.
+
+```ts
+import { engine } from "@netforge/engine";
+import "./src/game.js";
+
+const report = await engine.test.run({
+  ticks: 60 * 240,
+  bots: 4,
+  seed: 1,
+  assert: [
+    { name: "earn fired", check: (r) => r.earnEmitted > 0 },
+    { name: "no softlock", check: (r) => !r.softlock },
+  ],
+});
+if (report.failed.length > 0) throw new Error(report.failed.join("\n"));
+```
+
+The report has kills, deaths, rounds (runs.won), topScore, scorers, earned by rule, softlock and ms per tick.
+
+The template's own tests (vitest) are the reference checks:
+
+- test/harness.test.ts
+- test/host.test.ts
+- test/newcomer.test.ts
+- test/store.test.ts
+
+### Play it locally
+
+In a folder with netnet.json and src/game.ts:
+
+```sh
+npm install @netforge/kit-play @netforge/engine @netforge/template-arena
+echo '{"template":"arena"}' > netnet.json
+npx kit-play        # opens http://127.0.0.1:4663
+```
+
+kit play builds the template client with your src/game.ts and runs a local
+room host with play money. No wallet, no chain and no hosted servers are
+involved. Open the link in more tabs for more players.

package/llms.txt

@@ -1,4 +1,4 @@
-# VOLTYARD: the arena shooter template (NetNet game runtime, Template 2)
+# Net Forge arena shooter template (VOLTYARD)
 
 > A twin-stick arena shooter for up to 16 players, with bots filling empty
 > seats. Rounds last a few minutes; the top of the board takes the round.

package/package.json

@@ -1,12 +1,35 @@
 {
   "name": "@netforge/template-arena",
-  "version": "0.1.0",
-  "description": "VOLTYARD: Template 2 of the NetNet game runtime, an arena shooter with lag-compensated beams, loadouts, rounds and seat-filling bots. The game module, its browser client and its playtest bots.",
+  "version": "0.2.0",
+  "description": "Arena shooter game template for Net Forge: up to 16 players, lag-compensated beams, loadouts, rounds and seat-filling bots (VOLTYARD).",
+  "keywords": [
+    "game-template",
+    "multiplayer",
+    "browser-game",
+    "html5-game",
+    "threejs",
+    "game-engine",
+    "typescript",
+    "gamedev",
+    "ai-agents",
+    "mcp",
+    "net-forge",
+    "io-game",
+    "netcode"
+  ],
   "license": "MIT",
   "type": "module",
+  "sideEffects": [
+    "./src/game.ts",
+    "./src/manifest.ts",
+    "./client/**"
+  ],
   "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,26 +38,32 @@
     "llms.txt",
     "README.md",
     "NOTICE",
-    "LICENSE"
+    "LICENSE",
+    "llms-full.txt",
+    "AGENTS.md",
+    "CLAUDE.md"
   ],
   "publishConfig": {
     "access": "public"
   },
+  "homepage": "https://forge.netnet.capital/docs/templates/arena",
+  "bugs": {
+    "url": "https://github.com/netnetdev/net-forge/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/netnetdev/net-forge.git",
     "directory": "packages/template-arena"
   },
-  "homepage": "https://github.com/netnetdev/net-forge/tree/main/packages/template-arena#readme",
   "engines": {
     "node": ">=20"
   },
   "dependencies": {
     "nipplejs": "1.0.4",
     "three": "0.186.1",
-    "@netforge/engine-sim": "0.1.0",
-    "@netforge/asset-library": "0.1.0",
-    "@netforge/engine": "0.1.0"
+    "@netforge/asset-library": "0.2.0",
+    "@netforge/engine": "0.2.0",
+    "@netforge/engine-sim": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "22.20.1",
@@ -44,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",

package/src/game.ts

@@ -102,7 +102,7 @@ earn.rule("top_of_the_yard", { when: "round.top", n: 1, pay: 25, oncePer: "run"
 earn.stake({ min: 10, max: 100, multiple: 2 });
 // PvP pot: each entrant pays the entry before a round; the round splits the pot by the earn each entrant
 // makes, and the recycle share stays in the reward pool. Values are PLACEHOLDER.
-// Off until a legal review: declared, not enabled, so no room takes an entry.
+// Declared, not enabled: add `enabled: true` to run it (R-16 approved 2026-10-23).
 earn.pot({ entry: 20, recycle: 0.05 });
 
 // Store (the Kit), priced in coins (the default coin model): three round upgrades