@netforge/engine 0.1.0 → 0.2.0

package/README.md

@@ -1,148 +1,101 @@
 # @netforge/engine
 
-The client side of the Net Forge game engine.
+The Net Forge game engine client: a typed, declarative game API and a three.js renderer (WebGPU with a WebGL2 fallback) for multiplayer browser games.
 
-Two entry points, on purpose:
+One simulation is shared by client and server (an ECS with Rapier physics, a fixed tick and snapshots, in `@netforge/engine-sim`), ten finished multiplayer games ship as templates (`@netforge/template-*`), and the whole API is built to be written by your own coding agent.
 
-| Import | Who uses it | What it holds |
-|---|---|---|
-| `@netforge/engine` | generated game code (the model) | `game`, `prefab`, `system`, `earn`, `store`, `engine.test.run`: declarative, Zod-validated, no DOM, no renderer, no netcode |
-| `@netforge/engine/runtime` | templates, the Net Forge shell, the demo | three.js renderer (WebGPU, WebGL2 fallback), `InstancedCrowd`, `CameraRig`, `InputController` (keyboard/mouse, nipplejs touch), `AssetLoader` (glTF + meshopt + KTX2), `ArenaClient`, `SystemScheduler`, `collectManifest` |
-
-A game module never reaches the renderer, netcode or physics.
-Bad declarations throw `GameDefinitionError` with one actionable line per
-issue, e.g. `model: reference assets by library id (e.g. "style.lowpoly.bat"), never by URL or path`.
-
-## Status (Template 1)
-
-- Declarations, validation, manifest cross-checks and the tick-based
-  `SystemScheduler`, plus `weapon()`, `upgrade()`, pickup prefabs, bosses,
-  and systems' `alive()`, `on(event)`, `respawnDead()`, `end(outcome)`.
-- `@netforge/engine/game` runs a declared game on engine-sim:
-  `compileGame` (manifest to sim content), `GameRunner` (systems on a run
-  clock, game events, run phases), `EarnTracker`, the engine-sim
-  `SimAdapter` (`engineSimAdapter`, wire schema `engineSchema`) and a
-  playtest bot. `engine.test.run` plays the declared game when there is one
-  (kills, waves, levels, earn by rule, softlock, ms/tick).
-- `@netforge/engine/net` is the client half of the netcode (the server
-  half runs in the hosted Net Forge room server): prediction and reconciliation, interpolation, delta
-  snapshots with per-kind fields, input packets, client clock adjustment
-  for one-input-per-tick sims, the wire protocol and the Colyseus room client.
-- `AssetLoader` is built but no template uses it yet (Template 1 art is
-  procedural, see packages/template-survivor/client/library.ts).
-
-## Status (Template 2, the arena shooter)
-
-- `game({ template: "arena", arena, round, players: { loadout, bots,
-  respawn, drop } })`, weapon kinds `blaster` (with `spread`) and `beam`,
-  and `emit(event, players?)` for crediting chosen players.
-- `compileGame` builds the yard (floor, pillars, spawns) and the arena
-  rules; it refuses survivor weapons in an arena and arena weapons in a
-  survivor game, with a line the model can act on.
-- `GameRunner` adds the round clock and frag limit (a round is a run),
-  `opponent.killed` / `player.died` / `round.top` / `round.finished`
-  events, kills and deaths per player, a kill feed in `RunInfo`, and seat
-  bots (`players.bots`) that fill empty seats while a human is present and
-  never earn. Killing a bot scores and shows in the feed but pays no earn
-  rule, and `round.top` pays only when another person was in the round
-  (both arrive as unpaid events, and so does anything a system emits while
-  handling one). Bots play through `arenaBotInput` (game/arena-bot.ts), a pure
-  function of the present, so a room's run replays exactly.
-- `engineSimAdapter` gives arena games the lag-compensation hooks the room
-  server's core already calls (`hitscans`, `hitboxes`, `applyHit`), runs
-  the client without authority, and grants store upgrades by name.
-- `engine.test.run` plays arena games with the bots and reports kills,
-  deaths, rounds, `topScore` and `scorers`.
-- The registry seals a game once its manifest is collected, so one process
-  (the room server) can load several game modules in turn.
-
-## Board genres (`@netforge/engine/rules`)
-
-Tower defense, idle, card battler and monster collector do not run on
-engine-sim's action world. Each is a deterministic rules module (integer
-state, a seeded PRNG word, no clocks) behind the same `SimAdapter` seam,
-so the room server, the netcode, the referee, run verification, the store,
-the stake and losable gear are the ones every template uses.
-
-- `RulesGenre<S>` (rules/kit.ts): `create`, `join`, `act` (a player's
-  validated action), `step` (one tick), `outcome`, `view(state, player)`
-  (what that player may see: hidden hands stay hidden), `entities` (moving
-  things, interpolated on the client) and the genre's own bot.
-- `rulesAdapter(genre, manifest)`: earn rules per player per run
-  (`EarnTracker`), seat bots that never earn, unpaid events, the late-start rule
-  (world progress never pays a run that started after the world began),
-  store upgrades and gear as recorded room commands capped at maxLevel,
-  cosmetics, the end screen and `run.reset`. Each player's avatar (a cursor,
-  a builder, a walking hero) is predicted from its own input.
-- `SimAdapter.infoFor(world, player)`: run state sent to one player only
-  (the room sends it when it changed, every `infoEveryTicks`).
-- Declarations: each genre adds its own typed functions to this package's
-  root (tower defense: `towerBoard`, `tower`, `waves`), validated by its own
-  Zod schemas and stored with `declareContent`. `engine.test.run` plays a
-  board genre through `playRules` and reports its own checks under
-  `rules.checks`.
-
-## Game feel kit (`runtime/feel`)
-
-One-line components every template uses. `FeelKit` wraps them:
-`hit`, `kill`, `hurt`, `levelUp`, `land`, `dash` and `footstep`, with the
-presets `subtle`, `default` and `heavy`. The parts work alone too:
-
-- `Trauma`: seeded-noise trauma shake.
-- `FeelClock`: hit-stop and slow motion with a smooth catch-up; the netcode never pauses.
-- `HitFlash` and `KnockbackOffsets`: flash and spring squash per entity id.
-- `Spring` and `Spring3`.
-- `DamageNumbers`: pooled, and merges rapid hits on one id.
-- `Tweens` and `Ease`, with `pop`, `shakeEl` and `countUp` for UI.
-- `FeelAudio`: procedural cues with throttles, voice limits, pan and distance falloff; `addBuffer` takes CC0 samples later. `Footsteps` alongside it.
-- `Rumble`: Gamepad dual-rumble, with a `navigator.vibrate` fallback.
-
-`CameraRig` adds `addTrauma`, `punch` (an FOV kick), a smoothed and
-clamped lead and a dead zone. Its old `shake(amplitude, seconds)` still
-works.
-
-## Render pipeline (`runtime/render`)
-
-`createRenderStack(handle, scene, camera, { preset, quality, bloom, outline })`
-returns the whole pipeline. Call `stack.frame(dt, focus)` in place of
-`renderer.render(scene, camera)`. It includes:
-
-- `LightingRig`: hemisphere light plus a sun whose shadow follows the focus, texel-snapped.
-- `PostFX`: bloom, colour grade, vignette and hurt pulse, tone mapping applied once, FXAA, and an optional depth outline.
-- `Atmosphere`: fog and a sky gradient.
-- `QualityManager`: tiers and dynamic resolution.
-- `GpuParticles`: one draw, with motion on the GPU.
-- `GroundDecals` and `GroundRings`.
-
-It runs on WebGPU and on WebGL2. Animated characters:
-
-- `AnimatedCrowd`: procedural vertex animation for instanced crowds.
-- `VatCrowd` and `bakeVertexAnimation`: vertex-animation textures for skinned crowds.
-- `AnimatedCharacter`: glTF skinned meshes on an `AnimationMixer` with locomotion blending.
-- `buildSegmentRig`: a procedural rig for tests and demos.
-
-The demo shows all of it with `?fx=1` (`&outline=1`, `&crowd=vat`,
-`&preset=dusk`, `&quality=low`).
-
-Game code declares the look and feel it wants: `game({ look })`,
-`prefab({ feel })` and `weapon({ feel })`, validated by `lookSchema` and
-`feelSchema`. See `llms.txt`.
-
-## Demo
+## Install
 
 ```sh
-pnpm --filter @netforge/engine-sim build
-pnpm --filter @netforge/engine demo          # http://localhost:5310
-# ?enemies=2000  ?webgl=1 (force the WebGL2 backend)  ?autopilot=1 (scripted input)
+npm install @netforge/engine
 ```
 
