@bitmagic/cli 0.1.64-dev.2 → 0.1.64-dev.3

package/dist/scaffold/blender-level-skill-files.js

@@ -0,0 +1,548 @@
+/**
+ * The `building-levels-in-blender` skill: a hand-designed low-poly world written as a Python script
+ * against the shipped `bmlevel` library, built by Blender into one GLB plus the collider / door /
+ * light / landmark JSON, audited with ray casts, reviewed from rendered stills, and loaded by the
+ * engine's `MeshLevel`. Distilled from a creator's space-station game whose agent installed Blender
+ * and hand-rolled every part of this — the build vocabulary, the audits, the review renders, the
+ * level loader — and hit the two failures the skill now names up front (a GLB fetched from a local
+ * path that 404s after publish; NPC spawns routed into an absent voxel grid).
+ *
+ * Same contract as `unity-skill-files.ts`: pure functions returning file contents, registered in
+ * `SHIPPED_SKILLS` (project.ts). The Python and Blender scripts ship in the package's
+ * `assets/blender-level/` (see `files` in package.json) rather than being rendered into every
+ * project; the skill's step 1 copies them into `tools/blender-level/`.
+ *
+ * The skill's first section is the gate: the path is for frontier models with Blender available,
+ * and everything else goes to `bitmagic forge`. The CLI cannot tell which model drives it, so the
+ * gate is the agent's own call — stated once, plainly, where the planning skill sends it.
+ *
+ * Backticks and `${` are escaped for the template literal; `project-files.test.ts` checks the
+ * rendered frontmatter and that no escape leaks into the output.
+ */
+export function renderBlenderLevelsSkill() {
+    return `---
+name: building-levels-in-blender
+description: Build a hand-designed low-poly 3D world — an interior, a space station, a house and its garden, a stylised set — in Blender from a short Python script instead of voxel terrain, and load it through the engine's MeshLevel: one GLB plus the collider, door, light and landmark JSON, audited with ray casts and reviewed from rendered stills before the game ever runs it. Use it when a creator asks for "low poly", "stylised 3D", a "hand-built level", an enclosed interior, "not voxels", or "in Blender" — and when such a level has walls you fall through, doors that do not open, z-fighting seams, or shows an empty world after publish.
+---
+
+# Building a level in Blender
+
+A mesh level is one GLB that IS the whole world, plus a JSON that says what the art cannot: which
+surfaces are solid, where the rooms, doors, lights and named points are. You write the level as a
+Python script against \`bmlevel\` (game coordinates: metres, Y up, +Z forward), Blender builds it,
+\`audit.py\` fires thousands of rays at the colliders, \`review.py\` renders every door and room, and
+the engine's \`MeshLevel\` loads the result in six lines (\`engine/agent-docs/mesh-level.md\`). The
+level that taught this skill was a five-module space station; every rule below was paid for there.
+
+## 0. Is this path yours?
+
+Take it only when BOTH hold:
+
+- **You are a frontier model** — Claude Fable / Opus 5, GPT-6 class. Building a level part by part
+  in code, reading a contact sheet and diagnosing a failed ray audit is sustained spatial reasoning
+  over hundreds of lines; a smaller model produces a plausible script and a level with holes in it.
+  If you are not sure you are one, you are not.
+- **Blender is installed or installable here.** Run the probe below. If it cannot be installed
+  (no admin rights, a sandbox), stop.
+
+Otherwise use \`bitmagic forge\` (AGENTS.md, "Forging a whole level") — it builds a real level from a
+prompt with no tooling beyond Chrome. The forge is also the right answer for natural terrain of
+any kind; this path is for places that are designed, not grown.
+
+\`\`\`
+python3 tools/blender-level/find_blender.py --check   # prints "Blender 4.x at <path>", or how to install it
+export BLENDER="$(python3 tools/blender-level/find_blender.py)"
+\`\`\`
+
+Install if needed: macOS \`brew install --cask blender\`, Debian/Ubuntu \`sudo apt install blender\`,
+Windows \`winget install BlenderFoundation.Blender\`. Blender 4.2 or newer.
+
+## 1. Install the library into the project
+
+The scripts ship inside the Bitmagic CLI package. Copy them once:
+
+\`\`\`
+CLI_ROOT="$(cd "$(dirname "$(readlink -f "$(which bitmagic)")")/.." && pwd)"
+mkdir -p tools && cp -R "$CLI_ROOT"/assets/blender-level tools/ && mkdir -p tools/level build
+grep -qx 'build/' .gitignore || echo 'build/' >> .gitignore
+\`\`\`
+
+\`tools/blender-level/README.md\` lists what each file does. Level scripts go in \`tools/level/\`,
+outputs in \`build/level/\`.
+
+## 2. Plan the place in words, then as a table
+
+Write the \`## Art direction\` of \`GAME-DESIGN.md\` first — \`bitmagic judge\` scores against it, and a
+reference image (\`bitmagic reference\`) keeps every pass aimed at the same look. Then list, before
+any code: every **room** with its size in metres, every **door** with which two rooms it joins,
+every **route** a player must be able to walk, the **spawn**, and the named points the game needs
+(extraction pad, guard posts, an altar). That table becomes \`volume()\`, \`door()\`, \`link()\`,
+\`spawn()\` and \`landmark()\` calls — and the audit checks exactly those, so a room you did not
+declare is a room nothing checks.
+
+## 3. Write \`tools/level/<name>.py\`
+
+Start from \`tools/blender-level/example_level.py\` — a two-room hut, porch, stairs and courtyard
+using every helper. The vocabulary:
+
+\`\`\`python
+import os, sys
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', 'blender-level'))
+from bmlevel import *
+
+mat('plaster', (0.82, 0.78, 0.7))          # rgb 0..1; glass* renders transparent, emissive* glows
+with context('hall', origin=(0, 0, 0), yaw=0):   # a named part with its own local frame; nests
+    slab('floor', (0, 0), (12, 8), 'plaster')                       # top surface at y=0
+    wall('north', (-6, -4), (6, -4), 3.5, 'plaster', opening={'at': 6, 'width': 1.6, 'height': 2.4})
+    door('north door', (0, 0, -4), yaw=0, width=1.6, height=2.4, jamb='timber')
+    stairs('up', (4, 0, 0), rise=3, run=5, material='stone', rail='brass')
+    decor('cornice', (0, 3.3, -3.85), (12, 0.2, 0.3), 'plaster')    # never collides
+    prism('bay', [(-2, 4), (2, 4), (0, 6)], 0, 3.5, 'plaster')       # convex outline, extruded
+    text('sign', 'HALL', (0, 2.9, -4.2), 'brass', size=0.4, both_faces=True)
+    lamp('centre', (0, 3.2, 0), '#ffd9a0', intensity=10, distance=14)
+    volume('hall', (0, 1.75, 0), (12, 3.5, 8), tags=['indoors'])
+    landmark('altar', (0, 0.1, 5), tags=['objective'])
+    spawn((0, 0.1, 2), yaw=3.14159)
+link('hall', 'yard', door='north door')
+export('build/level', 'temple')
+\`\`\`
+
+Rules that are not style:
+
+- **Everything solid by default.** \`box()\`, \`wall()\`, \`slab()\`, \`prism()\` and \`stairs()\` become
+  colliders; \`decor()\` and \`text()\` never do. Cladding, trim, lamps, fasteners and rugs are
+  \`decor()\` — a collider on a 5 mm strip is a step the player trips on and the audit flags.
+- **Name everything, uniquely.** Names are the \`.blend\` outliner and the audit's error messages.
+- **Overlap, never abut.** Two slabs meeting edge to edge leave a seam a ray, and a capsule, slips
+  through; overlap them by 5 cm. Two faces on the same plane z-fight; offset by 5 cm or make the
+  outer one deeper (the door header the library builds is 4 cm deeper than its jambs for this).
+- **Convex prisms only** — a concave outline raises; split it. Mitred junctions are two prisms.
+- **Doors are records, not meshes.** \`door()\` writes a \`DoorDefinition\`; the engine builds and
+  animates the leaf. \`jamb=\` adds solid jambs and a header so the wall reads as a doorway.
+
+## 4. Build
+
+\`\`\`
+"$BLENDER" -b --python tools/level/<name>.py
+\`\`\`
+
+It prints \`LEVEL … colliders … doors … volumes …\`, \`BOUNDS\`, and a \`REGISTER bitmagic assets add …\`
+line to keep for step 7. Outputs: \`build/level/<name>.glb\` (one draw call per material),
+\`<name>.blend\` (named, editable parts), \`<name>.mesh-level.json\`, \`<name>.doors.json\`. A syntax
+or geometry error prints a Python traceback naming the helper and the object — fix and rebuild;
+builds take seconds. \`python3 tools/level/<name>.py --dry-run\` gives the counts without Blender.
+
+## 5. Render and look
+
+\`\`\`
+"$BLENDER" -b --python tools/blender-level/review.py -- build/level/<name>.blend build/level/<name>.mesh-level.json build/level/review/
+\`\`\`
+
+Read \`build/level/review/contact-sheet.png\` (the log says which frame is which), then any single
+frame that looks wrong. You are looking for: a door with no wall around it, a room whose ceiling
+is missing, stairs that end in the air, a sign that reads backwards, two surfaces flickering into
+one another. Fix the script, rebuild, re-render. Do not go on to the audit while the sheet is
+wrong; the audit finds holes, not ugliness.
+
+## 6. Audit
+
+\`\`\`
+"$BLENDER" -b --python tools/blender-level/audit.py -- build/level/<name>.mesh-level.json                   # doors open: floors, doorways, routes
+"$BLENDER" -b --python tools/blender-level/audit.py -- build/level/<name>.mesh-level.json --doors closed    # envelopes sealed with the leaves in
+\`\`\`
+
+Every check prints its ray count and its failures with coordinates; exit 1 means the level is
+not done. A failed \`floor_continuity\` is a hole a player falls through; a failed \`door_clearance\`
+or \`link_clearance\` is a doorway or route the player cannot walk (a jamb in the opening, a table
+on the line between two rooms, a step that ends short); a failed \`sealed_envelope\` is a gap in a
+roof or wall. \`coplanar_overlap\` is a warning: two faces on one plane, which flicker. Never
+answer a failure by removing the volume or the link that found it.
+
+## 7. Register the GLB, sync world.json, write the game code
+
+\`\`\`
+bitmagic assets add build/level/<name>.glb --name <name> --keep-glb --asset-id level-<name> --height <native height>   # the REGISTER line from step 4
+python3 tools/blender-level/sync_world.py build/level/<name>.doors.json build/level/<name>.mesh-level.json src/work/world.json
+cp build/level/<name>.mesh-level.json src/work/
+\`\`\`
+
+\`--keep-glb\` keeps it a polygon mesh and puts a CDN URL in \`assets[]\`, which is the only thing a
+published bundle can load — a GLB fetched from \`src/work/\` works in \`bitmagic dev\` and shows an
+empty world after \`bitmagic publish\`. \`--height\` is the level's real height: the entry's default
+is 2 m. \`sync_world.py\` upserts the doors into \`worldProfileData.doors[]\` (creator-set keys and
+locks survive), sets the spawn, and sets \`terrain.shape\` to \`none\` so no voxel ground is built
+under the level. Then, in \`src/work/Game.ts\`, after the player controller exists:
+
+\`\`\`ts
+import { MeshLevel, DEFAULT_MESH_LEVEL_OPTIONS } from 'engine/meshlevel/MeshLevel.js';
+import { DEFAULT_FALL_RESCUE_OPTIONS } from 'engine/FallRescue.js';
+import levelJson from './<name>.mesh-level.json';
+
+const level = new MeshLevel(this.engine, { glb: { assetId: 'level-<name>' }, level: { data: levelJson } }, DEFAULT_MESH_LEVEL_OPTIONS);
+const loaded = await level.load();
+const spawn = level.landmark('spawn');
+this.playerController.teleportTo(spawn.position[0], spawn.position[1], spawn.position[2], spawn.yaw);
+this.playerController.configureFallRescue({ ...DEFAULT_FALL_RESCUE_OPTIONS, killPlaneY: loaded.bounds.minY - 50 });
+\`\`\`
+
+\`engine/agent-docs/mesh-level.md\` has the rest: \`landmarksTagged('guard')\` for NPC posts
+(\`npc.spawn(x, z, y)\` — pass the storey's Y for interiors), \`volumesAt(position)\` for room logic,
+the lighting modes, and \`samples/mesh-level-setup.ts\`.
+
+## 8. Check, verify, walk it
+
+\`bitmagic check\`, then \`bitmagic verify\`: the console must show one \`[MeshLevel] loaded …\` line
+with the collider and light counts you expect, and no \`404\` for the GLB. Then walk it in the
+\`bitmagic dev\` browser — through every door, up every stair, into every room — because an audit
+proves geometry, not that the place is good to be in. \`bitmagic verify --platform mobile\` too if
+phones matter.
+
+## 9. Judge, then iterate in passes
+
+\`bitmagic judge\` scores the verify screenshot against your art direction. Improve the level in
+passes, each one a full loop (edit script → build → review → audit → sync → verify):
+
+1. **Structure** — rooms, doors, routes, stairs, the spawn. Audit clean, walkable.
+2. **Detail** — cladding, casings, coffers, deck plates, signage, props. All \`decor()\` unless the
+   player should bump into it; keep every travel clearance.
+3. **Surfaces and light** — materials, emissive strips, warm and cool lamps, a spot or two with
+   shadows. Look at it in the real game, not only in the render.
+
+\`references/level-design-passes.md\` says what each pass contains and when to stop.
+
+## Where the deep material is
+
+| Read when… | File |
+|---|---|
+| a piece is mirrored, rotated, at the wrong height, or the \`.blend\` no longer matches the GLB | \`references/blender-conventions.md\` |
+| an audit check fails and the fix is not obvious, or a render looks wrong | \`references/audits-and-review.md\` |
+| the level is walkable but plain, and you want it to look like the reference | \`references/level-design-passes.md\` |
+| registering, syncing doors, spawning NPCs, lighting, publishing, or a level that is empty in the published game | \`references/engine-handoff.md\` |
+`;
+}
+export function renderBlenderConventionsReference() {
+    return `# Blender conventions the library relies on
+
+Every rule here is one the space-station level broke first and paid for in a rebuild.
+
+## Coordinates: you write game space, the library flips once
+
+| You write | Meaning |
+|---|---|
+| positions \`(x, y, z)\` | metres, **Y up, +Z forward**, in the current \`context()\` frame |
+| \`yaw\` | radians about +Y; an entity's forward at yaw θ is \`(sin θ, 0, cos θ)\` (\`engine/agent-docs/coordinate-system.md\`) |
+| \`size\` | full extents \`(width, height, depth)\` — the engine halves them |
+
+Blender is Z up. \`bmlevel\` places a game point at Blender \`(x, -z, y)\`. That map is a 90° rotation
+about X (determinant +1), not a mirror, so a yaw about game +Y is the **same angle** about Blender
++Z, and \`export_yup=True\` on the glTF exporter undoes the placement exactly: what the script said
+is what the engine reads. The collider JSON is written in game coordinates untouched, which is why
+art and physics line up without a single correction on the TypeScript side.
+
+Do not "fix" a piece that looks mirrored by negating an axis in the script. Something else is
+wrong — usually yaw applied to the wrong frame, or a \`context(yaw=…)\` you forgot you were inside.
+
+## The .blend is named parts; the GLB is one mesh per material
+
+\`export()\` saves the \`.blend\` **before** it joins anything, so every \`box()\` you named is a separate
+object in a collection named after its \`context()\`. Then it duplicates every mesh, joins the
+copies per material and exports only those — one draw call per material, the GLB the engine wants.
+Consequences:
+
+- Edit the script, not the \`.blend\`. A hand edit in Blender is lost on the next build. The \`.blend\`
+  is for LOOKING: open it when a render shows something you cannot place from the script.
+- Keep the material count small (six to twelve). Each is a draw call; a material per object is a
+  level that renders at 20 fps on a phone.
+- A material name is a contract with the engine: \`glass*\` renders as a thin transparent pane and
+  casts no shadow, \`emissive*\` is guaranteed to glow (\`glow=\` sets the exported emission strength;
+  the engine's bloom picks it up). Name a window material \`glass_pane\`, a light strip \`emissive_strip\`.
+- \`alpha < 1\` exports blended transparency; the engine only treats it as glass when the name says so.
+
+## Text without fonts
+
+\`text()\` uses Blender's bundled font, extrudes it and converts it to a mesh, so signage needs no
+font file and survives the per-material join. Text reads from local −Z at yaw 0, i.e. it faces a
+player approaching along +Z. \`both_faces=True\` adds a mirrored copy for the other approach — do
+that for any sign on a header seen from both sides; a sign that reads backwards from one side is
+the single most common review-sheet finding.
+
+## Solids, decoration, and the two failures in between
+
+- \`box\`, \`wall\`, \`slab\`, \`prism\`, \`stairs\` are solid: a collider record each. \`decor\`, \`text\` are
+  not. \`glazing()\` is both — a non-solid pane you can see through and a solid collider you cannot
+  walk through.
+- A decoration that should have been solid: the player walks through a pillar. A solid that should
+  have been decoration: a 5 mm deck plate becomes a step, \`link_clearance\` fails, and walking
+  stutters. The default is solid because the second failure is loud and the first is not.
+- \`prism()\` colliders are convex hulls. A concave outline raises rather than silently becoming its
+  hull (which would fill the concavity with invisible wall). Split it: an L is two rectangles, a
+  mitred corridor end is a triangle plus a rectangle.
+- \`stairs()\` makes visual treads and ONE ramp hull, so walking up is smooth; \`treads_solid=True\`
+  when the player must be able to stand on an individual step (a dropped item, an NPC post).
+
+## Overlap, offset, depth: the three z-fighting rules
+
+1. **Overlap, never abut.** Two slabs meeting edge to edge leave a hairline a ray falls through
+   and a capsule catches on. Overlap by 5 cm. The audit's \`floor_continuity\` finds the seam.
+2. **Offset coplanar faces by 5 cm.** A cladding panel flush with the wall it decorates flickers.
+   Push it out 5 cm (or in 5 cm, as an inset). \`coplanar_overlap\` warns about the ones on solids.
+3. **Give layered parts distinct depths.** Casing 0.30 m, header 0.34 m, trim 0.26 m: no two
+   layers share a face plane. The door helper does this for its own jambs and header.
+
+Bevels (\`bevel=\`) catch light on edges and read as "made", not "boxed"; 1–5 cm on furniture and
+casings, none on walls.
+
+## Mitred junctions
+
+Where a corridor meets a room at an angle, a square corridor end leaves a wedge of open air beside
+the doorway and a rectangular wall cutout leaves a slot above it. Build both ends on the same
+mitre plane: the corridor floor, walls and roof as \`prism()\`s whose end edge lies on the angled
+plane, and the room wall as two \`prism()\`s flanking the same plane. The station's ten junctions were
+rebuilt this way after a player reported "gaps and pillars" that the centre-line audit had not
+caught — which is why \`door_clearance\` now samples the full width of every opening.
+
+## What the exporter does, and why each flag
+
+| Flag | Why |
+|---|---|
+| \`export_format='GLB'\` | one binary file for \`bitmagic assets add\` |
+| \`use_selection=True\` | only the per-material joins, not the named parts |
+| \`export_apply=True\` | bakes object transforms so the engine gets world-space vertices |
+| \`export_yup=True\` | the coordinate round trip above |
+| \`export_lights=False\`, \`export_cameras=False\` | lights come from the JSON, cameras are review-only |
+`;
+}
+export function renderBlenderAuditsReference() {
+    return `# Audits and review renders
+
+The audit fires rays at the **colliders in the JSON** — the physics the engine will build — never at
+the art, because decoration is exactly what must not be solid. The renders show the **art in the
+.blend**, so a level can pass the audit and look wrong, or look right and fail. Do both, in that
+order: look first (cheap, catches design errors), audit second (catches the errors you cannot see).
+
+## The checks
+
+| Check | Mode | What it fires | Failure means | Usual fix |
+|---|---|---|---|---|
+| \`floor_continuity\` | open, closed | a 0.5 m grid over every \`volume()\`, one ray down from 1 m above its floor, must hit within 1.5 m | a hole in the floor, a slab that ends short, a volume declared over open air | overlap the slabs by 5 cm; move the volume to the floor's real extent; if the volume is a stairwell, lower it or split it per storey |
+| \`door_clearance\` | open | rays across every \`door()\` opening at three heights and every 25 cm of its width | something solid in the doorway: a jamb built into the opening, a lintel too low, a wall segment that did not stop at the opening | check the \`opening={'at': …}\` distance from the wall's START; check the door's \`yaw\` matches the wall's direction; check \`height\` against the lintel |
+| \`link_clearance\` | open | a player capsule (radius 0.4 m, 0.5 m and 1.5 m high) marched every 0.5 m from volume A's centre to the door to volume B's centre, plus a floor probe under it | a route the player cannot walk: furniture on the line, a step that ends short of the floor, a doorway narrower than 0.8 m, no floor between the rooms | move the prop off the walk line; overlap the ramp with the landing; widen the door; add the missing floor |
+| \`sealed_envelope\` | closed | from a 1 m grid inside every roofed volume: one ray up and four rays outward, each must hit within the volume plus 1 m | a gap in a roof or wall, a corner where two walls do not meet, a doorway with no door record (nothing to seal it) | extend the wall through the corner; add the door(); mark an open-sided space \`roofed=False\` |
+| \`coplanar_overlap\` | both (warning) | pairs of unrotated box colliders sharing a face plane, same facing, overlapping extents | two visible faces flicker into each other | offset by 5 cm or change one depth |
+
+"Mode" is \`--doors\` open (default) or \`closed\`: the leaves from \`<name>.doors.json\` are added as
+solids in closed mode, which is the only mode in which a room can be sealed. Run both.
+
+Every failure prints its first example with coordinates (game space) and \`--json out.json\` writes
+all of them. Locate a coordinate by asking which \`context()\` it falls in and subtracting that
+context's origin.
+
+## Reading a failure you do not believe
+
+- **A ray at exactly a slab's edge fails.** Rays that graze an edge miss. The fix is the same as
+  for a real seam — overlap the slabs — because the player's capsule grazes edges the same way.
+- **\`link_clearance\` fails at the door waypoint.** The march probes for the floor from 0.5 m above
+  waist height at the door; a threshold higher than the door's floor point, or a step directly
+  under the header, trips it. Put the door's \`pos\` at the floor of its threshold.
+- **\`sealed_envelope\` fails along a whole wall.** The wall does not reach the roof: \`wall(height=…)\`
+  is measured from \`base\`, and a ceiling slab's top is at \`y\` with its underside at \`y - thickness\`,
+  so a 3 m wall under a slab whose top is at 3.2 m and thickness 0.2 m just touches — overlap them.
+- **\`floor_continuity\` fails everywhere in one volume.** The volume's \`pos\` is its CENTRE, not its
+  floor; \`(x, height/2, z)\` for a room whose floor is at y = 0.
+
+Never make a failure go away by deleting the \`volume()\` or \`link()\` that found it. A level with
+no volumes passes every check and holds no claim.
+
+## The review set
+
+\`review.py\` renders, from the JSON: \`overview\` (top-down, the whole extent), \`door-<id>-a\` and \`-b\`
+(4 m back from each side of every door, eye height), \`stairs-<name>\` (from the foot, looking up),
+\`volume-<name>\` (inside every room, from one end looking along it). Then \`contact-sheet.png\`,
+four per row in the order the log prints.
+
+What to look for, frame by frame:
+
+- **overview** — the footprint matches the plan; nothing floats outside the walls; corridors meet
+  rooms with no wedge of sky beside the doorway.
+- **doors** — a wall on both sides and a header above; the sign readable from THIS side; the floor
+  continuous through the opening; the far room visible through it (a black doorway is a room with
+  no light AND no fill — usually a missing volume light).
+- **stairs** — treads reach the landing; the rail follows the slope; nothing pokes through a step.
+- **volumes** — a ceiling; walls meeting at the corners; props sitting on the floor, not in it.
+
+The renderer adds its own fill light so interiors are legible; it shows geometry, not the game's
+lighting. Judge the lighting in \`bitmagic verify\`'s screenshot and in the dev browser.
+
+## When a render is right and the game is wrong
+
+The two are the same geometry only if the GLB you registered is the one you just built. After
+every rebuild: register again (same \`--asset-id\`, the entry is replaced), re-run \`sync_world.py\`,
+copy the JSON into \`src/work/\`, and check \`[MeshLevel] loaded\` in the verify console reports the
+new collider count. A verify that passes on stale files is the trap the station fell into three
+times.
+`;
+}
+export function renderBlenderPassesReference() {
+    return `# Level design in passes
+
+A level that is only walls and floors is walkable and dead. The station that taught this skill
+went from boxes to a place people wanted to screenshot in four passes, each a full loop of edit →
+build → review → audit → sync → verify. The passes, what goes in each, and when to stop.
+
+## Pass 1 — structure
+
+Rooms, corridors, doors, stairs, the spawn, every route. Nothing decorative. Stop when: the audit
+is clean in both modes, every door opens onto a floor, every stair reaches a landing, and you have
+walked every \`link()\` in the dev browser. Sizes that read well: rooms 6–12 m across, 3–4 m high;
+corridors 3–4 m wide (a 2 m corridor is a pipe); doors 1.4–2 m wide and 2.2–2.6 m high; treads
+0.28–0.32 m deep and 0.16–0.18 m high. Bigger than a house, smaller than a hangar.
+
+## Pass 2 — detail
+
+Everything the eye reads as "built". All \`decor()\` unless the player should bump into it.
+
+- **Layered casings around every door**: an outer casing 5 cm proud of the wall, an inner recessed
+  band, a crown over the header. Three depths, three widths.
+- **Cladding bands** on long walls: panels inset 5 cm every 4–6 m with a thin vertical trim between
+  them, a service channel at waist height, a coffer or beam line at the ceiling. A blank wall longer
+  than 6 m is the second most common judge finding.
+- **Deck plates**: tile the floor slab with plates 4 × 4 m, 1.2 cm high, 6 cm apart, an occasional
+  plate in the alternate material; fasteners at the corners; a shallow grate every few plates.
+- **Ceiling coffers** or beams on a 3–4 m rhythm, with a recessed light housing in each.
+- **Guidance**: a floor strip in the room's accent colour running the route between doors; signs
+  on every door header, both faces; a module or room name on the wall you see on entering.
+- **Furniture at the walls, not on the line.** The audit will tell you when a prop blocks a route,
+  but the rule is simpler: props go against walls and in corners; the middle of a room is for
+  walking and fighting.
+- **Rails on every stair and gallery edge** (\`rail=\`), posts every third step.
+
+Stop when: the review sheet shows no blank wall and no floating detail, and the audit is still
+clean (detail is the pass that breaks clearances — a casing 20 cm into a doorway is a failed
+\`door_clearance\`).
+
+## Pass 3 — surfaces and light
+
+- **Materials**: six to twelve. A warm neutral for walls, a dark deck, one trim metal, one accent
+  per room, one glass, one emissive. Roughness 0.4–0.7 on walls, 0.2–0.35 on deck plates so they
+  catch light; metal only on rails and fasteners.
+- **Lights**: one warm \`lamp()\` per room near its centre at ceiling height minus 0.5 m, cool fill in
+  corridors, \`emissive_*\` strips where the eye should travel (door frames, guidance, consoles). One
+  or two \`spot()\`s with shadows over the places that matter (the spawn, the objective). Point lights
+  share a small pool in the engine — a room with eight lamps gets four of them; put the count into
+  emissive materials instead.
+- **The engine's interior preset dims the sun for you**; a level that looks washed out in the game
+  after looking fine in the render has an \`exterior\` mode set, or its own sun in \`lightingConfig\`.
+
+Stop when: \`bitmagic judge\` no longer names lighting or flat surfaces, and the level reads the same
+in the verify screenshot as in the reference image.
+
+## Pass 4 — the reference image
+
+Only now: put the reference image beside the review sheet and the verify screenshot and list the
+five biggest differences. Fix those five, in order. Then stop — a level is done when the next
+change would be for you, not the player.
+
+## What not to do
+
+- Do not rebuild the whole script for one room; add a \`context()\` or edit one.
+- Do not make decoration solid "to be safe". Make it \`decor()\` and keep the clearances.
+- Do not add a light per lamp housing. Add the housing as \`emissive_*\` decor and one real light per room.
+- Do not put the whole level in one \`context()\`. One per room or module: the \`.blend\` outliner and
+  the audit's coordinates both read in room-local metres.
+`;
+}
+export function renderBlenderEngineHandoffReference() {
+    return `# Handing the level to the engine
+
+The engine side is \`MeshLevel\` — \`engine/agent-docs/mesh-level.md\` is the full reference and
+\`engine/agent-docs/samples/mesh-level-setup.ts\` the compile-checked sample. This page is the
+seam: what the build wrote, what each command does with it, and the four ways it goes wrong.
+
+## The files the build wrote
+
+| File | Goes | Carries |
+|---|---|---|
+| \`build/level/<name>.glb\` | \`bitmagic assets add … --keep-glb\` → CDN, an \`assets[]\` entry with id \`level-<name>\` | the art, one mesh per material |
+| \`build/level/<name>.mesh-level.json\` | \`cp\` into \`src/work/\`, static \`import\` in \`Game.ts\` | colliders, volumes, landmarks, lights, \`extras.links\` |
+| \`build/level/<name>.doors.json\` | \`sync_world.py\` → \`worldProfileData.doors[]\` | \`DoorDefinition\` records the engine animates |
+| \`build/level/<name>.blend\` | nowhere; open it to look | the named parts |
+
+## Registering: \`--keep-glb\` and \`--height\`
+
+\`\`\`
+bitmagic assets add build/level/<name>.glb --name <name> --keep-glb --asset-id level-<name> --height <native height>
+\`\`\`
+
+- Without \`--keep-glb\` the file is voxelized into a \`.vxl\` and the level becomes a blocky prop.
+- The entry's \`targetHeight\` defaults to 2 m. \`MeshLevel\` does not scale by it, but anything else
+  that reads the asset (the Creator's asset panel, a placement) would squash a 40 m station into a
+  2 m box. The build's \`REGISTER\` line has the real number.
+- Re-registering with the same \`--asset-id\` replaces the entry; the game code does not change.
+- **A GLB that is not an asset is not in the published game.** \`bitmagic publish\` bundles one HTML
+  file whose assets are absolute CDN URLs; a path under \`src/work/\` or \`build/\` resolves in
+  \`bitmagic dev\` and in \`bitmagic verify\` and returns 404 from the published page, which then shows
+  the sky and a falling player. \`MeshLevel\` warns when handed a local \`{ url }\`; use \`{ assetId }\`.
+
+## Syncing: doors, spawn, terrain
+
+\`\`\`
+python3 tools/blender-level/sync_world.py build/level/<name>.doors.json build/level/<name>.mesh-level.json src/work/world.json
+\`\`\`
+
+- **Doors** are upserted by id. The build owns \`position\`, \`rotationY\`, \`width\`, \`height\`,
+  \`thickness\`, \`animation\`; a \`kind: 'locked'\`, \`keyId\`, \`assetId\`, \`color\` or \`autoOpenRadius\` set
+  in world.json by the creator (or by you, for a key-and-lock design — \`engine/agent-docs/doors-and-locks.md\`)
+  survives a rebuild. Doors the build no longer has are listed, never deleted.
+- **Spawn**: the \`spawn\` landmark becomes \`playerSpawnPosition\` and \`playerSpawnRotation\`. The game
+  code teleports there too (below) so the two cannot disagree.
+- **Terrain**: \`terrain.shape\` becomes \`'none'\` — no voxel ground, no invisible safety plane. That
+  is the mode \`MeshLevel\` needs; it also means a level with no floor under the spawn is a player
+  falling for ever, which \`configureFallRescue\` turns into a respawn.
+
+Run it after EVERY rebuild; a door moved in the script and not synced is a leaf animating in a wall.
+
+## The game code
+
+\`\`\`ts
+import { MeshLevel, DEFAULT_MESH_LEVEL_OPTIONS } from 'engine/meshlevel/MeshLevel.js';
+import { DEFAULT_FALL_RESCUE_OPTIONS } from 'engine/FallRescue.js';
+import levelJson from './<name>.mesh-level.json';
+
+// After setupPlayerController(), before any NPC spawns.
+this.level = new MeshLevel(this.engine, { glb: { assetId: 'level-<name>' }, level: { data: levelJson } }, DEFAULT_MESH_LEVEL_OPTIONS);
+const loaded = await this.level.load();
+const spawn = this.level.landmark('spawn');
+this.playerController.teleportTo(spawn.position[0], spawn.position[1], spawn.position[2], spawn.yaw);
+this.playerController.configureFallRescue({ ...DEFAULT_FALL_RESCUE_OPTIONS, killPlaneY: loaded.bounds.minY - 50 });
+
+const guards = this.engine.registerNpc('guards', new NpcIdleBehavior(), { autoRespawn: false });   // any INpcBehavior — engine/agent-docs/npc-system.md
+for (const post of this.level.landmarksTagged('guard')) {
+    await guards.spawn(post.position[0], post.position[2], post.position[1]);   // (x, z, y): Y picks the storey
+}
+\`\`\`
+
+- \`landmark(name)\` throws with the known names when one is missing; a typo cannot spawn the boss
+  at the origin. \`landmarksTagged(tag)\` for posts, \`volumesAt(position)\` for "which room am I in".
+- NPC spawns on a mesh level resolve the floor with raycasts (there is no voxel grid). Pass the
+  storey's Y for interior spawns, or an upstairs room resolves to the roof above it.
+- \`DEFAULT_MESH_LEVEL_OPTIONS.lighting.mode\` is \`interior\`: the sun is dimmed through
+  \`lightingConfig\`, the template's hemisphere light reused, JSON point lights pooled, the first two
+  shadow-casting spots cached. An outdoor level (the courtyard game) wants
+  \`{ ...DEFAULT_MESH_LEVEL_OPTIONS, lighting: { ...DEFAULT_MESH_LEVEL_LIGHTING, mode: 'exterior' } }\`.
+- \`dispose()\` removes bodies, lights and the scene, and restores the lighting config and the spawn
+  finder it replaced — call it before loading another level.
+
+## Verify, and the four ways it fails silently
+
+\`bitmagic verify\` must print \`[MeshLevel] loaded "<cdn url>" — N colliders …\` with the count the
+build printed. Then:
+
+1. **Verify passes, published game is empty** — the GLB was a local path (above).
+2. **Verify passes, doors animate inside walls** — \`sync_world.py\` was not re-run after a rebuild.
+3. **Verify passes, zero NPCs** — spawns given without the storey's Y on a multi-floor level, or
+   posts declared inside a wall; the console shows the finder returning null for each.
+4. **Verify passes, the level is bright white** — \`lighting.mode\` is \`exterior\`, or \`lightingConfig\`
+   in world.json sets a sun the preset then merges with. The preset only lowers what it names.
+`;
+}
+//# sourceMappingURL=blender-level-skill-files.js.map

