@netforge/template-arena 0.0.0-stage → 0.1.0

package/client/stake.ts

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

package/llms.txt

@@ -0,0 +1,164 @@
+# VOLTYARD: the arena shooter template (NetNet game runtime, Template 2)
+
+> 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.

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@netforge/template-arena",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/manifest.ts",
+    "./store": "./src/store.ts"
+  },
+  "files": [
+    "src",
+    "client",
+    "!client/vite.config.ts",
+    "llms.txt",
+    "README.md",
+    "NOTICE",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/netnetdev/net-forge.git",
+    "directory": "packages/template-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"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "@types/three": "0.186.0",
+    "tsx": "4.23.0",
+    "typescript": "5.8.3",
+    "vite": "6.4.3",
+    "vitest": "3.2.7"
+  },
+  "bugs": {
+    "url": "https://github.com/netnetdev/net-forge/issues"
+  },
+  "scripts": {
+    "build": "node ../engine/scripts/fresh-dist.mjs && vite build --config client/vite.config.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "dev": "vite --config client/vite.config.ts",
+    "preview": "vite preview --config client/vite.config.ts"
+  }
 }

package/src/game.ts

@@ -0,0 +1,117 @@
+/**
+ * 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.
+// Off until a legal review: declared, not enabled, so no room takes an entry.
+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 } });

package/src/manifest.ts

@@ -0,0 +1,38 @@
+/**
+ * Loads the game module once per process and compiles it. The room server,
+ * the client, the bots and the tests all start here.
+ */
+import { collectManifest, compileGame, engineSimAdapter } from "@netforge/engine/game";
+import type { CompiledGame, EngineRoomWorld, RunnerOptions } from "@netforge/engine/game";
+import type { SimAdapter } from "@netforge/engine/net";
+import type { InputCommand } from "@netforge/engine-sim";
+import "./game.js";
+
+/** Content version: bump with any change to game.ts (hot swap compares it). */
+export const GAME_VERSION = "voltyard-0.1.1";
+export const GAME_NAME = "voltyard";
+/** Room template (as the Net Forge room server names it) and place used by the client and the bots. */
+export const TEMPLATE = "shooter";
+export const PLACE = "yard";
+
+/**
+ * Collected as soon as the module is imported: one process may load more
+ * than one game module (the room server hosts every template), and each
+ * manifest takes its own game before the next module declares.
+ */
+const MANIFEST = collectManifest();
+let compiled: CompiledGame | null = null;
+
+/** The compiled game (weapons, loadout, arena, rounds as sim content). */
+export function arenaGame(): CompiledGame {
+  compiled ??= compileGame(MANIFEST);
+  return compiled;
+}
+
+/** The SimAdapter for this game. `runner` options are server-side measurement modes. */
+export function arenaAdapter(runner?: RunnerOptions): SimAdapter<EngineRoomWorld, InputCommand> {
+  return engineSimAdapter({ name: GAME_NAME, version: GAME_VERSION, game: arenaGame(), ...(runner ? { runner } : {}) });
+}
+
+/** Cosmetic ids for store SKUs (0 is the default finish). */
+export const COSMETICS: Readonly<Record<string, number>> = { skin_neon: 1, skin_chrome: 2 };

package/src/store.ts

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