-Measure in headless Chrome (raw CDP, no puppeteer dependency):
+Node 20 or later. The package ships ES modules with TypeScript types.
 
-```sh
-pnpm --filter @netforge/engine demo:build
-pnpm --filter @netforge/engine exec vite preview --config demo/vite.config.ts --port 5311
-CHROME_BIN=/path/to/chrome node packages/engine/scripts/measure-demo.mjs "http://localhost:5311/?autopilot=1" 20 --enable-unsafe-webgpu --use-angle=metal
+## Example
+
+A game is one file, `src/game.ts`, that declares what the game is. It imports only `@netforge/engine` and never touches the renderer, the netcode or the physics. This is a cut-down version of the arena shooter template:
+
+```ts
+import { earn, game, prefab, store, weapon } from "@netforge/engine";
+
+export default game({
+  template: "arena",
+  style: "lowpoly",
+  places: { yard: { chunks: "places/yard", spawn: [0, 1, 0] } },
+  players: { prefab: "style.lowpoly.mini_male_f", max: 16, loadout: ["arc_rifle"], bots: 6, respawn: 3, drop: "volt_cell" },
+  arena: { halfSize: 26, pillars: [[0, 0, 2.6]], spawns: [[22, 22], [-22, -22], [22, -22], [-22, 22]] },
+  round: { seconds: 180, frags: 25 },
+});
+prefab("volt_cell", { model: "style.lowpoly.cell_heal", health: 1, speed: 0, kind: "pickup", value: 35 });
+weapon("arc_rifle", { kind: "blaster", damage: 12, cooldown: 0.15, range: 26, speed: 44 });
+earn.rule("live_wire", { when: "opponent.killed", n: 3, pay: 4, oncePer: "run" });
+earn.stake({ min: 10, max: 100, multiple: 2 });
+store.sku("skin_neon", { coins: 300, grants: { cosmetic: 1 } });
 ```
 
-The script always launches with `--use-mock-keychain --password-store=basic`
-and a throwaway profile, so it never prompts for the macOS keychain.
+Then play it headless with bots and check it:
+
+```ts
+import { engine } from "@netforge/engine";
+
+const report = await engine.test.run({
+  ticks: 60 * 240,
+  bots: 4,
+  assert: [{ name: "someone scores", check: (r) => r.kills > 0 }],
+});
+console.log(report.kills, report.earned, report.softlock, report.msPerTick);
+```
+
+Bad declarations throw `GameDefinitionError` with one actionable line per issue, for example `model: reference assets by library id (e.g. "style.lowpoly.bat"), never by URL or path`.
+
+## Entry points
+
+| Import | Who uses it | What it holds |
+|---|---|---|
+| `@netforge/engine` | game code (`src/game.ts`) | `game`, `prefab`, `weapon`, `upgrade`, `system`, `director`, `earn`, `store`, `keeper`, `achievement`, `mission`, `title`, `economy`, `metaUpgrade`, `dungeon`, the board genre declarations (`towerBoard`, `tower`, `waves`, `saltFlat`, `plant`, `marsh`, `creature`, `move`, `card`, `cardTable`), and `engine.test.run`. Declarative, Zod-validated, no DOM. |
+| `@netforge/engine/runtime` | template clients | the three.js renderer (`createRenderer`), `createRenderStack`, `CameraRig`, `InputController` (keyboard, mouse, gamepad, touch), `AssetLoader` (glTF, meshopt, KTX2), `FeelKit` and its parts, `SoundPlayer`, `ArenaClient`, `SystemScheduler`, `collectManifest`. |
+| `@netforge/engine/game` | templates, room hosts, tests | `compileGame`, `collectManifest`, `GameRunner`, `EarnTracker`, `engineSimAdapter` (the SimAdapter on `@netforge/engine-sim`). |
+| `@netforge/engine/net` | template clients | the client half of the netcode: prediction and reconciliation, interpolation, delta snapshots, input packets, clock adjustment and the room client. |
+| `@netforge/engine/rules` | board genres | `rulesAdapter`, `playRules` and the genre modules: deterministic rules (tower defense, idle, cards, collector) behind the same SimAdapter seam. |
+| `@netforge/engine/voxel` | template clients | the voxel style's core. |
+| `@netforge/engine/earn-source` | tools | reads and rewrites the `earn.rule(...)` lines of a `src/game.ts` as source text. |
+
+Game code imports only the root. Everything else is template machinery.
+
+## What the root API covers
+
+- **Templates**: `TEMPLATES` lists them: `survivor`, `arena`, `dungeon`, `racer`, `platformer`, `tower-defense`, `party`, `idle`, `cards` and `collector`.
+- **Art**: `game({ style })` picks one of `STYLES`: `pixel`, `lowpoly`, `toon`, `voxel`, `ps1` or `handdrawn`. Models are asset library ids such as `"style.lowpoly.ghost"`, never URLs or file paths.
+- **Look and feel**: `game({ look })`, `prefab({ feel })` and `weapon({ feel })` are presentation only and never change the simulation.
+- **Earn**: every game declares at least one `earn.rule(...)` and exactly one `earn.stake({ min, max, multiple })`. The build fails without them. Ids are lower_snake_case.
+- **Coins and the store**: `store.sku(...)` sells in-run consumables, cosmetics and unlocks by default. Permanent stat upgrades are opt-in through `economy({ metaUpgrades: true })` and `metaUpgrade(...)`, capped by the engine (`META_MAX_PER_STAT`, `META_MAX_TOTAL`).
+- **Systems**: `system(id, ctx => ...)` gets `every`, `after`, `on`, `emit`, `spawn`, `spawnEdge`, `players`, `end` and a seeded `random`, on a tick clock.
+- **Playtest**: `engine.test.run({ ticks, bots, seed?, enemies?, bot?, assert? })` plays the game on the server sim and reports kills, deaths, waves, runs, earn by rule, softlocks, ms per tick and fun metrics.
+
+`GAME-DESIGN.md` holds the design rules the playtest gate measures (a readable opening, fast rewards, no on-screen spawns) and the recommended coin model.
+
+## For AI agents
+
+- Read `llms.txt` (look, feel, physics and rendering) and `llms-full.txt` (`llms.txt`, `GAME-DESIGN.md` and the API reference in one file).
+- Each template package (`@netforge/template-*`) ships its own `llms.txt`, `llms-full.txt` and `AGENTS.md` for its genre.
+- The Net Forge MCP server gives an agent the same tools over stdio: `npx -y @netforge/mcp` (package `@netforge/mcp`, bin `netforge-mcp`). Tools: `netforge_list_templates`, `netforge_create_game`, `netforge_explain_api`, `netforge_search_docs`, `netforge_validate_game`, `netforge_run_playtest`, `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 add the server with `claude mcp add netforge -- npx -y @netforge/mcp`. Any other MCP client takes this config:
+
+```json
+{ "mcpServers": { "netforge": { "command": "npx", "args": ["-y", "@netforge/mcp"] } } }
+```
+
+## Play a game locally
+
+`@netforge/kit-play` runs a game folder (`netnet.json` plus `src/game.ts`) on your own computer with play money. See its README.
+
+## Docs
+
+- https://forge.netnet.capital/docs/packages/engine
+- `llms.txt`, `llms-full.txt` and `GAME-DESIGN.md` in this package
+
+## License
+
+MIT. See `LICENSE` and `NOTICE`.