package/dist/scaffold/blender-level-skill-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blender-level-skill-files.js","sourceRoot":"","sources":["../../src/scaffold/blender-level-skill-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,UAAU,wBAAwB;IACtC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsMR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,iCAAiC;IAC/C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyFR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,4BAA4B;IAC1C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmER,CAAC;AACF,CAAC;AAED,MAAM,UAAU,4BAA4B;IAC1C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkER,CAAC;AACF,CAAC;AAED,MAAM,UAAU,mCAAmC;IACjD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2FR,CAAC;AACF,CAAC"}

package/dist/scaffold/project-files.js

@@ -749,7 +749,7 @@ If you are unsure whether one is already running, \`bitmagic reload\` says so an
   itself: \`planning-a-game/\` (what to build first), \`finding-engine-apis/\` (engine docs),
   \`generating-assets/\`, \`working-with-the-creator/\`, \`theming-the-hud/\`,
   \`publishing-a-game/\`, \`judging-quality/\`, \`checking-usage/\`, \`making-a-trailer/\`,
-  \`converting-unity-levels/\`.${mirrorClause}
+  \`converting-unity-levels/\`, \`building-levels-in-blender/\`.${mirrorClause}
   \`upgrade\` rewrites every copy, so edits to them are lost; skills you add yourself are never
   touched.
 - \`.claude/settings.json\` — **Claude Code only, and yours**: seeded with one Stop hook that runs
@@ -1051,7 +1051,9 @@ terrain, props, spawn points — into \`src/work/world.json\`. \`bitmagic levels
 | set-start | remove\` manages them afterwards (free, local); \`set-start\` is how you change which
 level the game boots into, and it moves the legacy mirror fields with it. Add \`--city\`, \`--dungeon\`,
 \`--platformer\` or \`--freeform\` (at most one) for a different kind of place; omit them all for
-natural terrain.
+natural terrain. A place designed part by part — an interior, a station, a stylised set — can
+instead be built in Blender from a script: \`${PRIMARY_SKILLS_DIR}/building-levels-in-blender/SKILL.md\`,
+whose first section says when that path is yours (a frontier model, Blender installable).
 
 Four things worth knowing:
 
@@ -1062,8 +1064,7 @@ Four things worth knowing:
    voxelizing is the engine's own code. The command builds and serves the project itself, so you
    do not need \`bitmagic dev\` running and it will not collide with one that is.
 3. **It rewrites large parts of \`world.json\`** (assets, environmentObjects, the level registry,
-   spawn points), so re-read the file afterwards if you were editing it. It also drops a
-   \`forged-heightfield.json\` beside it, which later placements use to sit objects on the terrain.
+   spawn points), so re-read the file afterwards if you were editing it.
 4. **Resume rather than re-run.** The command prints a job id, \`world.json\` only ever changes on
    the final step, and every failure says whether it did and whether
    \`bitmagic forge --resume <jobId>\` is worth it — which is twenty minutes you do not spend again.
@@ -1152,6 +1153,7 @@ the engine, already wired** — and hand-building a worse version of it is the m
 | Animals, snakes, fish, birds, dragons | Procedural creature systems | \`animal-instructions.md\`, \`snake-instructions.md\` |
 | Score, timers, health bars, game-over and win screens | HUD + end-game systems | \`HUD_ELEMENTS.md\`, \`end-game.md\` |
 | A start screen — cover image, title, Play-button label | Start-screen system | \`START_SCREEN.md\` |
+| An opening cutscene or any full-screen video | \`engine.playVideo()\` fullscreen overlay | \`video-cutscenes.md\` |
 | Collectibles, pickups, checkpoints, markers | Dedicated systems | \`collectible-objects.md\`, \`markers-system.md\` |
 | Doors, locked doors and their keys | \`worldProfileData.doors[]\` + \`keyItems[]\` | \`doors-and-locks.md\` |
 | Moving platforms, elevators, crushers, conveyors, spinners | \`mechanisms[]\` in world.json | \`moving-platforms.md\` |
@@ -1207,7 +1209,7 @@ player to move) either builds no player controller (the \`no-character\` templat
 - Controls:           every action as desktop key + phone button, bound in one call
 - Engine systems:     one line each, naming the doc — \`engine/agent-docs/…\`
 - Assets to generate: name them. A skybox and the cover usually earn their place in slice 1.
-- Level:              procedural baseline terrain, unless the terrain IS the mechanic
+- Level:              procedural baseline terrain, unless the terrain IS the mechanic (forge — or Blender, if that skill's gate passes)
 
 ## Deferred — the backlog
 Numbered, roughly best-first. Everything the design implies that slice 1 does not do.
@@ -1244,7 +1246,11 @@ ${PLANNING_SKILL_REFERENCE_STEP4}4. \`bitmagic cover\` — **now**, not later. I
 so it sets how long the human waits for slice 1. It belongs in slice 1 for a game that cannot be
 played without its shape — skiing, racing on a real circuit, open-world driving, an enclosed dungeon
 interior. For everything else the baseline's procedural voxel terrain is a fine slice-1 world and the
-forge is backlog item 1, run once the loop is proven.
+forge is backlog item 1, run once the loop is proven. A designed place — an interior, a station, a
+stylised set the creator has a picture of — has a second route, building it in Blender from a
+script (\`${PRIMARY_SKILLS_DIR}/building-levels-in-blender/SKILL.md\`); its first section is a gate
+on the model and on Blender being available, and it belongs in slice 1 only under the same rule as
+the forge.
 
 ## Step 5 — hand it back
 
@@ -1339,6 +1345,7 @@ tier 2.
 | HUD elements — bars, scores, counters, timers | \`HUD_ELEMENTS.md\` |
 | HUD visual style and themes | \`HUD_STYLE_GUIDE.md\`, \`HUD_THEMES.md\` |
 | Start screen — cover image, title, Play-button label | \`START_SCREEN.md\` |
+| An opening cutscene or any full-screen video — \`engine.playVideo\` | \`video-cutscenes.md\` |
 | Collectibles and interactables | \`collectible-objects.md\` |
 | Placed scenery / \`environmentObjects\` — gameplay near props, harvesting, occupancy | \`environment-objects.md\` |
 | Doors, locked gates, keycards | \`doors-and-locks.md\` |