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

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NetNet Capital Management
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,34 @@
+@netforge/template-arena (VOLTYARD)
+Copyright (c) 2026 NetNet Capital Management
+
+An original game. No names, characters, maps, models, sounds or code from
+any other game or franchise.
+
+Art and sound
+- Models come from the per-style asset library
+  (@netforge/asset-library): CC0 1.0 models by Kenney (Mini
+  Characters, Blaster Kit, Space Kit, Car Kit), each pack listed with its
+  source URL and licence verification in that package's NOTICE and
+  manifest/packs.json. The files are fetched and built, never committed
+  here; the build copies only the models this game uses.
+- Fallback shapes (client/library.ts) are generated from three.js
+  primitives; all textures are drawn on a canvas at load; all sounds are
+  synthesized with WebAudio oscillators (client/audio.ts).
+
+Dependencies (unmodified, via npm)
+- three.js 0.186.1 (https://github.com/mrdoob/three.js), MIT.
+- nipplejs 1.0.4 (https://github.com/yoannmoinet/nipplejs), MIT.
+- @netforge/engine and @netforge/engine-sim (this repository);
+  see their NOTICE files (bitECS MPL-2.0, Rapier Apache-2.0, Colyseus MIT,
+  zod MIT).
+
+Patterns (ideas only)
+- The arena shooter genre's general mechanics (twin-stick aim, weapon
+  loadouts, respawns, frag limits, health drops, a scoreboard). Mechanics,
+  not expression; no level, weapon, character or text was copied from any
+  game.
+- Lag compensation for hitscan as described in Valve's public Source
+  multiplayer networking write-up (ideas only; implemented in the Net Forge
+  room server and engine-sim's arena seam).
+- Hit-stop, screen shake and damage numbers as described in common
+  game-feel talks and articles (e.g. "Juice it or lose it", GDC 2012).

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# @netforge/template-arena
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 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`, the newcomer test and the store test. |
+| `llms.txt`, `llms-full.txt` | How to change the game, for agents. |
+
+## 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.
+
+## 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
+npx -y @netforge/mcp
+```
+
+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
+
+MIT. See LICENSE and NOTICE.

package/client/audio.ts

@@ -0,0 +1,43 @@
+/**
+ * VOLTYARD's sound cues on the engine's FeelAudio (FeelKit). Shots, downs
+ * and heals play real CC0 samples from the asset library's audio section
+ * (ARENA_SAMPLES, loaded by the engine's SoundPlayer with a music loop);
+ * the FeelKit's own cues (impact, bigKill, hurt) take the library's samples
+ * by name. Two cues stay synthesized on purpose so you can tell them apart
+ * without looking: the hit tick and the two-note kill confirm. Every cue
+ * keeps a synth recipe as the fallback when a sample cannot load. Others'
+ * cues ("-o") are played quieter. Starts on the first user gesture.
+ */
+import type { FeelAudio } from "@netforge/engine/runtime";
+
+/** Arena cue name -> library sound id (soundBank's `cues` overrides). */
+export const ARENA_SAMPLES: Readonly<Record<string, string>> = {
+  zap: "audio.sfx.shoot",
+  "zap-o": "audio.sfx.shoot",
+  wide: "audio.sfx.shoot",
+  "wide-o": "audio.sfx.shoot",
+  down: "audio.sfx.downed",
+  "down-o": "audio.sfx.kill",
+  heal: "audio.sfx.revive",
+};
+
+export function defineArenaCues(a: FeelAudio): void {
+  a.define("zap", { wave: "square", f0: 1300, f1: 500, ms: 50, gain: 0.35 }, { minGapMs: 40, voices: 3 });
+  a.define("zap-o", { wave: "square", f0: 1300, f1: 500, ms: 50, gain: 0.35 }, { minGapMs: 40, voices: 3 });
+  a.define("wide", { wave: "square", f0: 260, f1: 60, ms: 140, gain: 0.6 }, { minGapMs: 60, voices: 2 });
+  a.define("wide-o", { wave: "square", f0: 260, f1: 60, ms: 140, gain: 0.6 }, { minGapMs: 60, voices: 2 });
+  a.define("beam", { wave: "sawtooth", f0: 1800, f1: 120, ms: 220, gain: 0.7 }, { minGapMs: 60, voices: 2 });
+  a.define("beam-o", { wave: "sawtooth", f0: 1800, f1: 120, ms: 220, gain: 0.7 }, { minGapMs: 60, voices: 2 });
+  a.define("hitmark", { wave: "triangle", f0: 2600, f1: 1900, ms: 40, gain: 0.55 }, { minGapMs: 35, voices: 2, pitchVar: 0.03 });
+  a.define("confirm", { wave: "triangle", f0: 660, f1: 990, ms: 120, gain: 0.8 }, { minGapMs: 80, voices: 2, pitchVar: 0 });
+  a.define("confirm2", { wave: "triangle", f0: 990, f1: 1980, ms: 200, gain: 0.8 }, { minGapMs: 80, voices: 2, pitchVar: 0 });
+  a.define("down-o", { wave: "triangle", f0: 520, f1: 260, ms: 160, gain: 0.3 }, { minGapMs: 120, voices: 2 });
+  a.define("down", { wave: "sawtooth", f0: 300, f1: 40, ms: 600, gain: 0.8 }, { minGapMs: 300, voices: 1 });
+  a.define("heal", { wave: "sine", f0: 440, f1: 880, ms: 180, gain: 0.6 }, { minGapMs: 150, voices: 1 });
+}
+
+/** Our kill: two rising notes. */
+export function killConfirm(a: FeelAudio): void {
+  a.play("confirm");
+  setTimeout(() => a.play("confirm2"), 90);
+}

package/client/decor.ts

@@ -0,0 +1,22 @@
+/**
+ * Library models the VOLTYARD scene draws on its own (template machinery,
+ * not game content). The build copies these with the models game.ts uses.
+ */
+/** Seat bots: a different townsperson from the players' model. */
+export const BOT_MODEL = "style.lowpoly.mini_male_e";
+/** The blaster every wirejack holds. */
+export const HELD_MODEL = "style.lowpoly.blaster_h";
+/** Each transformer pillar: a generator machine. */
+export const PILLAR_MODEL = "style.lowpoly.generator";
+/** Wirejacks are drawn this tall, m. */
+export const PLAYER_HEIGHT = 1.9;
+
+/** [library id, height m, how many] parked outside the fence. */
+export const YARD_DECOR: readonly (readonly [string, number, number])[] = [
+  ["style.lowpoly.truck_flat", 2, 3],
+  ["style.lowpoly.van", 2, 3],
+  ["style.lowpoly.barrels", 1.3, 6],
+  ["style.lowpoly.satellite_dish", 3.2, 2],
+];
+
+export const SCENE_MODELS: readonly string[] = [BOT_MODEL, HELD_MODEL, PILLAR_MODEL, ...YARD_DECOR.map(([id]) => id)];

package/client/host.ts

@@ -0,0 +1,96 @@
+/**
+ * Net Forge as host. Framed by Net Forge, the page URL carries
+ * the Kit flags and the host posts one message; played on its own, none of
+ * this applies and the game behaves exactly as before.
+ *
+ *   ?host=netnet       the host draws Invite and sign-in; the game hides its own
+ *   ?coin=TICKER       the coin the HUD names (2 to 6 capitals or digits)
+ *   ?title=NAME        the game's own name for the wordmark and the tab title
+ *   ?player=guest      no wallet is connected: play pays nothing, and the HUD
+ *                      says "not earning" instead of a balance
+ *   ?player=play       the token has not launched: coins are play money
+ *
+ * The player flag changes while the game runs (a wallet connects), so the
+ * host also posts { kind: "netnet-kit", type: "player", mode }. Only the
+ * parent window is listened to, and only when the URL says it is the host.
+ */
+
+export type PlayerMode = "earning" | "guest" | "play";
+
+export interface HostFlags {
+  /** Framed by Net Forge. */
+  readonly framed: boolean;
+  /** The coin's ticker, when the host names one. */
+  readonly coin: string | null;
+  /** The game's own name, when the host names one. */
+  readonly title: string | null;
+  /** What play pays the person at the screen. Standalone play is "earning" (the game's own kit decides). */
+  readonly player: PlayerMode;
+}
+
+const TICKER_RE = /^[A-Z0-9]{2,6}$/;
+
+export function hostFlags(params: URLSearchParams): HostFlags {
+  const framed = params.get("host") === "netnet";
+  const coin = params.get("coin");
+  // eslint-disable-next-line no-control-regex
+  const title = (params.get("title") ?? "").replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim().slice(0, 40);
+  const player = params.get("player");
+  return {
+    framed,
+    coin: coin && TICKER_RE.test(coin) ? coin : null,
+    title: title || null,
+    player: framed && (player === "guest" || player === "play") ? player : "earning",
+  };
+}
+
+/**
+ * The player mode the host named on the URL, or null when it named none (a
+ * connected player on a live game gets no flag, only the posted message) or
+ * the page is not framed by Net Forge.
+ */
+export function namedPlayer(params: URLSearchParams): PlayerMode | null {
+  if (params.get("host") !== "netnet") return null;
+  const player = params.get("player");
+  return player === "earning" || player === "guest" || player === "play" ? player : null;
+}
+
+/**
+ * The store's note under its prices, from one source of truth. Once the host
+ * has named the player mode (on the URL or in a message), that mode decides,
+ * exactly as it does for the coin box: a live game never calls its coins play
+ * money. Standalone play, or a host that names no mode (the studio's drafts),
+ * keeps the room's own word (`welcome.earnLive`).
+ */
+export function storeNote(hostMode: PlayerMode | null, earnLive: boolean, symbol: string): string {
+  if (hostMode === "play") return "Play money until launch";
+  if (hostMode === "guest") return `Connect a wallet to earn ${symbol}`;
+  if (hostMode === "earning") return "";
+  return earnLive ? "" : "Play money until launch";
+}
+
+/** A host message, checked: anything else is ignored. */
+export function playerFrom(data: unknown): PlayerMode | null {
+  if (typeof data !== "object" || data === null) return null;
+  const m = data as Record<string, unknown>;
+  if (m["kind"] !== "netnet-kit" || m["type"] !== "player") return null;
+  const mode = m["mode"];
+  return mode === "earning" || mode === "guest" || mode === "play" ? mode : null;
+}
+
+/** Calls `cb` with each player mode the host posts. Framed pages only. */
+export function onHostPlayer(flags: HostFlags, cb: (mode: PlayerMode) => void): void {
+  if (!flags.framed || window.parent === window) return;
+  window.addEventListener("message", (e: MessageEvent<unknown>) => {
+    if (e.source !== window.parent) return;
+    const mode = playerFrom(e.data);
+    if (mode) cb(mode);
+  });
+}
+
+/** Tells the host the game is up, so it can post the current player mode. */
+export function postReady(flags: HostFlags): void {
+  if (!flags.framed || window.parent === window) return;
+  // The host's origin is not known to an opaque-origin frame; the message is one public flag.
+  window.parent.postMessage({ kind: "netnet-kit", type: "ready" }, "*");
+}