package/dist/api/schemas.js

@@ -675,8 +675,8 @@ export const earnPotSchema = z
     /** Share of every pot that stays in the reward pool (0.01 to 0.5). */
     recycle: z.number().min(0.01).max(0.5),
     /**
-     * Pots are OFF by default until a legal review clears
-     * them. A declared pot runs only with `enabled: true`; without it the
+     * Pots are off by default; the R-16 legal review approved them
+     * (2026-10-23), so a game opts in with `enabled: true`. Without it the
      * terms are kept for later and no room takes an entry.
      */
     enabled: z.boolean().default(false),

package/dist/game/earn-source.d.ts

@@ -115,7 +115,7 @@ export interface SourceEarnPot {
     readonly entry: number;
     /** Share of every pot that stays in the reward pool. */
     readonly recycle: number;
-    /** Pots are off by default until a legal review: true only when the line says `enabled: true`. */
+    /** A pot runs only when the line says `enabled: true` (off by default; R-16 approved 2026-10-23). */
     readonly enabled?: boolean;
 }
 /** The game's PvP pot, read only (null when it has none or it is not written with plain values on one line). */

package/dist/net/protocol.d.ts

@@ -205,4 +205,11 @@ export interface RunIdMessage {
 export interface CreateOptions {
     readonly place: string;
     readonly template: string;
+    /**
+     * The game's slug when one room server runs several games of one template
+     * (launched Net Forge games, keyed by slug). Absent: the template's own game.
+     */
+    readonly game?: string;
 }
+/** A game slug as the GameFactory and the room server take it. */
+export declare const GAME_SLUG_RE: RegExp;

package/dist/net/protocol.js

@@ -6,3 +6,5 @@ export const MSG_SNAPSHOT = 2; // server -> client, bytes (netcode/snapshot.ts)
 export const ROOM_NAME = 'instance';
 /** Guest profile ids: 16-80 characters of A-Z, a-z, 0-9, _ or - (the same rule as Launcher guest drafts). */
 export const GUEST_ID_RE = /^[A-Za-z0-9_-]{16,80}$/;
+/** A game slug as the GameFactory and the room server take it. */
+export const GAME_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;

package/dist/net/room-client.d.ts

@@ -6,6 +6,12 @@ export interface JoinParams {
     readonly endpoint: string;
     readonly place: string;
     readonly template: string;
+    /**
+     * The launched game's slug: one room server runs every launched game of a
+     * template side by side. Absent: the page's own ?game= (Net Forge frames a
+     * launched game with it), else the template's own game.
+     */
+    readonly game?: string;
     readonly wallet?: string;
     /** Session token from POST /auth/sign-in. Without it the seat plays as a guest and earns nothing. */
     readonly session?: string;
@@ -53,5 +59,7 @@ export interface RoomConnection<W, I> {
     claim(): Promise<unknown>;
     leave(): Promise<void>;
 }
+/** The page's ?game= slug (set by Net Forge on a launched game's frame), or null outside a browser or without one. */
+export declare function pageGame(): string | null;
 export declare function joinRoom<W, I>(sim: SimAdapter<W, I>, p: JoinParams): Promise<RoomConnection<W, I>>;
 export declare function connectReservation<W, I>(sim: SimAdapter<W, I>, endpoint: string, reservation: Parameters<Client['consumeSeatReservation']>[0]): Promise<RoomConnection<W, I>>;

package/dist/net/room-client.js

@@ -3,14 +3,26 @@
 // demo and the headless load bots.
 import { Client } from '@colyseus/sdk';
 import { DEFAULT_CLIENT, NetClient } from './client.js';
-import { MSG_INPUT, MSG_SNAPSHOT, } from './protocol.js';
+import { GAME_SLUG_RE, MSG_INPUT, MSG_SNAPSHOT, } from './protocol.js';
+/** The page's ?game= slug (set by Net Forge on a launched game's frame), or null outside a browser or without one. */
+export function pageGame() {
+    try {
+        const g = typeof location === 'undefined' ? null : new URLSearchParams(location.search).get('game');
+        return g && GAME_SLUG_RE.test(g) ? g : null;
+    }
+    catch {
+        return null;
+    }
+}
 export async function joinRoom(sim, p) {
+    const game = p.game ?? pageGame();
     const res = await fetch(`${p.endpoint}/world/join`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({
             place: p.place,
             template: p.template,
+            ...(game ? { game } : {}),
             ...(p.wallet ? { wallet: p.wallet } : {}),
             ...(p.session ? { session: p.session } : {}),
             ...(p.guest ? { guest: p.guest } : {}),

package/llms-full.txt

@@ -0,0 +1,460 @@
+# @netforge/engine (llms-full.txt)
+
+> Everything an agent needs to write and change a Net Forge game in one file. A game is one module, src/game.ts, that imports only @netforge/engine and declares the game with game(), prefab(), weapon(), upgrade(), system(), earn.rule(), earn.stake() and store.sku(). Templates draw it, run it on the server simulation and handle netcode, physics and rendering. Part 1 is llms.txt (look, feel, physics and rendering), Part 2 is GAME-DESIGN.md (the design rules the playtest gate measures, and the coin model), Part 3 is the API reference.
+
+## Contents
+
+- Part 1: llms.txt
+- Part 2: GAME-DESIGN.md
+- Part 3: API reference
+
+## Part 1: llms.txt
+
+## Net Forge game engine: physics, game feel and rendering (llms.txt)
+
+> The engine every Net Forge game runs on. Two
+> layers matter here:
+>  1. Game code (src/game.ts) only DECLARES how things look and feel, with
+>     `look` on game() and `feel` on prefab() and weapon(). Templates draw it.
+>  2. Template code (client/ and the sim) uses the runtime APIs below:
+>     the physics world in @netforge/engine-sim, and the feel kit and
+>     render stack in @netforge/engine/runtime.
+> Generated game code never imports the runtime. It cannot reach the
+> renderer, netcode or physics, and it does not need to.
+
+### 1. Game code: look and feel declarations
+
+Everything here is presentation. It never changes the simulation, so it
+is always safe to tune. Unknown values fail the build with a message.
+
+#### The look of the whole game (game({ look }))
+
+game({
+  template: "survivor", style: "lowpoly", places: { ... }, players: { ... },
+  look: { preset: "dusk", bloom: 1.3, fog: 0.4, vignette: 0.4, tint: "#ffd9a0" },
+});
+
+- preset: "night" | "dusk" | "day" | "studio". Sets the sun, sky, fog and
+  colour grade together. Default "night".
+- bloom: glow on bright and emissive things, 0 (off) to 3. Default 1.
+- shadows: sun shadows on or off (on by default above the low quality tier).
+- outline: a toon outline around shapes (true or false).
+- fog: 0 (clear) to 1 (thick).
+- exposure (0.2 to 3), saturation (0 to 2), contrast (0.5 to 1.5),
+  vignette (0 to 1), tint ("#rrggbb", a grading colour over the frame).
+
+Slow devices drop shadows, post and resolution by themselves (quality
+tiers and dynamic resolution), so turning things on never breaks 60 fps.
+
+#### How a prefab dies and takes hits (prefab({ feel }))
+
+prefab("brute", { model: "style.lowpoly.brute", health: 160, speed: 2.2, radius: 0.8, mass: 6,
+  feel: { particles: "burst", decal: "scorch", sound: "boom", shake: 0.5, hitStop: 0.06, color: "#ff4d5e" } });
+
+#### How a weapon's impacts look (weapon({ feel }))
+
+weapon("frost_ring", { kind: "nova", damage: 6, cooldown: 0.8, range: 5, knockback: 8,
+  feel: { particles: "magic", decal: "ring", color: "#7ad7ff", shake: 0.1 } });
+
+feel fields, all optional:
+- shake: screen shake added, 0 to 1 (0.2 a bump, 0.6 a big hit).
+- hitStop: seconds the picture freezes on impact (0.03 to 0.08 feels good, 0.2 max).
+- particles: "sparks" | "burst" | "embers" | "smoke" | "hitSpark" | "dust" | "magic".
+- decal: "none" | "scorch" | "splat" | "ring" (left on the ground, fades).
+- sound: "none" | "hit" | "crunch" | "boom" | "zap" | "chime" | "thud".
+- color: "#rrggbb" for particles, decals and flashes.
+- flash: false turns off the white hit flash.
+
+#### Knockback is physics
+
+weapon knockback is metres per second pushed into each enemy, divided by
+the enemy's mass. Enemies knocked hard stagger, slide, bounce off pillars
+and shove the enemies behind them. mass 1 is light, 6 is a brute, 20 a
+boss (light hits barely move it).
+
+#### Dungeon levels (game({ field }) with walls and floors)
+
+const CRYPT = dungeon({ seed: 2026, rooms: 10, cell: 24, size: [12, 18], corridor: 6, loops: 2 });
+game({ template: "dungeon", ..., field: CRYPT.field });
+
+dungeon(...) grows a floor plan from a seed: rooms on a grid, joined by
+corridors, the start room centred on [0, 0] and the deepest room as
+CRYPT.boss. field.walls are boxes [x, z, halfX, halfZ] that stop players,
+enemies and bolts; field.floors are the only ground (spawns land on them,
+and enemies behind a wall path round it through the doors on a flow
+field). Systems get onScreen(x, z) to bring enemies in where nobody is
+looking. A system's room logic reads CRYPT.rooms and CRYPT.roomAt(x, z).
+
+### 2. Template code: the physics world (@netforge/engine-sim)
+
+Deterministic Rapier on client and server. No rendering dependency.
+
+import { initSim, createPhysics, restorePhysics, Layer } from "@netforge/engine-sim";
+await initSim();
+const p = createPhysics({ gravity: [0, -20, 0], tickRate: 30 });
+p.addStaticBox([30, 0.5, 30], [0, -0.5, 0], { layer: Layer.Level });
+const crate = p.addBody({ type: "dynamic", shape: { box: [0.4, 0.4, 0.4] }, position: [0, 2, 0],
+  mass: 20, friction: 0.7, restitution: 0.2, layer: Layer.Prop });
+const bolt = p.addBody({ type: "dynamic", shape: { sphere: 0.1 }, ccd: true, gravityScale: 0,
+  linearVelocity: [80, 0, 0], layer: Layer.Projectile, mask: Layer.Level | Layer.Enemy });
+const zone = p.addTrigger({ box: [2, 2, 2] }, [5, 1, 0]);
+const hero = p.addCharacter({ position: [0, 1, 0], maxSpeed: 7, jumpVelocity: 8, coyoteTicks: 5,
+  jumpBufferTicks: 5, airAccel: 18, dashTicks: 6, dashSpeed: 22, dashCooldownTicks: 30 });
+const { events, characters } = p.step(new Map([[hero, { moveX: 1, moveZ: 0, jump: true, dash: false }]]));
+
+- Bodies: dynamic, kinematic (setKinematicTarget) or static; box, sphere,
+  capsule, cylinder; mass or density, friction, restitution, damping,
+  gravityScale, lockRotations, sensor, ccd, userData (a NetId).
+- Layers: Layer.Level, Player, Enemy, Projectile, Pickup, Prop, Trigger,
+  Debris, User1..8. A pair collides only when each mask holds the other.
+- Events from step(): contact.start, contact.end, trigger.enter,
+  trigger.exit, sorted, with a < b.
+- Forces: applyImpulse, applyForce (one step), applyKnockback(id, from,
+  strength, { lift, byMass }). Knockback works on characters too.
+- Queries: raycast(origin, dir, maxDist, { mask, exclude, includeSensors })
+  for line of sight and hitscan; raycastAll; shapeCast; overlap.
+- Joints: addJoint({ kind: "fixed" | "ball" | "hinge" | "slider", a, b }).
+- Character motor: slopes (climb and slide), steps, ground snapping, coyote
+  time, jump buffering, variable jump height, ground and air acceleration,
+  terminal velocity, dash with buffer, cooldown and invulnerability,
+  pushing dynamic bodies. Per-step reports: grounded, landed, jumped,
+  dashed, hitCeiling, groundNormal. characterState / setCharacterState for
+  reconcile.
+- Netcode: snapshot() and restorePhysics(bytes) restore bit-exact;
+  stateHash() hashes every pose, velocity and motor state.
+- Rapier 0.21 already stops small fast spheres on thin walls; use round
+  projectiles (thin spinning planks can still tunnel).
+
+### 3. Template code: game feel (@netforge/engine/runtime)
+
+import { FeelKit } from "@netforge/engine/runtime";
+const feel = new FeelKit({ preset: "default" });   // "subtle" | "default" | "heavy"
+feel.camera = rig;  feel.project = (x, y, z) => scene.project(x, y, z);  feel.particles = stack.particles;
+// per frame
+const { now, dt, realDt } = feel.tick(performance.now());   // hit-stop aware render clock
+feel.hit({ id, x, y, z, amount, big, dirX, dirZ });          // flash, knockback, number, sound, shake
+feel.kill({ x, y, z, big, color });                           // particles, shake, hit-stop when big
+feel.hurt(damage, maxHealth);                                 // shake, stop, rumble, hurtPulse
+feel.levelUp(); feel.dash(); feel.land(0.6); feel.footstep(speed);
+feel.update(dt, realDt);
+
+Parts, each usable alone: Trauma (seeded trauma shake), FeelClock (hit-stop,
+slow motion, smooth catch-up), HitFlash, KnockbackOffsets (spring offsets
+and squash), Spring and Spring3, DamageNumbers (pooled, merges rapid hits),
+Tweens and Ease with pop / shakeEl / countUp for UI, FeelAudio (procedural
+cues, throttles, voice limits, pan, distance) and Footsteps, Rumble
+(Gamepad dual-rumble, navigator.vibrate fallback). CameraRig adds
+addTrauma, punch (FOV kick), a smoothed and clamped lead and a dead zone.
+
+Real sound (SoundPlayer): CC0 samples for the cues and one music loop from
+the asset library's audio section. Samples replace the synth recipes under
+the same cue names (the synth plays until a sample loads, or if it fails).
+
+import { soundBank } from "@netforge/asset-library";
+const sound = new SoundPlayer(feel.audio, { key: "mygame:sound", musicVolume: 0.35 });
+sound.load(soundBank(libraryBase));     // cues: hit impact kill bigKill hurt levelUp gem coin dash step land boss ui pick downed revive shoot
+sound.toggle();                         // the mute (effects and music), remembered; returns true when muted
+feel.audio.play("boss");                // any cue by name
+
+Camera bounds: never show the void past the field.
+rig.setBounds(fieldBounds(half, 16));   // the field plus 16 m of dressed outside ground
+The clamp moves the camera by the overshoot of what it sees (groundFootprint,
+boundsShift); dress that outside strip (ground, trees, fog).
+
+Hero highlight: an outline and a rim on one character (the local hero), as
+extra draws that share its geometry and skeleton; its materials stay as
+they are.
+const hl = new HeroHighlight(character.root, { rim: 0xffd27a, outline: 0x140a02, outlineWidth: 0.05 });
+hl.strength = 0.4;  hl.dispose();
+
+### 4. Template code: rendering (@netforge/engine/runtime)
+
+const stack = createRenderStack(handle, scene, rig.camera, { preset: "night", quality: "auto", bloom: true });
+stack.frame(dt, focus);       // instead of renderer.render(scene, camera)
+stack.particles.burst("bigKill", x, y, z, { color: 0xffc070 });
+stack.decals.add("scorch", x, z, { size: 3 });
+stack.rings.fire(x, z, 6, { color: 0xffb347 });
+stack.post.hurt.value = feel.hurtPulse;
+
+- LightingRig: hemisphere, sun shadow following the focus with texel
+  snapping, presets.
+- PostFX: bloom, grade (contrast, saturation, split tone, vignette, hurt
+  pulse), tone mapping once, FXAA, optional depth outline.
+- Atmosphere: fog (linear or exp2, height fog) and sky gradient. A high
+  top-down camera should set heightFog 0.
+- QualityManager / DynamicResolution: tiers low, medium and high
+  (auto-detected), pixel ratio held to the frame budget.
+- GpuParticles: one draw for every preset; motion runs on the GPU.
+- GroundDecals and GroundRings: pooled, one draw each.
+- AnimatedCrowd: procedural vertex animation for instanced crowds (bob,
+  waddle, lean, hit squash, flash). VatCrowd with bakeVertexAnimation:
+  skinned clips baked to a texture, thousands of instances in one draw.
+  AnimatedCharacter: skinned glTF with locomotion blending.
+- WebGPU pipelines build on first use. Draw one of everything out of sight
+  at load (EMBERWATCH's SurvivorScene.warmup) so the first kill does not
+  hitch.
+
+## Part 2: GAME-DESIGN.md
+
+## Game design playbook
+
+Rules every game on this engine follows. They come from measured play: the
+first survivor build killed every player in 12 seconds, and a fun one kept
+the same bot alive for minutes. The playtest gate measures most of them, and
+a game that breaks them scores low.
+
+### Every genre
+
+1. **A readable opening, with real danger by 0:30.** The first threats
+   reach the player by about 0:20, and health moves by 0:30 to 0:45. The
+   first elite comes at about 0:45 and a mini-boss by 1:30 to 2:00. Nobody
+   dies in the first minute. (The first cut's playtest found no danger for
+   three minutes and scored 4/10. A quiet opening is not an empty one.)
+2. **Reward fast.** The first reward (a level, a kill, a pickup) comes within
+   about 10 seconds, then every 6 to 10 seconds for the first minute.
+3. **Never spawn on screen.** Enemies arrive from just off screen:
+   `director(...)` or `spawnEdge(prefab, { count })`, never `spawn()` or
+   `spawnRing()` at short radii. Pressure follows a moving player, because
+   stragglers far behind are recycled ahead of them.
+4. **Hits are survivable.** Contact damage gives i-frames
+   (`players.hitIframes`, 0.5 s). Twenty enemies touching you means one hit,
+   not twenty.
+5. **Slower than the player unless telegraphed.** Players run at 7 m/s.
+   Fodder moves at 45 to 60% of that, and fast runners up to 85% but fragile.
+   Anything faster or harder-hitting shows a telegraph first.
+6. **Telegraph every big hit.** Charges, slams, blasts and boss patterns
+   show a ground marker for 0.5 to 1 s, using shape and fill and not only
+   red. Over half of late deaths should be telegraphed ones, which means the
+   player misread the threat rather than the game being unfair.
+7. **Death is not a waiting room.** A downed player bleeds for about 10 s
+   and can crawl toward help. Each player gets one free self-revive per run.
+   A player who is out comes back beside a teammate within seconds
+   (`players.downed`), never "out until the next wave".
+8. **A run has a timeline.** It plays like a story with moments: new enemy
+   roles join one at a time, then elites, a mini-boss, an event, a flood, and
+   a final boss. Announce each moment so players always know what just
+   happened and where to go.
+9. **Bosses are moments.** A boss has a silhouette no mob shares and one or
+   two telegraphed attacks to learn. The first fight is short (about 45 s
+   solo), and the reward pops: a hoard chest that brings an evolution onto
+   the cards (`pickup: { effect: "chest", evolve: true }`).
+10. **Tougher, not more.** Past the crowd cap, the director makes new enemies
+   tougher instead of adding bodies. A boss alive halves the spawn rate, and
+   bosses scale with players present.
+11. **Builds have a goal.** Upgrades have numbers players can read ("+1 bolt",
+   "-20% cooldown"). Each weapon pairs with a passive toward an evolution.
+   Solo cards pause the game. Co-op cards do not pause, but they shove
+   enemies back.
+12. **Measure fun with bots.** The gate's human-like bot reacts 200 ms late,
+    kites, and reads cards for a second. Fix what it reports before
+    shipping.
+
+### Horde (survivor-like) targets
+
+| Metric | Target |
+|---|---|
+| First level | 4-10 s |
+| First damage taken | 15-45 s |
+| First elite / first mini-boss | ~0:45 / 1:30-2:00 |
+| First mini-boss fight, solo | ~45 s |
+| Level at 1:00 / 3:00 / 6:00 | ~5 / ~10 / ~15 |
+| Deaths before 1:00 | 0 |
+| Enemies on screen at 0:30 | 30-50 (wave-3 density in minute 1) |
+| Touches taken in minute 1 | 1-3 |
+| Spawns on screen | 0% |
+| Time spent downed or out | under 10% |
+| Solo survival, random picks | 4-7 min |
+
+A good curve is `director({ alive: [[0, 20], [30, 55], [60, 100], [180, 220], [300, 560], [540, 1900]], rate: [[0, 2], [30, 4], [60, 5], [180, 8], [300, 16], [540, 64]], speed: [[0, 1], [240, 1], [600, 1.6]], elites: { from: 45, every: [40, 55] } })`.
+Health and damage curves grow roughly ×1.35 per minute early and flatten
+later. Early gems are worth a little less (`xp` 0.7 at first), so the dense
+first minute does not run the levels hot. Late `speed` keeps endless
+kiting from working. The 2,000-enemy crowd is a late-run payoff, not an
+opening wall.
+
+### Arena shooter
+
+1. **First kill or pickup within about 20 s.** Spawns should be close enough
+   to find a fight, and pickups worth walking to.
+2. **Spawn safety.** No damage in the first 2 s after spawning, and under a
+   quarter of deaths within 3 s of spawning. Spawn points sit out of sight
+   lines, away from the middle.
+3. **Contest the map.** Heals, power weapons and high ground make places
+   worth fighting over. Put them in the open between spawns.
+4. **Readable hits.** Hits flash, kills pop, the feed names who killed whom,
+   and your own shot shows instantly on your screen, before the server
+   agrees.
+5. **Moments.** Announce streaks, put a bounty on the leader, and run a
+   late-round event, so the lead changes hands. When one player has 3x the
+   average kills, a weapon or a position dominates.
+6. **Bots that ramp.** Seat bots fill rooms, play below a new player's level
+   at first and get sharper as people win. They never stomp a newcomer.
+   They never earn, and they are never a coin source: killing a bot scores
+   but pays no earn rule, and "round.top" pays only with another person in
+   the round. Earn comes from beating people.
+
+### How a change request maps to the API
+
+- **"Harder"**: raise the director's `alive`, `rate`, `health` or `damage`
+  keyframes late in the run, never at 0 s.
+- **"Easier"**: lower them, raise `players.hitIframes` or `magnet`, or give
+  the starting weapon more range.
+- **"More enemy types"**: add a prefab and a pool entry with `from: <seconds>`,
+  one new idea at a time. Use `group: [8, 12]` for streams.
+- **"Add a boss"**: add a prefab with `boss: { attacks: [...], rank }` and
+  spawn it with `spawnEdge(id, { count: 1 })` from `after(seconds, ...)`.
+  Give mini-bosses 3 attacks and the final boss 4. Its health scales with
+  players present.
+- **"Smarter" or "trickier enemies"**: give prefabs roles (`ai: "charger"`,
+  `"ranged"`, `"bomber"`, `"shielder"`, `"summoner"`), or add elites.
+- **"Add events" or "waves"**: use `every` or `after` in a system, with
+  `spawnEdge(id, { count, side: "north" })` for a tide from one side,
+  `xpBoost`, `surge` or a fleeing carrier with a chest. `announce` each one,
+  never repeat the same event twice in a row, and skip events while
+  `bossAlive()`.
+- **"More loot" or "a map worth exploring"**: special pickups (heal,
+  vacuum, bomb, chest) as rare drops, props to `scatter`, and a bigger `field`.
+- **"Longer or shorter run"**: move the boss's `after(...)` and stretch the
+  curves' keyframe times.
+- **"More weapons" or "better builds"**: declare 5-8 `levels` per weapon
+  (each a readable change), pair weapons with passives through `evolve`, and
+  give evolutions a new shape. Keep weapons + evolutions within 15.
+- **"Add a character" or "more heroes"**: `keeper(id, { weapon, passive,
+  unlock })`, unlocked by an `achievement`, or declared without an unlock
+  and sold (`store.sku(id, { coins, grants: { keeper: id } })`): earned or
+  bought, never both. A keeper is a different way to play, never a stronger
+  one, and the first keeper is always free.
+- **"Reasons to come back"**: `achievement`s that unlock keepers,
+  `mission`s for daily goals, `title`s for the end screen. None pay coins;
+  coin rewards are earn rules, which are an economy decision. The room
+  server grants them from the run and saves them per player, so they follow
+  the player to every device.
+- **"Sell character unlocks"**: a SKU per keeper with `grants: { keeper }`,
+  on keepers declared without an `unlock`.
+- **"Cosmetics only" or "no pay to win"**: `economy({ store: "cosmetics" })`
+  and only SKUs with `grants: { cosmetic: n }`.
+- **"Let players buy permanent upgrades with coins"**:
+  `economy({ metaUpgrades: true })` and a few `metaUpgrade(...)`s (below).
+- **"Better co-op"**: `players.share` ("nearby" is the default), a
+  `reviveBuff`, `lateJoinBehind`, and `upcoming(...)` countdowns everyone
+  sees.
+
+### The recommended coin model, and why
+
+Every game has coins (1 coin = 1 of the game's own token). How they are
+spent decides whether the game stays fair to the player who never pays, and
+whether a token holder can buy a win. The engine ships one recommended
+model and makes the alternatives declarations, so a
+change request is a one-line change, never new code.
+
+**The default (no declaration; every template uses it).** Coins buy:
+
+- **Cosmetics**: a look owned for good,
+  `store.sku("skin_aurora", { coins: 300, grants: { cosmetic: 1 } })`.
+- **Unlocks**: a keeper (a character, a starting loadout, a sidegrade)
+  declared without an `unlock`,
+  `store.sku("unlock_tinker", { coins: 400, grants: { keeper: "tinker" } })`.
+  An unlock is a different way to play at the same power as the keepers
+  anyone can earn by playing. A keeper is earned (by an achievement) or
+  bought, never both, so a sold keeper cannot be opened another way.
+- **In-run consumables**: used once, inside one run,
+  `store.sku("revive", { coins: 50 })` (no `grants`).
+
+Coins never buy permanent stat power by default. A run is decided by how it
+was played, and a newcomer next to a long-time holder plays the same game.
+
+**Cosmetics only (opt-in):** `economy({ store: "cosmetics" })`. The build
+refuses any SKU that is not a look.
+
+**Meta upgrades (opt-in, never the default):** permanent stat upgrades
+bought with coins, the way many survivor-likes do between runs.
+
+```ts
+economy({ metaUpgrades: true });
+metaUpgrade("hearth", { stat: "maxHealth", step: 0.05, levels: 3, cost: 120, growth: 2 });  // +5% a level: 120, 240, 480
+metaUpgrade("stride", { stat: "speed", step: 0.03, levels: 3, cost: 100, growth: 1.8 });
+```
+
+The engine enforces hard caps that no game can raise: +15% to any one stat
+from meta upgrades, +30% across all of them, at most 5 levels each and 8 per
+game, and geometric costs (each level at least 1.5 times the last). The
+room server applies a player's levels at the start of every run, capped
+again, and the store shows each level's bonus and price. Use them only when
+the creator asks for permanent upgrades, and keep steps small (3-5%).
+
+**Before launch** coins are play money, and play money buys only in-run
+items. Looks, unlocks and meta levels need real coins, so they open at
+launch; nothing bought with play money persists or carries over.
+
+**Where it is enforced.** Prices come from the manifest, never the client.
+A purchase is a coin spend (earned coins first, then the wallet) that the
+room server checks against that price before the item is owned, and the
+item is saved in the player's profile on the server. Spent coins recycle
+to the reward pool for other players, as every coin spend does.
+
+## Part 3: API reference (the package root, `@netforge/engine`)
+
+Game code imports only from the package root. Every declaration validates its input with Zod at import time and throws `GameDefinitionError` with one actionable line per problem. Ids are lower_snake_case (`/^[a-z][a-z0-9_]{0,47}$/`). Asset references are library ids such as `"style.lowpoly.ghost"`, never URLs or file paths.
+
+### Declarations
+
+- `game(def: GameInput): GameDef`: the game itself, declared once and exported as the module's default. `template` is one of `TEMPLATES` (`survivor`, `arena`, `dungeon`, `racer`, `platformer`, `tower-defense`, `party`, `idle`, `cards`, `collector`); `style` is one of `STYLES` (`pixel`, `lowpoly`, `toon`, `voxel`, `ps1`, `handdrawn`). Other fields depend on the template: `places`, `players`, `field`, `arena`, `round`, `look`, `tickRate`.
+- `prefab(id, def: PrefabInput): PrefabDef`: an enemy, boss, pickup or prop. `model`, `appearance`, `health`, `speed`, `radius`, `damage`, `mass`, `ai` (one of `AI_BEHAVIOURS`), `drops`, `kind`, `value`, `boss`, `feel`.
+- `weapon(id, def: WeaponInput): WeaponDef`: `kind` is one of `WEAPON_KINDS` (`nova`, `bolt`, `orbit`, `blaster`, `beam`, `cone`, `chain`, `aura`, `meteor`, `boomerang`); `damage`, `cooldown`, `range`, `speed`, `count`, `spread`, `pierce`, `knockback`, `levels`, `feel`. The build checks which kinds each template accepts (the arena takes `blaster`, `beam` and `nova`).
+- `upgrade(id, def: UpgradeInput): UpgradeDef`: a passive or run upgrade on one of `STAT_KINDS`, with `step` and `maxLevel`.
+- `director(def: DirectorInput): DirectorDef`: the spawn director for horde games, with keyframed curves (`alive`, `rate`, `health`, `damage`) and an enemy pool.
+- `system(name, setup: (ctx: SystemContext) => void): void`: game logic on the tick clock (below).
+- `keeper(id, def)`, `achievement(id, def)`, `mission(id, def)`, `title(id, def)`: characters, unlocks, daily goals and end-screen titles. None of these pay coins.
+- `economy(def?)`: the coin model. The default needs no declaration. `economy({ store: "cosmetics" })` sells looks only; `economy({ metaUpgrades: true })` opts in to `metaUpgrade(...)`.
+- `metaUpgrade(id, { stat, step, levels, cost, growth })`: permanent stat upgrades, capped by the engine at `META_MAX_PER_STAT` per stat and `META_MAX_TOTAL` across all, at most `META_MAX_LEVELS` levels each and `META_MAX_UPGRADES` per game, with costs growing by at least `META_MIN_GROWTH`.
+- `dungeon(spec: DungeonSpec): DungeonLayout`: a seeded floor plan (`seed`, `rooms`, `cell`, `size`, `corridor`, `loops`) whose `.field` goes into `game({ field })`; `.rooms`, `.roomAt(x, z)` and `.boss` feed systems.
+- Board genres: `towerBoard`, `tower`, `waves` (tower defense); `saltFlat`, `plant` (idle); `marsh`, `creature`, `move` (monster collector); `cardTable`, `card` (card battler). Each template's `llms.txt` documents its own fields.
+
+### Earn and the store
+
+- `earn.rule(id, { when, n?, pay, oncePer })`: pays `pay` whole coins when the event `when` (a dotted name such as `"wave.cleared"`) reaches its `n`th count; `oncePer` is `"run"`, `"day"` or `"lifetime"`. Every game declares at least one.
+- `earn.stake({ min, max, multiple })`: the buy-in run, declared exactly once by every game. A staked run pays its normal earn plus a share of `stake x multiple` (multiple 1 to `STAKE_MAX_MULTIPLE`), by the share of the run's most earn the player makes.
+- `earn.pot({ entry, recycle, enabled? })`: an optional PvP pot for arena games. Off unless `enabled: true`.
+- `store.sku(id, { coins?, usdg?, grants? })`: a store item priced in coins (1 coin is 1 of the game's own token). No `grants` is an in-run consumable or a run upgrade named after a declared `upgrade`; `{ cosmetic: n }` is a look owned for good; `{ keeper: id }` unlocks a keeper; `{ gear: upgradeId, loseBelow }` is losable gear.
+- `STAKE_REASON` (`"stake"`) and `POT_REASON` (`"pot"`) are reserved and never SKU ids.
+
+### The system context
+
+`system(name, (ctx) => { ... })` receives a deliberately small, deterministic context. Systems run only on the authoritative side (the room host and the headless playtest); clients see the results in snapshots.
+
+- Clock: `tick()`, `time()`, `every(seconds, n => ...)`, `after(seconds, fn)`, `onTick(fn)`.
+- Players: `players()` returns each player's `id`, `position`, `health`, `alive`, `kills`, `deaths` and `bot`.
+- Events: `on(event, ids => ...)` for the sim's own events (`enemy.killed`, `boss.killed`, `player.downed`, `player.revived`, `player.levelup`, `player.died`; arena: `opponent.killed`, `round.top`, `round.finished`; and `run.started`) and any you emit; `emit(event, ids?)` credits those players, or everyone present.
+- Spawning: `spawnEdge(prefab, { count, around?, side?, spread?, scale?, elite? })` brings enemies in just off screen (prefer it); `spawn(prefab, [x, y, z], { elite? })`, `spawnRing(prefab, { count, radius, around? })`, `spawnPickup(prefab, [x, y, z])`, `scatter(prefab, count)`, `clear(prefab)`, `alive(prefab?)`, `onScreen(x, z)`.
+- Pacing: `announce(text, { tone? })`, `upcoming(label, seconds)`, `bossAlive()`, `pauseDirector(seconds)`, `surge(multiplier, seconds)`, `xpBoost(multiplier, seconds)`.
+- Run control: `respawnDead()`, `end("won" | "lost")`, and `random()` (the sim's seeded PRNG; never `Math.random`).
+
+### Playtest
+
+`engine.test.run(opts: HarnessOptions): Promise<HarnessReport>` plays the declared game on the server simulation.
+
+- Options: `ticks`, `bots`, and optionally `seed`, `tickRate`, `enemies` (stress), `enemyMix`, `bot` (`"basic"` or `"human"`), `picks` (`"random"` or `"greedy"`), and `assert`: a list of `{ name, check: (report) => boolean }`.
+- Report: `kills`, `deaths`, `wave`, `runs` (`won`, `lost`), `maxLevel`, `peakEnemies`, `topScore`, `scorers`, `earned` (by rule id), `earnEmitted`, `msPerTick`, `p99MsPerTick`, `softlock`, `fun` (fun metrics, horde and arena games) and `rules` (the board genres' own checks).
+
+```ts
+import { engine } from "@netforge/engine";
+const r = await engine.test.run({ ticks: 30 * 180, bots: 4, seed: 3, assert: [{ name: "kills", check: (x) => x.kills > 500 }] });
+```
+
+### Constants and schemas
+
+`GameDefinitionError`, `TEMPLATES`, `STYLES`, `AI_BEHAVIOURS`, `WEAPON_KINDS`, `STAT_KINDS`, `LOOK_PRESETS`, `PARTICLE_PRESETS`, `DECAL_PRESETS`, `SOUND_CUES`, `TITLE_STATS`, `META_STATS`, the `META_*` caps, `STAKE_MAX_MULTIPLE`, `STAKE_MAX_COINS`, `TOWER_KINDS`, `TOWER_STATS`, `PLANT_KINDS`, `IDLE_STATS`, `ELEMENTS`, `MOVE_EFFECTS`, `COLLECTOR_STATS`, `CARD_STATS`, `EFFECT_KINDS`, `EFFECT_TARGETS`, `APPEARANCE_PARTS`, `appearanceSchema` and `dungeonSchema`. Every input and definition type (`GameInput`, `PrefabInput`, `WeaponInput`, `EarnRuleInput`, `SkuInput` and the rest) is exported for TypeScript.
+
+### Other entry points (template code only)
+
+- `@netforge/engine/runtime`: `createRenderer`, `createRenderStack`, `CameraRig`, `fieldBounds`, `InputController`, `AssetLoader`, `FeelKit`, `SoundPlayer`, `InstancedCrowd`, `ArenaClient`, `SystemScheduler`, `collectManifest`, `createStyledView`, `createPixelStyle`.
+- `@netforge/engine/game`: `compileGame`, `collectManifest`, `GameRunner`, `EarnTracker`, `engineSimAdapter`, `engineSchema`, `botInput`, `HumanBot`, `Director`.
+- `@netforge/engine/net`: the client netcode (prediction, reconciliation, interpolation, delta snapshots, the room client).
+- `@netforge/engine/rules`: `rulesAdapter`, `playRules` and the board genres' rules modules.
+- `@netforge/engine/voxel` and `@netforge/engine/earn-source`.
+
+### Tools for agents
+
+The Net Forge MCP server runs with `npx -y @netforge/mcp` (package `@netforge/mcp`, bin `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`. `@netforge/kit-play` runs a game folder (`netnet.json` and `src/game.ts`) locally with play money: `npx kit-play`.
+
+Docs: https://forge.netnet.capital/docs/packages/engine

package/llms.txt

@@ -1,4 +1,4 @@
-# NetNet game engine: physics, game feel and rendering (llms.txt)
+# Net Forge game engine: physics, game feel and rendering (llms.txt)
 
 > The engine every Net Forge game runs on. Two
 > layers matter here:

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@netforge/engine",
-  "version": "0.1.0",
-  "description": "NetNet game runtime client: the typed game API the model writes against, and the three.js runtime (WebGPU with WebGL2 fallback) that plays it.",
+  "version": "0.2.0",
+  "description": "Net Forge game engine client: a typed declarative game API and a three.js WebGPU/WebGL2 renderer for multiplayer browser games.",
+  "keywords": [
+    "game-engine",
+    "multiplayer",
+    "browser-game",
+    "html5-game",
+    "threejs",
+    "three",
+    "webgpu",
+    "webgl",
+    "netcode",
+    "client-side-prediction",
+    "typescript",
+    "gamedev",
+    "ai-agents",
+    "mcp",
+    "vibe-coding",
+    "net-forge"
+  ],
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +52,10 @@
     "./voxel": {
       "types": "./dist/runtime/styles/voxel/core.d.ts",
       "default": "./dist/runtime/styles/voxel/core.js"
-    }
+    },
+    "./package.json": "./package.json",
+    "./llms.txt": "./llms.txt",
+    "./llms-full.txt": "./llms-full.txt"
   },
   "files": [
     "dist",
@@ -42,18 +63,22 @@
     "GAME-DESIGN.md",
     "llms.txt",
     "NOTICE",
-    "LICENSE"
+    "LICENSE",
+    "llms-full.txt"
   ],
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "homepage": "https://forge.netnet.capital/docs/packages/engine",
+  "bugs": {
+    "url": "https://github.com/netnetdev/net-forge/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/netnetdev/net-forge.git",
     "directory": "packages/engine"
   },
-  "homepage": "https://github.com/netnetdev/net-forge/tree/main/packages/engine#readme",
   "engines": {
     "node": ">=20"
   },
@@ -62,7 +87,7 @@
     "nipplejs": "1.0.4",
     "three": "0.186.1",
     "zod": "4.4.3",
-    "@netforge/engine-sim": "0.1.0"
+    "@netforge/engine-sim": "0.2.0"
   },
   "devDependencies": {
     "@types/three": "0.186.0",
@@ -71,9 +96,6 @@
     "vitest": "3.2.7",
     "@types/node": "22.20.1"
   },
-  "bugs": {
-    "url": "https://github.com/netnetdev/net-forge/issues"
-  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.api.json && tsc -p tsconfig.demo.json",