@netforge/template-arena 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@netforge/template-arena",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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",
+    "./package.json": "./package.json",
+    "./llms.txt": "./llms.txt",
+    "./llms-full.txt": "./llms-full.txt"
+  },
+  "files": [
+    "src",
+    "client",
+    "!client/vite.config.ts",
+    "llms.txt",
+    "README.md",
+    "NOTICE",
+    "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"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "nipplejs": "1.0.4",
+    "three": "0.186.1",
+    "@netforge/asset-library": "0.2.0",
+    "@netforge/engine": "0.2.0",
+    "@netforge/engine-sim": "0.2.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"
+  },
+  "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.
+// 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 } });

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);
+      },
+    },
+  };
+}