@netforge/template-arena 0.0.0-stage → 0.2.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-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

@@ -0,0 +1,164 @@
+# 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.