@netforge/template-dungeon 0.0.0-stage → 0.2.0

package/AGENTS.md

@@ -0,0 +1,74 @@
+# Extending CRYPTWICK
+
+CRYPTWICK is the co-op dungeon crawl template of the Net Forge game engine. The template already has the crypt's walls and floors, enemies that path through doors, weapons, XP shards, level-ups, bosses, co-op revive, netcode, rendering, touch controls, earn and the store. You change the game by changing declarations and the crawl system. Read `llms.txt` for every field, `llms-full.txt` for the complete worked example, and `GAME-DESIGN.md` in `@netforge/engine` for the design rules the playtest gate scores.
+
+## The one file to edit
+
+- `src/game.ts` is the whole game, including the `crawl` system (room wakes, `ENCOUNTERS` by depth, `STIR_AFTER`, reliquaries). Change it in place.
+- `src/names.json`, next to it, holds the title and every label players read (weapons, upgrades, earn rules, store items). Add a label there for every new id.
+- Everything else (`src/manifest.ts`, `src/store.ts`, `client/`, `test/`, `scripts/`) is template machinery. Do not edit it.
+
+## Imports
+
+`src/game.ts` imports only from `@netforge/engine`. The shipped game uses:
+
+```ts
+import { achievement, dungeon, earn, game, keeper, mission, prefab, store, system, title, upgrade, weapon } from "@netforge/engine";
+```
+
+Also available: `economy` and `metaUpgrade` (opt-in, only when the creator asks for permanent upgrades; the engine caps them at +15% a stat and +30% in all).
+
+## Declarations
+
+- `dungeon({ seed, rooms, cell, size, corridor, loops })` grows the floor plan. Pass its `field` to `game({ field })`. `CRYPT.rooms`, `CRYPT.boss` and `CRYPT.roomAt(x, z)` feed the crawl.
+- `game({ template: "dungeon", style, places, field, look?, players: { prefab, max, weapon, xp, magnet, hitIframes, downed, ... } })`.
+- `prefab(id, { model, health, speed, radius, damage, ai, drops?, attack?, split?, mass? })` for the dead, bosses and pickups. `ai` is one of the engine's behaviours (`chase`, `runner`, `tank`, `ranged`, `bomber`, `healer`, `summoner`, `charger` and others).
+- `weapon(id, { kind, damage, cooldown, range, levels?, evolve? })`, at most 15 including evolutions.
+- `upgrade(id, ...)`, at most 8.
+- `system(id, (ctx) => { ... })` with `every`, `after`, `onTick`, `spawn`, `spawnPickup`, `spawnEdge`, `spawnRing`, `announce`, `upcoming`, `alive`, `players`, `emit`, `on`, `respawnDead`, `end`, `onScreen`, `random`, `tick`, `time` and more (see llms.txt, Systems API).
+- `keeper(id, { name, text, weapon, passive, model?, tint?, unlock? })`, `achievement(...)`, `mission(...)`, `title(...)`.
+- `earn.rule(id, { when, n, pay, oncePer: "run" })`. Events: `room.cleared`, `enemy.killed`, `boss.killed`, `player.downed`, `player.revived`, `player.levelup`, `run.won`, `run.lost`, and anything a system emits.
+- `earn.stake({ min, max, multiple })`, exactly one, on one top-level line.
+- `store.sku(id, { coins, grants? })`.
+
+## Rules the build enforces
+
+- Ids are lower_snake_case.
+- Every game declares at least one `earn.rule` and exactly one `earn.stake`. `"stake"` is reserved.
+- A dungeon game needs one enemy prefab, one weapon and `players.weapon` (or keepers).
+- Drops must be pickup prefabs.
+- A keeper is earned (an achievement unlock) or bought (a SKU), never both. The first keeper is free.
+- Asset ids are library ids such as `"style.lowpoly.skeleton"`, never URLs or paths, and must exist in the asset library. Keep `game({ style })` as the creator picked it.
+- Keep the SKUs the client is wired to exactly: `revive`, `skin_ossuary` and the `wick_charm` gear.
+
+## Validate
+
+- With the MCP server (`npx -y @netforge/mcp`), call `netforge_validate_game` on `src/game.ts`. It returns one actionable line per problem.
+- In this package, run the tests with vitest: `test/harness.test.ts`, `test/host.test.ts` and `test/store.test.ts`.
+
+## Playtest
+
+- With the MCP server, call `netforge_run_playtest`.
+- In code, import the game module and run the headless harness:
+
+```ts
+import { engine } from "@netforge/engine";
+import "./src/game.js";
+
+const report = await engine.test.run({ ticks: 30 * 180, bots: 4, seed: 1, bot: "human" });
+console.log(report.kills, report.wave, report.maxLevel, report.earned, report.fun);
+```
+
+The report has kills, wave (1 + rooms cleared), maxLevel, earn by rule, deaths, runs won and lost, softlock and ms per tick. With `bot: "human"`, `report.fun` has the fun metrics the gate scores.
+
+## Play locally
+
+In a folder with `netnet.json` (`{"template":"dungeon"}`) and `src/game.ts`, with `@netforge/kit-play` and `@netforge/engine` installed, run `npx kit-play`. It opens http://127.0.0.1:4663 with play money. The MCP tool `netforge_play_locally` gives the same steps.
+
+## Do not
+
+- Do not write renderers, netcode, physics or pathing. The template has them.
+- Do not reference assets by URL or file path.
+- Do not import anything other than `@netforge/engine` in `src/game.ts`.
+- Do not edit `client/`, `src/manifest.ts` or `src/store.ts`.
+- Do not rename or reprice the SKUs the client is wired to.

