@netforge/template-survivor 0.0.0-stage → 0.2.0

package/AGENTS.md

@@ -0,0 +1,62 @@
+# Extending EMBERWATCH
+
+EMBERWATCH is the survivor-like co-op template of the Net Forge game engine. This file tells a coding agent how to change the game safely. `llms.txt` in this package has the full recipe book for this genre, and `llms-full.txt` adds the whole `src/game.ts` as a worked example.
+
+## The one file to edit
+
+Change the game by editing `src/game.ts` only. It holds declarations, not engine code. client/names.ts holds the display labels for weapon, upgrade and earn ids. In a downloaded game folder, labels players read live in src/names.json. Everything else (the client, the manifest, the store hooks, the simulation, the netcode) is template machinery.
+
+## Import only @netforge/engine
+
+`src/game.ts` imports from `@netforge/engine` and nothing else. The template's game imports:
+
+```ts
+import { achievement, director, earn, game, keeper, mission, prefab, store, system, title, upgrade, weapon } from "@netforge/engine";
+```
+
+Also available for this genre: `economy`, `metaUpgrade`. `earn` has `earn.rule(...)` and `earn.stake(...)`; `store` has `store.sku(...)`. `system(id, ctx => ...)` gets the systems API described in `llms.txt`. The renderer, input, netcode and physics live elsewhere and are not reachable from game code.
+
+## Rules the build enforces
+
+- Ids are lower_snake_case.
+- Every game declares at least one `earn.rule(...)` (mandatory earn) and one `earn.stake(...)` (the buy-in run), on one top-level line. A game without either does not build.
+- Asset ids are library ids such as `style.lowpoly.turret`, never URLs or file paths, and must exist in the asset library.
+- A survivor game needs one enemy prefab, one weapon and `players.weapon`.
+- Drops must be pickup prefabs. At most 15 weapons (evolutions count) and 8 upgrades.
+- `game({ style })` is the art style the creator picked (lowpoly, toon, ps1, pixel, voxel or handdrawn). Keep it.
+- Keep the store SKUs the client is wired to, at their prices: revive and skin_aurora (and the ember_charm gear). "stake" is reserved and is never a SKU id.
+
+## Validate
+
+- With the MCP server (`npx -y @netforge/mcp`, bin `netforge-mcp`): call `netforge_validate_game` on the game. It returns one line per problem.
+- In this package: `npx vitest run` runs `test/harness.test.ts`, `test/host.test.ts`, `test/store.test.ts`. A bad declaration throws `GameDefinitionError` with a line you can act on.
+
+## Playtest
+
+- With the MCP server: call `netforge_run_playtest`.
+- In code: `import { engine } from "@netforge/engine"` and run `engine.test.run({ ticks: 30 * 180, bots: 4, assert: [] })`. It reports kills, wave, maxLevel, earned by rule, deaths, runs won and lost, softlock and ms per tick. With `bot: "human"` a human-like bot plays and `report.fun` holds the fun metrics the gate scores (first threat, first level, downs before 1:00, spawns on screen and more).
+
+## Play locally
+
+```sh
+mkdir -p my-game/src && cd my-game
+npm init -y && npm install @netforge/kit-play @netforge/engine @netforge/template-survivor
+cp node_modules/@netforge/template-survivor/src/game.ts src/
+echo '{"template":"survivor"}' > netnet.json
+npx kit-play        # opens http://127.0.0.1:4663
+```
+
+The MCP tool `netforge_play_locally` does the same. Coins are play money; nothing pays out and no chain or wallet is involved. Edit `src/game.ts` and run it again to try a change.
+
+## What not to do
+
+- Do not write renderers, netcode, physics or bot AI. The template already has them.
+- Do not use asset URLs or file paths. Use library ids.
+- 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 store SKUs the client is wired to.
+- Do not spawn enemies on screen; the director brings them in just off screen.
+
+## Docs
+
+https://forge.netnet.capital/docs/templates/survivor