package/CLAUDE.md

@@ -0,0 +1,11 @@
+# CLAUDE.md
+
+This package is CRYPTWICK, a Net Forge game template. Read AGENTS.md before changing this game. It lists the declarations this genre has, the rules the build enforces, and how to validate, playtest and play the game locally.
+
+The five hard rules:
+
+1. Edit only src/game.ts (and src/names.json for the labels players read).
+2. Import only from @netforge/engine.
+3. Ids are lower_snake_case.
+4. Declare at least one earn.rule and exactly one earn.stake.
+5. Never write renderers, netcode, physics or bot AI, and never reference assets by URL or file path (use library ids such as "style.lowpoly.frog").

package/LICENSE

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

package/NOTICE

@@ -0,0 +1,35 @@
+@netforge/template-dungeon (CRYPTWICK)
+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 (wickbearers,
+  the dead) and Kenney (columns, crates and rocks), 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 dungeon-crawl and survivor-like genres' general mechanics (rooms
+  joined by corridors, rooms that wake as you near them, loot in cleared
+  rooms, permadeath runs, auto-firing weapons, pick-one-of-three
+  level-ups, a boss in the deepest room). Mechanics, not expression; no
+  level, item, enemy or text was copied from any game. The floor plan is
+  generated by our own code (engine dungeon.ts) from a seed.
+- Flow-field pathing (a breadth-first distance field steered down its
+  gradient), a textbook technique, implemented in engine-sim walls.ts.
+- 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,85 @@
-# Temporary Holding Version
+# @netforge/template-dungeon
 
-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 co-op dungeon crawler game template for Net Forge: up to 4 players descend a procedural crypt, room by room, in permadeath runs (CRYPTWICK).
+
+Four wickbearers go down into a candle-lit crypt. The crypt is grown from a seed with `dungeon(...)`: ten rooms joined by corridors, the start room at the top and the Wax Abbot in the deepest one. Rooms wake as the party nears them and their dead come through the doors. A cleared room leaves a reliquary (pick an upgrade) and brings back anyone who fell. If the whole party is down at once, the descent is over.
+
+## Install
+
+```sh
+npm install @netforge/template-dungeon
+```
+
+You rarely import this package directly. kit play (`@netforge/kit-play`) and the Net Forge MCP server use it to build and run a game whose `src/game.ts` you write.
+
+## Play it locally
+
+```sh
+mkdir -p my-game/src && cd my-game
+npm init -y && npm install @netforge/kit-play @netforge/engine @netforge/template-dungeon
+cp node_modules/@netforge/template-dungeon/src/game.ts src/
+echo '{"template":"dungeon"}' > netnet.json
+npx kit-play        # opens http://127.0.0.1:4663
+```
+
+Open the Invite link (`?room=<id>`) in another tab to play together, or start with `--host 0.0.0.0` and open it on a phone on the same network. Coins are play money. Real-token earning, stakes and claims run only on the hosted Net Forge server.
+
+## Change the game
+
+Edit `src/game.ts` and run `npx kit-play` again. For example, grow a different and larger crypt by changing the seed and the room count:
+
+```ts
+const CRYPT = dungeon({ seed: 7, rooms: 14, cell: 24, size: [12, 18], corridor: 6, loops: 3 });
+```
+
+Or make the candle burst, the starting weapon, hit harder:
+
+```ts
+weapon("candle_burst", {
+  kind: "nova", damage: 16, cooldown: 1.1, range: 3.8, knockback: 2.5,
+  // levels and evolve as shipped
+});
+```
+
+## How it plays on the server
+
+- Server-authoritative at 30 Hz on the survivor machinery: auto-firing weapons, shards and level-up cards, co-op downs and revives, keepers, and bosses with telegraphed attacks. Your own wickbearer is predicted.
+- The crypt's walls are boxes in the sim (`field.walls`) and its floors (`field.floors`) are the only ground. Enemies behind a wall walk round through the doors on a flow field, with a wider grid for big bodies.
+- The crawl is a system in `src/game.ts` that you can read and change: room wakes, encounters by depth, off-screen spawns inside the woken room, the quiet timer that wakes the nearest room when the party waits, reliquaries and the respawn on clear.
+- Earn: rooms cleared (2 and 7), the Abbot, and 60 kills by one wickbearer, once per run each. The room server is the referee.
+
+## Files
+
+| Path | What |
+|---|---|
+| `src/game.ts` | The game, as declarations only: the crypt's spec, the dead, weapons, the crawl system, earn and the store. This is the file you edit. |
+| `src/manifest.ts` | Loads and compiles the game; `dungeonAdapter()` for the room host and the client. |
+| `src/store.ts` | Store hooks on the Kit's API names (`kit.coins.*`, `kit.store.*`): a revive, a cosmetic and the wick charm (losable gear). |
+| `client/` | The browser client: three.js scene, the crypt's floors and walls with an x-ray cut and fog of war, HUD, input (keys, gamepad, touch), game feel. |
+| `test/` | Playtest bots through `engine.test.run`, the host test and the store test. |
+| `llms.txt`, `llms-full.txt` | How to change the game, for agents. |
+
+## Controls
+
+WASD or arrows to move, Space to dash, 1 2 3 to pick a card. On touch, drag on the left half, use the DASH button and tap a card. The backtick key shows stats.
+
+## For AI agents
+
+Read `AGENTS.md` and `llms.txt` before editing. The Net Forge MCP server gives a coding agent the templates, the API and a playtest loop:
+
+```sh
+npx -y @netforge/mcp
+```
+
+The package is `@netforge/mcp` and its bin is `netforge-mcp`. Its tools are `netforge_list_templates`, `netforge_create_game`, `netforge_explain_api`, `netforge_search_docs`, `netforge_validate_game`, `netforge_run_playtest` and `netforge_play_locally`. The engine's `GAME-DESIGN.md` (in `@netforge/engine`) has the design rules the playtest gate scores.
+
+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/dungeon
+- `llms.txt` and `llms-full.txt` in this package. The full file includes the complete `src/game.ts` and the validate and playtest steps.
+
+## License
+
+MIT. See LICENSE and NOTICE.

package/client/crypt.ts