package/CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md
+
+Read AGENTS.md before changing this game.
+
+The five hard rules:
+
+1. Edit only `src/game.ts`.
+2. Import only `@netforge/engine`.
+3. Ids are lower_snake_case.
+4. Declare at least one `earn.rule(...)` and exactly one `earn.stake(...)`.
+5. No renderers, netcode, physics or asset URLs.

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,30 @@
+@netforge/template-survivor (EMBERWATCH)
+Copyright (c) 2026 NetNet Capital Management
+
+An original game. No names, characters, sprites, models, sounds or code
+from any other game or franchise. Nothing from PokéSurvivor (its code and
+sprites are non-commercial) or SpriteCollab was used or consulted for code.
+
+Art and sound
+- Models come from the per-style asset library
+  (@netforge/asset-library): CC0 1.0 models by Quaternius (keepers,
+  enemies) and Kenney (Nature Kit trees, rocks and stumps), 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; textures are drawn on a canvas at load.
+
+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 survivor-like genre's general mechanics (auto-firing weapons, XP
+  gems, pick-one-of-three level-ups, waves, a boss). Mechanics, not
+  expression; no level, item, enemy or text was copied from any game.
+- 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,74 @@
-# Temporary Holding Version
+# @netforge/template-survivor
 
-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.
+A survivor-like co-op game template for Net Forge: 4 players against up to 2,000 enemies at once (EMBERWATCH).
+
+Four keepers hold a field at night against a swarm that grows every wave. Weapons fire by themselves, gems level you up, you pick one of three upgrades, you stand by a downed teammate to revive them, and the team survives ten waves and breaks the Bell Warden.
+
+The room server is authoritative at 30 Hz. Your own keeper is predicted. The spawn director brings every enemy in just off screen on the run's clock, with curves for the pacing.
+
+Earn: waves cleared (2 and 7), the boss killed, and 500 kills, once per run each. Real-token earn and stakes run only on the hosted Net Forge server.
+
+## Install
+
+```sh
+npm install @netforge/template-survivor
+```
+
+You normally do not import this package yourself. `kit play` runs it on your own computer, and the Net Forge MCP server and studio copy its `src/game.ts` as the starting point for a new game.
+
+## Play it locally
+
+```sh
+mkdir -p my-game/src && cd my-game
+npm init -y && npm install @netforge/kit-play @netforge/engine @netforge/template-survivor
+cp node_modules/@netforge/template-survivor/src/game.ts src/
+echo '{"template":"survivor"}' > netnet.json
+npx kit-play        # opens http://127.0.0.1:4663
+```
+
+Coins are play money and nothing pays out. Real-token earning, stakes and claims run only on the hosted Net Forge server.
+
+## Change the game
+
+The ember nova is the starting weapon. Make it hit harder and reach further:
+
+```ts
+weapon("ember_nova", {
+  kind: "nova", damage: 16, cooldown: 1.1, range: 4.4, knockback: 2.5,
+  // levels and evolve stay as they are
+});
+```
+
+Save `src/game.ts` and run `npx kit-play` again.
+
+## Files
+
+| Path | What |
+|---|---|
+| `src/game.ts` | The game, declarations only: the field, the swarm, weapons, upgrades, the director, systems, earn, store. |
+| `src/manifest.ts` | Loads and compiles the game; `survivorAdapter()` and `survivorGame()` for the room host and the client. |
+| `src/store.ts` | Store hooks on the Kit's names: a revive (50 coins), a cosmetic (300 coins) and the ember charm gear (150 coins). |
+| `client/` | The browser client: three.js scene, HUD, input (keys, gamepad, touch), game feel. `client/names.ts` holds display labels. |
+| `test/` | Playtest bots through `engine.test.run`, the local host and the store. |
+| `llms.txt` | How to change the game, for agents. |
+
+## Controls
+
+Keys: WASD or arrows move, Space dash, 1 2 3 pick a card. Touch: drag on the left half, the DASH button, tap a card. The backquote key shows stats. Open the Invite link in another tab or on a phone on the same network to play together (`?room=<id>`).
+
+## For AI agents
+
+Read `AGENTS.md` and `llms.txt` in this package before changing the game. `llms-full.txt` adds the whole `src/game.ts` as a worked example.
+
+Agents can also drive this template through the Net Forge MCP server: run `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`.
+
+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/survivor
+- `llms.txt` and `llms-full.txt` in this package (also exported as `@netforge/template-survivor/llms.txt` and `@netforge/template-survivor/llms-full.txt`)
+
+## License
+
+MIT. See `LICENSE` and `NOTICE`.

package/client/debris.ts

@@ -0,0 +1,257 @@
+/**
+ * Client-side physics dressing on engine-sim's PhysicsWorld (Rapier, the
+ * same build the server runs): chunks that fly off killed enemies and
+ * bounce off the floor and pillars, and a scatter of rocks and stumps
+ * the keepers shove around and novas blast away.
+ *
+ * Presentation only. None of it feeds back into the authoritative sim, so
+ * it never needs to match the server or other players exactly; every
+ * client drives the props from the same interpolated keeper positions, so
+ * what they see agrees closely anyway.
+ */
+import { Color, InstancedMesh, Matrix4, MeshStandardMaterial, Quaternion, Vector3 } from "three/webgpu";
+import type { BufferGeometry, Material, Scene } from "three/webgpu";
+import { CylinderGeometry, DodecahedronGeometry } from "three/webgpu";
+import { Layer, createPhysics } from "@netforge/engine-sim";
+import type { BodyId, PhysicsWorld, ResolvedSimConfig } from "@netforge/engine-sim";
+
+const HZ = 60;
+const MAX_CHUNKS = 220;
+const MAX_STEPS = 4;
+const CHUNK_LIFE = 2.2;
+
+interface Chunk {
+  id: BodyId;
+  life: number;
+  max: number;
+  size: number;
+  color: Color;
+}
+
+interface Prop {
+  id: BodyId;
+  barrel: boolean;
+  /** Last speed, for impact thuds. */
+  speed: number;
+}
+
+/** Seeded PRNG so every client scatters the props in the same places. */
+function rng(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    s = (s + 0x6d2b79f5) >>> 0;
+    let t = s;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** An art style's own drawing of a debris shape (the voxel style's cube chunks, rocks and stumps); null keeps the primitive. */
+export type DebrisShape = (name: "chunk" | "rock" | "stump") => { readonly geometry: BufferGeometry; readonly material: Material } | null;
+
+function instanced(geometry: BufferGeometry, color: number, capacity: number, emissive = 0x000000, styled?: ReturnType<DebrisShape>): InstancedMesh {
+  const material = styled?.material ?? new MeshStandardMaterial({ color, roughness: 0.75, flatShading: true, emissive, emissiveIntensity: 0.6 });
+  const mesh = new InstancedMesh(styled?.geometry ?? geometry, material, capacity);
+  mesh.count = 0;
+  mesh.frustumCulled = false;
+  mesh.castShadow = true;
+  mesh.receiveShadow = true;
+  const white = new Color(1, 1, 1);
+  for (let i = 0; i < capacity; i++) mesh.setColorAt(i, white);
+  return mesh;
+}
+
+export class PhysicsDressing {
+  readonly physics: PhysicsWorld;
+  private readonly chunks: Chunk[] = [];
+  private readonly props: Prop[] = [];
+  private readonly keepers = new Map<number, BodyId>();
+  private readonly chunkMesh: InstancedMesh;
+  private readonly crateMesh: InstancedMesh;
+  private readonly barrelMesh: InstancedMesh;
+  private acc = 0;
+  private readonly m = new Matrix4();
+  private readonly q = new Quaternion();
+  private readonly p = new Vector3();
+  private readonly s = new Vector3();
+  private readonly random = rng(0xe3b1);
+  /** Impacts this frame (world position and speed), for thud sounds. */
+  readonly impacts: { x: number; y: number; z: number; speed: number }[] = [];
+  /** Effects fired so far (playtest checks). */
+  readonly counts = { chunks: 0, blasts: 0 };
+
+  constructor(scene: Scene, config: ResolvedSimConfig, opts: { props?: boolean; shape?: DebrisShape } = {}) {
+    this.physics = createPhysics({ gravity: [0, -24, 0], tickRate: HZ });
+    const P = this.physics;
+    const h = config.arena.halfExtent;
+    const wall = config.arena.wallHeight;
+    P.addStaticBox([h + 1, 0.5, h + 1], [0, -0.5, 0], { friction: 0.8, layer: Layer.Level });
+    P.addStaticBox([h + 1, wall, 0.5], [0, wall, h + 0.5], { layer: Layer.Level });
+    P.addStaticBox([h + 1, wall, 0.5], [0, wall, -h - 0.5], { layer: Layer.Level });
+    P.addStaticBox([0.5, wall, h + 1], [h + 0.5, wall, 0], { layer: Layer.Level });
+    P.addStaticBox([0.5, wall, h + 1], [-h - 0.5, wall, 0], { layer: Layer.Level });
+    for (const pl of config.arena.pillars) {
+      P.addBody({ type: "static", shape: { cylinder: [pl.height / 2, pl.radius] }, position: [pl.x, pl.height / 2, pl.z], layer: Layer.Level, friction: 0.6 });
+    }
+
+    // Props: crates and barrels around the pillars and in the open, the same scatter on every client.
+    const props = rng(0x51f7);
+    const spots: [number, number][] = [];
+    for (const pl of config.arena.pillars) {
+      for (let k = 0; k < 3; k++) {
+        const a = props() * Math.PI * 2;
+        const d = pl.radius + 1.2 + props() * 1.5;
+        spots.push([pl.x + Math.cos(a) * d, pl.z + Math.sin(a) * d]);
+      }
+    }
+    for (let k = 0; k < 14; k++) {
+      const a = props() * Math.PI * 2;
+      const d = 6 + props() * (h - 12);
+      spots.push([Math.cos(a) * d, Math.sin(a) * d]);
+    }
+    if (opts.props === false) spots.length = 0;
+    for (const [x, z] of spots) {
+      const barrel = props() < 0.4;
+      const yaw = props() * Math.PI;
+      const id = P.addBody({
+        type: "dynamic",
+        shape: barrel ? { cylinder: [0.45, 0.35] } : { box: [0.4, 0.4, 0.4] },
+        position: [x, barrel ? 0.45 : 0.4, z],
+        rotation: [0, Math.sin(yaw / 2), 0, Math.cos(yaw / 2)],
+        density: 40,
+        friction: 0.7,
+        restitution: 0.15,
+        linearDamping: 0.4,
+        angularDamping: 0.6,
+        layer: Layer.Prop,
+        mask: Layer.Level | Layer.Prop | Layer.Player | Layer.Debris,
+      });
+      this.props.push({ id, barrel, speed: 0 });
+    }
+
+    this.chunkMesh = instanced(new DodecahedronGeometry(1, 0), 0xffffff, MAX_CHUNKS, 0, opts.shape?.("chunk"));
+    // One family with the field's stone and the Nature Kit stumps: loose rocks and cut stumps, not crates and barrels.
+    this.crateMesh = instanced(new DodecahedronGeometry(0.5), 0x5e5246, Math.max(1, this.props.length), 0, opts.shape?.("rock"));
+    this.barrelMesh = instanced(new CylinderGeometry(0.33, 0.38, 0.9, 7), 0x4e3a28, Math.max(1, this.props.length), 0, opts.shape?.("stump"));
+    scene.add(this.chunkMesh, this.crateMesh, this.barrelMesh);
+  }
+
+  /** Keepers push props: one kinematic capsule per player, moved to where it is drawn. */
+  keeper(owner: number, x: number, y: number, z: number, up: boolean): void {
+    let id = this.keepers.get(owner);
+    if (id === undefined) {
+      id = this.physics.addBody({ type: "kinematic", shape: { capsule: [0.5, 0.4] }, position: [x, y, z], layer: Layer.Player, mask: Layer.Prop | Layer.Debris });
+      this.keepers.set(owner, id);
+    }
+    this.physics.setKinematicTarget(id, [x, up ? y : -5, z]);
+  }
+
+  /** Forget keepers not seen this frame. */
+  keepOnly(owners: ReadonlySet<number>): void {
+    for (const [owner, id] of this.keepers) {
+      if (owners.has(owner)) continue;
+      this.physics.removeBody(id);
+      this.keepers.delete(owner);
+    }
+  }
+
+  /** Chunks off a killed enemy, thrown along the push direction. */
+  shatter(x: number, z: number, radius: number, color: Color, count: number, dirX = 0, dirZ = 0): void {
+    const P = this.physics;
+    this.counts.chunks += count;
+    for (let i = 0; i < count; i++) {
+      if (this.chunks.length >= MAX_CHUNKS) this.retire(0);
+      const size = radius * (0.22 + this.random() * 0.25);
+      const a = this.random() * Math.PI * 2;
+      const sp = 2 + this.random() * 3.5;
+      const id = P.addBody({
+        type: "dynamic",
+        shape: { box: [size, size, size] },
+        position: [x + Math.cos(a) * radius * 0.5, radius + 0.2 + this.random() * radius, z + Math.sin(a) * radius * 0.5],
+        density: 8,
+        friction: 0.6,
+        restitution: 0.35,
+        angularDamping: 0.3,
+        linearVelocity: [Math.cos(a) * sp + dirX * 5, 3.5 + this.random() * 4, Math.sin(a) * sp + dirZ * 5],
+        angularVelocity: [(this.random() - 0.5) * 18, (this.random() - 0.5) * 18, (this.random() - 0.5) * 18],
+        layer: Layer.Debris,
+        mask: Layer.Level | Layer.Prop,
+      });
+      const life = CHUNK_LIFE * (0.7 + this.random() * 0.6);
+      this.chunks.push({ id, life, max: life, size, color });
+    }
+  }
+
+  /** A blast (nova) shoves props and chunks out of `radius`. */
+  blast(x: number, z: number, radius: number, strength: number): void {
+    const P = this.physics;
+    this.counts.blasts++;
+    const hits = P.overlap({ cylinder: [1.5, radius] }, [x, 1.5, z], { mask: Layer.Prop | Layer.Debris });
+    for (const id of hits) P.applyKnockback(id, [x, 0, z], strength, { lift: strength * 0.35 });
+  }
+
+  private retire(i: number): void {
+    const c = this.chunks[i];
+    if (!c) return;
+    this.physics.removeBody(c.id);
+    this.chunks[i] = this.chunks[this.chunks.length - 1] as Chunk;
+    this.chunks.pop();
+  }
+
+  update(dt: number): void {
+    this.impacts.length = 0;
+    this.acc = Math.min(this.acc + dt, MAX_STEPS / HZ);
+    while (this.acc >= 1 / HZ) {
+      this.acc -= 1 / HZ;
+      this.physics.step();
+    }
+    for (let i = this.chunks.length - 1; i >= 0; i--) {
+      const c = this.chunks[i] as Chunk;
+      c.life -= dt;
+      if (c.life <= 0) this.retire(i);
+    }
+    // Draw.
+    const P = this.physics;
+    let n = 0;
+    for (const c of this.chunks) {
+      const [x, y, z] = P.position(c.id);
+      const [qx, qy, qz, qw] = P.rotation(c.id);
+      const k = Math.min(1, c.life / (c.max * 0.35));
+      this.p.set(x, y, z);
+      this.q.set(qx, qy, qz, qw);
+      this.s.setScalar(c.size * 1.25 * k);
+      this.m.compose(this.p, this.q, this.s);
+      this.chunkMesh.setMatrixAt(n, this.m);
+      this.chunkMesh.setColorAt(n, c.color);
+      n++;
+    }
+    this.chunkMesh.count = n;
+    this.chunkMesh.instanceMatrix.needsUpdate = true;
+    if (this.chunkMesh.instanceColor) this.chunkMesh.instanceColor.needsUpdate = true;
+    let crates = 0;
+    let barrels = 0;
+    this.s.setScalar(1);
+    for (const prop of this.props) {
+      const [x, y, z] = P.position(prop.id);
+      const [vx, vy, vz] = P.velocity(prop.id);
+      const speed = Math.hypot(vx, vy, vz);
+      if (prop.speed - speed > 3) this.impacts.push({ x, y, z, speed: prop.speed - speed });
+      prop.speed = speed;
+      const [qx, qy, qz, qw] = P.rotation(prop.id);
+      this.p.set(x, y, z);
+      this.q.set(qx, qy, qz, qw);
+      this.m.compose(this.p, this.q, this.s);
+      if (prop.barrel) this.barrelMesh.setMatrixAt(barrels++, this.m);
+      else this.crateMesh.setMatrixAt(crates++, this.m);
+    }
+    this.crateMesh.count = crates;
+    this.barrelMesh.count = barrels;
+    this.crateMesh.instanceMatrix.needsUpdate = true;
+    this.barrelMesh.instanceMatrix.needsUpdate = true;
+  }
+
+  get liveChunks(): number {
+    return this.chunks.length;
+  }
+}

package/client/decor.ts

@@ -0,0 +1,21 @@
+/**
+ * Library models the EMBERWATCH scene draws on its own (template machinery,
+ * not game content): the forest past the wall.
+ * The build copies these with the models game.ts uses.
+ */
+
+/** Enemy models are drawn about this many hit radii tall. */
+export const ENEMY_HEIGHT_PER_RADIUS = 3.2;
+/** Keepers are drawn this tall, m. */
+export const KEEPER_HEIGHT = 1.8;
+
+/** [library id, height m, how many] in a ring outside the wall. */
+export const DECOR: readonly (readonly [string, number, number])[] = [
+  ["style.lowpoly.tree_pine", 5.5, 26],
+  ["style.lowpoly.tree_pine_tall", 7.5, 14],
+  ["style.lowpoly.tree_dark", 5, 14],
+  ["style.lowpoly.rock_large", 1.8, 12],
+  ["style.lowpoly.stump", 0.7, 10],
+];
+
+export const SCENE_MODELS: readonly string[] = 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" }, "*");
+}