@@ -0,0 +1,274 @@
+/**
+ * The crypt as drawn: dark rock under everything, a flagstone floor on
+ * every room and corridor (game.ts field.floors), stone walls on every
+ * wall box (field.walls), and candles in sconces at the room corners. One merged mesh for all the walls and one for all
+ * the floors, so the whole level is a handful of draws.
+ *
+ * Rooms nobody has walked into yet stay dim (a soft fog of war that lifts
+ * as a wickbearer enters); the walls stay readable so the plan is always
+ * there to see.
+ *
+ * An art style that paints surfaces (ps1's textures) paints these too
+ * (surface roles "floor", "wall", "stone"); the toon, pixel, voxel and
+ * hand-drawn styles reshade them in post like everything else.
+ */
+import { BufferAttribute, BufferGeometry, CanvasTexture, Color, CylinderGeometry, Group, Mesh, MeshBasicMaterial, MeshStandardMaterial, MeshStandardNodeMaterial, PlaneGeometry, RepeatWrapping, SphereGeometry, SRGBColorSpace, Vector3 } from "three/webgpu";
+import { clamp, dot, float, length, positionWorld, select, uniform } from "three/tsl";
+import type { Texture } from "three/webgpu";
+import type { WallBox } from "@netforge/engine-sim";
+
+/** Walls are drawn this tall (the sim's are 3 m): low enough that a wall south of you hides less of the room. */
+export const WALL_DRAW_HEIGHT = 2.2;
+/** Candles burn in sconces this high in the room corners, under the wall tops. */
+const SCONCE_HEIGHT = 1.75;
+/** Brightness of a floor nobody has walked into yet, and of one a wickbearer has. */
+const UNSEEN = 0.2;
+const LIT = 0.8;
+
+function hash01(n: number): number {
+  let t = (n + 0x6d2b79f5) >>> 0;
+  t = Math.imul(t ^ (t >>> 15), t | 1);
+  t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+  return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+}
+
+/** Worn flagstones, drawn on a canvas (one repeat covers 4 m). */
+function flagstones(): CanvasTexture {
+  const c = document.createElement("canvas");
+  c.width = c.height = 256;
+  const g = c.getContext("2d");
+  if (g) {
+    g.fillStyle = "#3b342d";
+    g.fillRect(0, 0, 256, 256);
+    for (let j = 0; j < 4; j++) {
+      for (let i = 0; i < 4; i++) {
+        const k = j * 4 + i;
+        const off = j % 2 === 0 ? 0 : 32;
+        const v = 70 + Math.floor(hash01(k) * 26);
+        g.fillStyle = `rgb(${v + 8}, ${v}, ${v - 10})`;
+        g.fillRect(((i * 64 + off) % 256) + 2, j * 64 + 2, 60, 60);
+        // Cracks and wear.
+        g.strokeStyle = "rgba(20, 16, 12, 0.35)";
+        g.beginPath();
+        g.moveTo(((i * 64 + off) % 256) + 8 + hash01(k + 50) * 40, j * 64 + 6);
+        g.lineTo(((i * 64 + off) % 256) + 10 + hash01(k + 90) * 44, j * 64 + 58);
+        g.stroke();
+      }
+    }
+    g.fillStyle = "rgba(255, 220, 160, 0.04)";
+    for (let n = 0; n < 300; n++) g.fillRect(hash01(n * 3) * 256, hash01(n * 3 + 1) * 256, 2, 2);
+  }
+  const t = new CanvasTexture(c);
+  t.wrapS = t.wrapT = RepeatWrapping;
+  t.colorSpace = SRGBColorSpace;
+  t.userData = { tile: 4 };
+  return t;
+}
+
+/** Coursed stone blocks for the walls (one repeat covers 2 m). */
+function masonry(): CanvasTexture {
+  const c = document.createElement("canvas");
+  c.width = c.height = 128;
+  const g = c.getContext("2d");
+  if (g) {
+    g.fillStyle = "#1d1a18";
+    g.fillRect(0, 0, 128, 128);
+    for (let j = 0; j < 4; j++) {
+      for (let i = -1; i < 3; i++) {
+        const v = 52 + Math.floor(hash01(j * 7 + i + 20) * 22);
+        g.fillStyle = `rgb(${v}, ${v - 4}, ${v - 9})`;
+        g.fillRect(i * 64 + (j % 2) * 32 + 2, j * 32 + 2, 60, 28);
+      }
+    }
+  }
+  const t = new CanvasTexture(c);
+  t.wrapS = t.wrapT = RepeatWrapping;
+  t.colorSpace = SRGBColorSpace;
+  t.userData = { tile: 2 };
+  return t;
+}
+
+/**
+ * Boxes as one geometry with world-space UVs (so a texture tiles at the
+ * same scale on a 1 m stub and a 40 m run). `h` is the height; the floor
+ * is y = 0.
+ */
+function boxesGeometry(boxes: readonly WallBox[], h: number, tile: number): BufferGeometry {
+  const pos: number[] = [];
+  const nor: number[] = [];
+  const uv: number[] = [];
+  const idx: number[] = [];
+  const quad = (a: number[], b: number[], c: number[], d: number[], n: number[], uvOf: (p: number[]) => [number, number]) => {
+    const base = pos.length / 3;
+    for (const p of [a, b, c, d]) {
+      pos.push(p[0] ?? 0, p[1] ?? 0, p[2] ?? 0);
+      nor.push(n[0] ?? 0, n[1] ?? 0, n[2] ?? 0);
+      const [u, v] = uvOf(p);
+      uv.push(u / tile, v / tile);
+    }
+    idx.push(base, base + 1, base + 2, base, base + 2, base + 3);
+  };
+  for (const b of boxes) {
+    const x0 = b.x - b.hx;
+    const x1 = b.x + b.hx;
+    const z0 = b.z - b.hz;
+    const z1 = b.z + b.hz;
+    const xz = (p: number[]): [number, number] => [p[0] ?? 0, p[2] ?? 0];
+    const xy = (p: number[]): [number, number] => [p[0] ?? 0, p[1] ?? 0];
+    const zy = (p: number[]): [number, number] => [p[2] ?? 0, p[1] ?? 0];
+    quad([x0, h, z1], [x1, h, z1], [x1, h, z0], [x0, h, z0], [0, 1, 0], xz);
+    quad([x0, 0, z1], [x1, 0, z1], [x1, h, z1], [x0, h, z1], [0, 0, 1], xy);
+    quad([x1, 0, z0], [x0, 0, z0], [x0, h, z0], [x1, h, z0], [0, 0, -1], xy);
+    quad([x1, 0, z1], [x1, 0, z0], [x1, h, z0], [x1, h, z1], [1, 0, 0], zy);
+    quad([x0, 0, z0], [x0, 0, z1], [x0, h, z1], [x0, h, z0], [-1, 0, 0], zy);
+  }
+  const g = new BufferGeometry();
+  g.setAttribute("position", new BufferAttribute(new Float32Array(pos), 3));
+  g.setAttribute("normal", new BufferAttribute(new Float32Array(nor), 3));
+  g.setAttribute("uv", new BufferAttribute(new Float32Array(uv), 2));
+  g.setIndex(idx);
+  g.computeBoundingSphere();
+  return g;
+}
+
+/**
+ * The x-ray cut: wall fragments near the line from the camera to your
+ * wickbearer (and in front of them) are not drawn, so a wall south of you
+ * never hides you. Works on the node material every backend draws, and the
+ * art styles carry it over (they copy opacity nodes and the alpha test).
+ */
+export class WallCut {
+  readonly camera = uniform(new Vector3(0, 20, 20));
+  readonly hero = uniform(new Vector3(0, 1, 0));
+  /** Radius of the cut, m. */
+  readonly radius = uniform(1.6);
+
+  /** A wall material with the cut in it. */
+  material(color: number, map: Texture | null, roughness: number): MeshStandardNodeMaterial {
+    const m = new MeshStandardNodeMaterial({ color, roughness, flatShading: true });
+    if (map) m.map = map;
+    const c = this.camera;
+    const seg = this.hero.sub(c);
+    const p = positionWorld;
+    const t = clamp(dot(p.sub(c), seg).div(dot(seg, seg)), 0, 1);
+    const d = length(p.sub(c.add(seg.mul(t))));
+    // Cut: close to the sight line, before the hero, and above the wall's foot (the base still outlines the room).
+    const cut = d.lessThan(this.radius).and(t.lessThan(0.97)).and(p.y.greaterThan(0.12));
+    m.opacityNode = select(cut, float(0), float(1));
+    m.alphaTest = 0.5;
+    return m;
+  }
+
+  update(camera: Vector3, hero: Vector3): void {
+    this.camera.value.copy(camera);
+    this.hero.value.set(hero.x, hero.y + 0.9, hero.z);
+  }
+}
+
+interface FloorPiece {
+  readonly box: WallBox;
+  readonly material: MeshStandardMaterial;
+  lit: number;
+  seen: boolean;
+}
+
+export class CryptLevel {
+  readonly group = new Group();
+  /** Where candles burn ([x, y, z]): the scene drifts embers off the near ones. */
+  readonly flames: [number, number, number][] = [];
+  private readonly floors: FloorPiece[] = [];
+  readonly cut = new WallCut();
+
+  constructor(
+    walls: readonly WallBox[],
+    floors: readonly WallBox[],
+    half: number,
+    surface: ((kind: "floor" | "wall" | "stone" | "ground") => Texture | null) | null,
+  ) {
+    // Rock under everything: what the camera sees past the walls.
+    const rock = new Mesh(new PlaneGeometry(half * 2 + 60, half * 2 + 60), new MeshStandardMaterial({ color: 0x0b0a0c, roughness: 1 }));
+    rock.rotation.x = -Math.PI / 2;
+    rock.position.y = -0.02;
+    rock.userData.surface = "rock";
+    this.group.add(rock);
+
+    // Floors: one mesh per room or corridor, so each can lift out of the dark on its own.
+    const floorMap = surface?.("floor") ?? flagstones();
+    const ftile = (floorMap.userData as { tile?: number }).tile ?? 4;
+    for (const f of floors) {
+      const map = floorMap.clone();
+      map.needsUpdate = true;
+      map.repeat.set((f.hx * 2) / ftile, (f.hz * 2) / ftile);
+      map.offset.set(((f.x - f.hx) / ftile) % 1, ((f.z - f.hz) / ftile) % 1);
+      const material = new MeshStandardMaterial({ map, roughness: 0.95, color: new Color(UNSEEN, UNSEEN, UNSEEN) });
+      const m = new Mesh(new PlaneGeometry(f.hx * 2, f.hz * 2), material);
+      m.rotation.x = -Math.PI / 2;
+      m.position.set(f.x, 0.005, f.z);
+      m.receiveShadow = true;
+      m.userData.surface = "floor";
+      this.group.add(m);
+      this.floors.push({ box: f, material, lit: UNSEEN, seen: false });
+    }
+
+    // Walls: one merged mesh with a darker cap, so the plan reads from above.
+    const wallMap = surface?.("wall") ?? masonry();
+    wallMap.wrapS = wallMap.wrapT = RepeatWrapping;
+    const wtile = (wallMap.userData as { tile?: number }).tile ?? 2;
+    const wall = new Mesh(boxesGeometry(walls, WALL_DRAW_HEIGHT, wtile), this.cut.material(0x9a8f84, wallMap, 0.92));
+    wall.castShadow = true;
+    wall.receiveShadow = true;
+    wall.userData.surface = "wall";
+    this.group.add(wall);
+    const capMat = this.cut.material(0x2b2420, null, 1);
+    const cap = new Mesh(boxesGeometry(walls.map((b) => ({ x: b.x, z: b.z, hx: b.hx + 0.04, hz: b.hz + 0.04 })), 0.08, 1), capMat);
+    cap.position.y = WALL_DRAW_HEIGHT;
+    this.group.add(cap);
+
+    // Candles: a sconce flame at each room's inner corners (rooms are the floors big enough to be rooms).
+    const flameMat = new MeshBasicMaterial({ color: new Color(0xffb04a).multiplyScalar(5) });
+    const flameGeo = new SphereGeometry(0.16, 8, 6);
+    const sconceGeo = new CylinderGeometry(0.22, 0.12, 0.24, 6);
+    const sconceMat = new MeshStandardMaterial({ color: 0x2a2420, roughness: 0.6, metalness: 0.4 });
+    for (const f of floors) {
+      if (f.hx < 4 || f.hz < 4) continue;
+      for (const [sx, sz] of [
+        [-1, -1],
+        [1, -1],
+        [-1, 1],
+        [1, 1],
+      ] as const) {
+        // A candle in an iron sconce, set into the corner.
+        const x = f.x + sx * (f.hx - 0.3);
+        const z = f.z + sz * (f.hz - 0.3);
+        const sconce = new Mesh(sconceGeo, sconceMat);
+        sconce.position.set(x, SCONCE_HEIGHT - 0.12, z);
+        this.group.add(sconce);
+        const flame = new Mesh(flameGeo, flameMat);
+        flame.position.set(x, SCONCE_HEIGHT + 0.1, z);
+        this.group.add(flame);
+        this.flames.push([x, SCONCE_HEIGHT + 0.15, z]);
+      }
+    }
+  }
+
+  /** Lift the dark off every floor a wickbearer stands on (or within 2 m of). */
+  update(dt: number, players: readonly (readonly [number, number])[]): void {
+    for (const f of this.floors) {
+      if (!f.seen) {
+        for (const [x, z] of players) {
+          if (Math.abs(x - f.box.x) <= f.box.hx + 2 && Math.abs(z - f.box.z) <= f.box.hz + 2) f.seen = true;
+        }
+      }
+      const goal = f.seen ? LIT : UNSEEN;
+      if (Math.abs(goal - f.lit) < 0.002) continue;
+      f.lit += (goal - f.lit) * Math.min(1, dt * 2.5);
+      // Candle-warm: a touch less blue than red.
+      f.material.color.setRGB(f.lit, f.lit * 0.93, f.lit * 0.84);
+    }
+  }
+
+  /** A fresh descent: every room goes back into the dark. */
+  reset(): void {
+    for (const f of this.floors) f.seen = false;
+  }
+}