@bitmagic/cli 0.1.64-dev.1 → 0.1.64-dev.11

package/README.md

@@ -192,7 +192,7 @@ browser reloads itself on every change and the assets panel shows each generatio
 | `bitmagic logout [--env <env>]` | Remove stored credentials for an environment. |
 | `bitmagic reset-account [--env <env>] [--yes] [--keep-cli]` | **Deletes your account** on `dev` or `local` so the first-run experience can be tested again — games, sparks, profile, terms acceptance and Bitmagic Pro (cancelled in Stripe first). Then clears that environment's stored credentials **and uninstalls this CLI**, so the next run starts where a new creator starts: `npm install -g @bitmagic/cli`. `--keep-cli` skips that last step. Refuses `prod`, where the endpoint is not deployed at all. Asks you to type the environment name; `--yes` skips that and is required in a shell with no terminal. Your project directory is left alone — its `gameId` no longer exists, so start the fresh run in a new one. |
 | `bitmagic whoami [--env <env>]` | Show the identity the CLI is authenticated as — the account's email address alongside its user id — and which environment answered, including where that environment was chosen from. |
-| `bitmagic init [dir] [--template <id>] [--name <name>] [--idea "<pitch>"] [--env <env>] [--force]` | Scaffold a new project: mints a game, downloads the vendored engine, writes `AGENTS.md`, `GAME-DESIGN.md` and templates. Starts from `empty-3d` unless told otherwise. `--idea` seeds the design doc's pitch **and** picks the template whose camera and controls fit it — "a doom-like corridor shooter" scaffolds `first-person`, "jump between floating islands" scaffolds `sidescroller`. `--template` overrides both; a suggestion that fails for any reason falls back to `empty-3d` rather than failing the scaffold. Dependencies are installed with **pnpm** when your machine has it and npm otherwise — the lockfile that produces is what every later command reads, so it never tells you to run the wrong one. |
+| `bitmagic init [dir] [--template <id>] [--name <name>] [--idea "<pitch>"] [--art-style <voxel\|low-poly>] [--env <env>] [--force]` | Scaffold a new project: mints a game, downloads the vendored engine, writes `AGENTS.md`, `GAME-DESIGN.md` and templates. Starts from `empty-3d` unless told otherwise. `--idea` seeds the design doc's pitch **and** picks the template whose camera and controls fit it — "a doom-like corridor shooter" scaffolds `first-person`, "jump between floating islands" scaffolds `sidescroller`. `--template` overrides both; a suggestion that fails for any reason falls back to `empty-3d` rather than failing the scaffold. Dependencies are installed with **pnpm** when your machine has it and npm otherwise — the lockfile that produces is what every later command reads, so it never tells you to run the wrong one. |
 | `bitmagic import <export.zip> [dir] [--name <name>] [--new-game] [--no-rehost] [--env <env>] [--force]` | Convert a game exported from the **web Creator** into a CLI project. Takes the `.zip` the Creator's "Export game" button downloads, writes its `source/` into `src/work/`, vendors the current engine around it, and produces the same project `init` does. **Keeps the game's id**, so `publish` updates the game you already have and every asset URL keeps resolving; `--new-game` forks instead, minting a fresh game and rewriting the id through `game.json` and `world.json`. Assets belonging to a **different** environment than the project are copied onto this one and the references rewritten, so a dev game imported to prod serves its own assets (`--no-rehost` leaves them). Defaults the directory to `./<gameId>`. See **Importing a Creator game** below. |
 | `bitmagic check` | Typecheck (`tsc --noEmit`) against the vendored engine. Fast; does not prove the game runs. |
 | `bitmagic dev [--port <port>] [--editor-port <port>] [--no-open] [--mobile] [--mobile-http]` | Build, then serve everything and keep it running: `tsc --watch`, `vite`, and a **Game / Editor** view that reloads itself when the project changes, and shows where the game is published (with a QR code) once it has been. Every project on the machine gets its own fixed pair of ports and keeps them — 3010/3011 for the first, 3020/3021 for the next, and so on (see **One project, one set of ports** below). Opens the view in your browser, unless the tab from the previous run is still there, in which case that tab reloads itself instead; `--no-open` (or `BITMAGIC_NO_OPEN=1`) skips opening altogether. `--mobile` also serves the game to phones on your network, over https, and prints a QR code for that. The one command to leave open. See **The dev view** below. |
@@ -202,8 +202,8 @@ browser reloads itself on every change and the assets panel shows each generatio
 | `bitmagic publish [--visibility public\|private] [--name <name>] [--description <desc>] [--force] [--single-file] [--no-qr]` | Verify-gate, build if needed, and upload straight to GCS. `--single-file` publishes the offline bundle described under `bitmagic build`; switching the flag between runs always rebuilds, since it changes nothing on disk for the reuse check to notice. **Keeps the game's current visibility**; a new game is private until published with `--visibility public`. Shows the published URL as a QR code so you can scan it onto a phone — drawn in the terminal, or written to `.bitmagic/publish-qr.png` when it cannot be. `--no-qr` skips both. |
 | `bitmagic self-update [--tag latest\|dev]` | Update the **CLI itself** to the newest build of its line, installing into the place this CLI actually lives rather than wherever the `npm` on your `PATH` would put it — which under nvm is routinely somewhere else. Reads the project's line from `bitmagic.json` when there is one, so it also fixes a wrong-line install; `--tag` overrides. Verifies the version on disk moved, and refuses (naming the path) for an `npx` run, a source checkout, or an install shape it cannot recognise. Not to be confused with `upgrade`, which is about the project's engine. |
 | `bitmagic upgrade [--engine <version>] [--force]` | Refresh vendored platform files and the CLI's own skills to the currently published engine. Refuses a dirty git tree unless `--force`. Also records the project's `environment` in `bitmagic.json` if it has none yet — the engine it just vendored came from that api-server — and says so when it does. |
-| `bitmagic generate <skybox\|background\|block-type\|sound\|music\|image\|video\|character\|animation\|model\|prop\|vehicle> ...` | Generate one asset directly into `src/work/world.json`. Costs sparks. `model` mints a **new** 3D object from a prompt, `prop` upgrades an existing placeholder **in place** (both produce voxels directly; `--mesh` takes the older mesh path), `vehicle` adds a new drivable one, `animation` takes a parameter spec rather than a prompt, `block-type` registers a custom voxel block, `video` makes a short clip for a cutscene (played with `engine.playVideo("<id>")`) — see below. `skybox` and `background` write the **same** field: pick one. |
-| `bitmagic assets add <file> [--name <n>] [--asset-id <id>] [--keep-glb] [--voxel-size <m>] [--max-voxel-size <m>] [--height <m>] [--hollow\|--solid] [--force]` | Upload **your own** file — `.glb`, `.vxl`, `.png/.jpg/.webp`, `.opus/.ogg/.m4a/.mp3`, `.json` — into the game's assets and write its entry into `src/work/world.json`. A `.glb` is voxelized in a headless browser (Chrome + a free port in 3000–3199, like `prop`) unless `--keep-glb`. Free — no sparks. See **Adding your own assets** below. |
+| `bitmagic generate <skybox\|background\|block-type\|sound\|music\|image\|video\|character\|animation\|model\|prop\|vehicle> ...` | Generate one asset directly into `src/work/world.json`. Costs sparks. `model` mints a **new** 3D object from a prompt, `prop` upgrades an existing placeholder **in place** (both produce voxels directly; `--mesh` takes the older mesh path; a low-poly project keeps the mesh as a `glb` asset — see **Art style**), `vehicle` adds a new drivable one, `animation` takes a parameter spec rather than a prompt, `block-type` registers a custom voxel block, `video` makes a short clip for a cutscene (played with `engine.playVideo("<id>")`) — see **Cutscene clips** below. `skybox` and `background` write the **same** field: pick one. |
+| `bitmagic assets add <file> [--name <n>] [--asset-id <id>] [--keep-glb\|--voxelize] [--voxel-size <m>] [--max-voxel-size <m>] [--height <m>] [--hollow\|--solid] [--force]` | Upload **your own** file — `.glb`, `.vxl`, `.png/.jpg/.webp`, `.opus/.ogg/.m4a/.mp3`, `.json` — into the game's assets and write its entry into `src/work/world.json`. A `.glb` is voxelized in a headless browser (Chrome + a free port in 3000–3199, like `prop`) unless `--keep-glb` — or unless the project is low-poly (see **Art style**). Free — no sparks. See **Adding your own assets** below. |
 | `bitmagic assets list` | The assets in `world.json`: id, name, type, size, placed instances, and total references. Local, no network. |
 | `bitmagic assets materials <assetId> [--set <file.json>] [--auto] [--clear]` | Show what an asset's voxels look like, or say what they are **made of** — so a sword's steel blade shines and its leather grip does not. With no flag it prints the asset's colour groups; `--set` applies your verdicts; `--auto` lets a model decide (what `generate prop` and `generate model` already do on their own); `--clear` removes them. Free — no sparks, nothing generated. See **Voxel materials** below. |
 | `bitmagic assets remove <assetId> [--force]` | Remove an asset from `world.json` (the uploaded file stays in storage). Refuses while anything in `world.json` still references it; `--force` removes the asset and its placed instances together. |
@@ -211,10 +211,11 @@ browser reloads itself on every change and the assets panel shows each generatio
 | `bitmagic reference <make\|accept\|show\|clear> ...` | Make a concept image of the game's world, iterate until it is right, and `accept` one — the accepted image becomes the default style reference for `generate skybox\|background\|block-type\|image`, `cover` and `forge`. Only `make` costs sparks (priced like an image). See **Reference image** below. |
 | `bitmagic judge [--genre <name>] [--platform desktop\|mobile] [--min-score <1-10>]` | Grade the screenshot `bitmagic verify` captured against a quality rubric built from `GAME-DESIGN.md` (plus an optional genre hint) with a vision model, and print a scorecard: four dimension scores and at most three actionable findings, also written to `.bitmagic/judge.json`. Informs rather than gates — exits 0 whatever the score, unless `--min-score` sets a bar (exit 4 below it). `--platform` picks which frame to grade; with no flag it grades the mobile one when the game is mobile-primary and `screenshot.mobile.png` exists, and the mobile rubric folds touch-HUD legibility, thumb reach and phone framing into the existing `readability` and `polish` dimensions rather than adding a fifth score. Warns when the project changed since the screenshot. Costs sparks (a few per run — one call to a model that reasons about the frame before it scores). |
 | `bitmagic trailer record [--seconds N] [--resolution WxH] [--flythrough <path.json>]` | Record gameplay for a trailer: opens Chrome on the running `bitmagic dev`, waits for Play, starts the engine's F9 recorder for you, stops after N seconds or your F9, and prints the recording dir (`.bitmagic/trailer/recordings/<name>/`). `--flythrough` records an authored camera path with nobody playing. |
-| `bitmagic trailer make [--music-prompt "..." \| --music <file> \| --no-music] [--title <t>] [--seconds 30] [--ui] [--publish] [--reset-shots]` | The one-shot: analyze the newest recording, lay a music bed (generated from a prompt — sparks — or your file), write a first cut to `trailer/shots.json` or cut the one you edited, render `<game>-trailer.mp4` (new `-rN` each run), and with `--publish` put it on the CDN and the game page. |
-| `bitmagic trailer analyze \| beats \| cut \| render \| merge` | The steps of `make` as separate commands: score a recording into highlight windows with contact sheets; detect a track's beat grid; turn `trailer/shots.json` into a frame-exact `edl.json`; render an EDL (`--ui` redraws the HUD, `--logo`, `--music …`); join recordings from separate sittings. |
+| `bitmagic trailer make [--music-prompt "..." \| --music <file> \| --no-music] [--title <t>] [--seconds 30] [--ui] [--ui-keyframe-rate 30] [--publish] [--reset-shots]` | The one-shot: analyze the newest recording, lay a music bed (generated from a prompt — sparks — or your file), write a first cut to `trailer/shots.json` or cut the one you edited, render `<game>-trailer.mp4` (new `-rN` each run), and with `--publish` put it on the CDN and the game page. |
+| `bitmagic trailer analyze \| beats \| cut \| render \| merge` | The steps of `make` as separate commands: score a recording into highlight windows with contact sheets; detect a track's beat grid; turn `trailer/shots.json` into a frame-exact `edl.json`; render an EDL (`--ui` redraws the HUD, `--ui-keyframe-rate` caps how often it may change, `--logo`, `--music …`); join recordings from separate sittings. |
 | `bitmagic trailer publish <file.mp4> [--no-attach]` | Upload a trailer (`.mp4`/`.webm`, ≤ 200 MiB, header-checked so a renamed image is refused before upload) to the CDN under `game-media/<gameId>/` and put it at the front of the game page gallery. Re-running replaces the previous trailer (remembered in `.bitmagic/trailer/published.json`); the page is capped at 12 media items. Works before the first publish — the page goes live on the first `bitmagic publish --visibility public`. `--no-attach` uploads only. |
 | `bitmagic forge --prompt "..." [--city\|--dungeon\|--platformer\|--freeform] [--name <name>] [--resume <jobId>]` | Design and bake a whole playable level into `world.json`. Costs sparks, and takes many minutes — the bake alone can take twenty. `--resume <jobId>` picks a failed run back up from the last step that finished, rather than redoing the whole thing. |
+| `bitmagic tools <list\|path\|install> [bundle]` | The script bundles the CLI ships for skills that drive Blender or Python (`blender-level`, `unity-import`): what they are, where this install keeps them, and `install` to copy one into the project's `tools/`. Local, no network, no sparks. |
 | `bitmagic levels <list\|add\|rename\|set-start\|remove> ...` | Manage the levels `forge` creates: which one boots, their names, registering a bake you already have, deleting one. Local, no network, no sparks. See **Managing levels** below. |
 
 Every command exits non-zero on failure with a single-line message (no stack trace) and, where a
@@ -430,6 +431,7 @@ my-game/
       <name>/               # that recording's analysis.json, sheets/, beats.json, music.mp3, edl.json and renders
       published.json        # the trailer's CDN URL after bitmagic trailer publish
     previews/                # rendered asset thumbnails, cached so they are drawn once
+    videos/<assetId>.png     # 8 frames from a generated clip, tiled — what `generate video` leaves to look at
     build/
       index.html            # bitmagic build's output bundle
       manifest.json          # engineVersion, fingerprint, bytes, sha256, builtAt
@@ -503,6 +505,30 @@ Re-running on an unchanged design generates nothing and costs nothing — it rep
 cover. Edit the design and run again, or pass `--force`, to replace it. Because it writes
 `world.json`, it invalidates a passing verify: run it before `bitmagic verify`, not after.
 
+## Cutscene clips
+
+`bitmagic generate video --prompt "the castle gates swing open, dust drifting"` makes a short 720p
+clip, writes it into `world.json` as a `type: "video"` asset, and prints the `engine.playVideo("<id>")`
+call that plays it as a fullscreen overlay. `--duration` sets the length (billed per second);
+`--image` animates a still you already have as the first frame, which is much slower and takes the
+clip's shape from the image rather than the 16:9 default.
+
+Because a clip is paid for before anyone can tell whether it is any good, the command leaves you
+something to look at: **8 frames spread across the clip, tiled into `.bitmagic/videos/<assetId>.png`**.
+Open it to check the clip actually shows what was asked for, without downloading the mp4 and writing
+an ffmpeg filter by hand. It needs `ffmpeg` on `PATH`; without it the command still succeeds and
+says why there are no frames. `--no-contact-sheet` skips the download.
+
+The same pass says **whether the clip carries an audio track** — today's generated clips are silent,
+so a cutscene that needs sound needs a music bed under it, and that is invisible in the frames.
+
+To watch it move rather than as stills, `bitmagic dev`'s assets panel plays it.
+
+One rule when you wire it up: call `engine.playVideo()` **from the Play click or later**, never
+before. Without a prior user gesture the browser blocks autoplay, and the engine resolves the call
+immediately — so the cutscene silently does not run. `engine/agent-docs/video-cutscenes.md` covers
+that and what to freeze while a cutscene plays.
+
 ## Reference image
 
 When a game has a strong setting — a tropical island, a neon city — one accepted concept image can
@@ -1209,6 +1235,55 @@ booting one level's terrain under another's objects).
 Runtime level switching is engine API — `engine.loadLevel(levelId)` from game code. These commands
 manage the registry, not gameplay.
 
+## Building a level in Blender
+
+A hand-designed low-poly world — an interior, a station, a stylised set — can be written as a short
+Python script against the `bmlevel` library that ships in this package (`assets/blender-level/`),
+built by Blender into one GLB plus the collider / door / light / landmark JSON, audited with ray
+casts and rendered for review, then registered with `bitmagic assets add … --keep-glb` and loaded
+by the engine's `MeshLevel`. The scaffolded `building-levels-in-blender` skill walks through it;
+its first section says when that path applies (a frontier model, and Blender installed) and sends
+everything else to `bitmagic forge`.
+
+## Art style
+
+A 3D game is voxel-built unless `src/work/game.json` says otherwise:
+
+```json
+{ "gameName": "…", "artStyle": "low-poly" }
+```
+
+`artStyle` sits beside `physicsMode` and takes `voxel` (the default, and what an absent field
+means) or `low-poly`. `bitmagic init --art-style low-poly` writes it and pre-fills
+`GAME-DESIGN.md`'s Art direction heading; an existing project adds the line by hand. One field,
+read by everything that used to assume cubes:
+
+| Command | `voxel` | `low-poly` |
+|---|---|---|
+| `bitmagic cover`, `bitmagic reference make` | MagicaVoxel-style prompt lead and tail | flat-shaded low-poly lead and tail (same image model) |
+| `bitmagic assets add x.glb` | voxelized in a headless browser | kept as a `glb` asset; `--voxelize` bakes it |
+| `bitmagic generate model` / `prop` | voxel master, baked in the browser | mesh generated, re-uploaded into the project, registered as `glb` (`--height` / the placeholder's fitBox); `--voxelize` bakes it |
+| `bitmagic generate character` | voxelized rig, library search first | the textured low-poly rig, no library; `--voxelize` overrides |
+| `bitmagic generate vehicle` | voxel | still voxel — the builder is voxel-native; the command says so |
+| `bitmagic judge` with no `## Art direction` | grades the style it sees | judges within low-poly |
+| the engine on load | sunset hemisphere light and a faint bloom | neither; a `MeshLevel` brings its own lighting |
+
+In a low-poly game the textured rig IS the product, so `bitmagic generate character` forges it with
+`runware-meshy-6`: an even remesh with symmetric limbs and an enforced A-pose, rather than a TRELLIS
+reconstruction that is only as low-poly as the concept image happened to be. **That costs about
+$0.80 and six minutes per character**, against fractions of a cent and forty seconds — pass
+`--mesh-model unified-trellis` to put one back on the cheap lane. A voxel game does not get it: the
+body is rebuilt out of cubes, so the remesh, the pose and the texture are all thrown away.
+
+Its wall time is why the forge job budget is 20 minutes and api-server's in-handler generation
+deadline is 29: at the old 8-minute and 280s ceilings a Meshy character was killed about three
+seconds before it finished, after being billed. Cloud Run's own 1800s request timeout was already
+high enough and is set in roleverse-infra.
+
+Both commands print `Art style: … (game.json)` so a transcript shows which medium drove them, and a
+value that is neither word is reported once and treated as voxel. The web Creator does not read
+the field: its planner builds voxel games only.
+
 ## Publishing
 
 `bitmagic publish` is two gated steps in one command:

package/assets/blender-level/README.md

@@ -0,0 +1,25 @@
+# blender-level
+
+The Python and Blender scripts behind the `building-levels-in-blender` skill (see
+`cli/src/scaffold/blender-level-skill-files.ts`). A level is a short Python script written against
+`bmlevel` — boxes, prisms, walls, doors, stairs, signage, rooms, lights, landmarks, all in game
+coordinates — that Blender runs to produce one GLB (joined per material), an editable `.blend`
+(named parts), a `bitmagic-mesh-level` JSON the engine's `MeshLevel` loads, and a `doors.json` in
+the shape of `worldProfileData.doors[]`. Shipped here (package.json `files`) rather than rendered
+into every project: most games never build a level this way, and the scripts are large. The
+skill's step 1 tells an agent how to copy them into a project's `tools/blender-level/`.
+
+| File | Runs under | Does |
+|---|---|---|
+| `find_blender.py` | python3 | prints the Blender executable, or how to install one |
+| `bmlevel/` | Blender, or python3 for a dry run | the authoring vocabulary (`__init__.py`), the bpy-free maths and JSON writers (`core.py`), the Blender backend (`scene_bpy.py`) and the recording backend (`scene_null.py`) |
+| `example_level.py` | either | a complete hut-and-courtyard level using every helper; the tests' fixture |
+| `audit.py` | Blender | ray-cast audit of the COLLIDERS: floor continuity, door and route clearance, sealed envelopes, z-fighting candidates |
+| `review.py` | Blender | deterministic review renders (overview, every door, every stair, every room) and a contact sheet |
+| `sync_world.py` | python3 | carries the doors, spawn and `terrain.shape: 'none'` into `src/work/world.json` |
+| `tests/` | python3 | `python3 -m unittest discover -s tests` — no Blender needed; `cli`'s `pnpm test` runs it |
+
+The JSON contract is owned by the engine (`game/src/engine/meshlevel/MeshLevelSchema.ts`,
+documented in `game/agent-docs/mesh-level.md`); `core.py` writes exactly that shape, and the
+engine's validator is the arbiter when the two disagree. The intended end state is a
+`bitmagic level build` command wrapping these once a second game has been through them.

package/assets/blender-level/audit.py

@@ -0,0 +1,232 @@
+"""Ray-cast audit of a built level, run inside Blender against the COLLIDERS the engine will get
+(not the art — decoration is exactly what must not be solid):
+
+    "$BLENDER" -b --python tools/blender-level/audit.py -- build/level/hut.mesh-level.json [--doors closed] [--json out.json]
+
+Checks, all driven by the level JSON:
+  floor_continuity   every volume: a ray down from 1 m above its floor must hit within 1.5 m on a 0.5 m grid
+  door_clearance     every door (doors open): nothing solid across the opening at three heights
+  link_clearance     every link: a player capsule (r 0.4, h 1.8) marched from A through the door to B never
+                     hits a wall and always has a floor under it
+  sealed_envelope    (--doors closed only) every roofed volume: rays up and outward from inside hit something —
+                     no hole in a roof or wall the player could fall through
+  coplanar_overlap   pairs of box colliders with a shared face plane and overlapping extents — z-fighting
+                     candidates; a WARNING, not a failure
+
+Exit 1 on any failure. `--json` also writes the full result for a script to read.
+"""
+import json
+import math
+import os
+import sys
+
+import bmesh
+from mathutils import Vector
+from mathutils.bvhtree import BVHTree
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from bmlevel.core import box_corners, flat_to_points, rotate_xz, to_blender  # noqa: E402
+
+argv = sys.argv[sys.argv.index('--') + 1:] if '--' in sys.argv else sys.argv[1:]
+if not argv:
+    print(__doc__)
+    sys.exit(2)
+LEVEL_PATH = argv[0]
+DOORS_CLOSED = '--doors' in argv and argv[argv.index('--doors') + 1] == 'closed'
+JSON_OUT = argv[argv.index('--json') + 1] if '--json' in argv else None
+DOORS_PATH = LEVEL_PATH.replace('.mesh-level.json', '.doors.json')
+
+level = json.load(open(LEVEL_PATH))
+doors = json.load(open(DOORS_PATH)) if os.path.exists(DOORS_PATH) else []
+
+# ---------------------------------------------------------------- BVH from colliders
+
+verts: list[Vector] = []
+faces: list[tuple] = []
+BOX_FACES = [(0, 1, 3, 2), (4, 6, 7, 5), (0, 4, 5, 1), (2, 3, 7, 6), (0, 2, 6, 4), (1, 5, 7, 3)]
+
+
+def add_box(center, size, yaw) -> None:
+    base = len(verts)
+    verts.extend(Vector(to_blender(p)) for p in box_corners(center, size, yaw))
+    faces.extend(tuple(base + i for i in f) for f in BOX_FACES)
+
+
+def add_hull(flat) -> None:
+    bm = bmesh.new()
+    for p in flat_to_points(flat):
+        bm.verts.new(to_blender(p))
+    bm.verts.ensure_lookup_table()
+    bmesh.ops.convex_hull(bm, input=list(bm.verts))
+    base = len(verts)
+    index = {v: i for i, v in enumerate(bm.verts)}
+    verts.extend(v.co.copy() for v in bm.verts)
+    faces.extend(tuple(base + index[v] for v in f.verts) for f in bm.faces)
+    bm.free()
+
+
+boxes = []
+for c in level['colliders']:
+    if c['shape'] == 'box':
+        add_box(c['position'], c['size'], c.get('yaw', 0.0))
+        boxes.append(c)
+    else:
+        add_hull(c['vertices'])
+if DOORS_CLOSED:
+    for d in doors:
+        p = d['position']
+        add_box((p['x'], p['y'], p['z']), (d['width'], d['height'], d['thickness']), d.get('rotationY', 0.0))
+bvh = BVHTree.FromPolygons(verts, faces) if faces else None
+
+
+def cast(origin, direction, limit):
+    """Ray in GAME coordinates; returns hit distance or None."""
+    if bvh is None:
+        return None
+    o = Vector(to_blender(origin))
+    d = Vector(to_blender(direction))
+    hit = bvh.ray_cast(o, d, limit)
+    return hit[3] if hit[0] is not None else None
+
+
+# ---------------------------------------------------------------- checks
+
+results: dict[str, dict] = {}
+
+
+def record(check: str, ok: bool, detail: dict) -> None:
+    r = results.setdefault(check, {'checks': 0, 'failures': []})
+    r['checks'] += 1
+    if not ok:
+        r['failures'].append(detail)
+
+
+def volume_grid(v, step=0.5, inset=0.35):
+    px, py, pz = v['position']
+    sx, sy, sz = v['size']
+    yaw = v.get('yaw', 0.0)
+    xs = [x for x in frange(-sx / 2 + inset, sx / 2 - inset, step)]
+    zs = [z for z in frange(-sz / 2 + inset, sz / 2 - inset, step)]
+    for lx in xs:
+        for lz in zs:
+            wx, wz = rotate_xz(lx, lz, yaw)
+            yield (px + wx, py - sy / 2, pz + wz), (lx, lz)
+
+
+def frange(a, b, step):
+    n = max(1, int(round((b - a) / step)))
+    return [a + (b - a) * i / n for i in range(n + 1)] if b > a else [(a + b) / 2]
+
+
+volumes = {v['name']: v for v in level.get('volumes', [])}
+for v in level.get('volumes', []):
+    for (x, floor_y, z), local in volume_grid(v):
+        hit = cast((x, floor_y + 1.0, z), (0, -1, 0), 2.5)
+        record('floor_continuity', hit is not None and hit <= 1.5, {'volume': v['name'], 'at': [round(x, 2), round(z, 2)], 'local': [round(local[0], 2), round(local[1], 2)]})
+
+if DOORS_CLOSED:
+    for v in level.get('volumes', []):
+        if 'unroofed' in v.get('tags', []):
+            continue
+        sx, sy, sz = v['size']
+        yaw = v.get('yaw', 0.0)
+        for (x, floor_y, z), local in volume_grid(v, step=1.0):
+            up = cast((x, floor_y + 0.5, z), (0, 1, 0), sy + 1.0)
+            record('sealed_envelope', up is not None, {'volume': v['name'], 'kind': 'roof', 'at': [round(x, 2), round(z, 2)]})
+            for dx, dz, limit in ((1, 0, sx / 2 - local[0] + 1.0), (-1, 0, sx / 2 + local[0] + 1.0), (0, 1, sz / 2 - local[1] + 1.0), (0, -1, sz / 2 + local[1] + 1.0)):
+                wx, wz = rotate_xz(dx, dz, yaw)
+                side = cast((x, floor_y + sy / 2, z), (wx, 0, wz), limit)
+                record('sealed_envelope', side is not None, {'volume': v['name'], 'kind': 'wall', 'at': [round(x, 2), round(z, 2)], 'dir': [dx, dz]})
+else:
+    for d in doors:
+        p = d['position']
+        yaw = d.get('rotationY', 0.0)
+        fx, fz = rotate_xz(0.0, 1.0, yaw)
+        rx, rz = rotate_xz(1.0, 0.0, yaw)
+        base_y = p['y'] - d['height'] / 2
+        span = d['thickness'] + 1.2
+        for lateral in frange(-d['width'] / 2 + 0.12, d['width'] / 2 - 0.12, 0.25):
+            for h in (0.3, 1.0, d['height'] - 0.25):
+                origin = (p['x'] + rx * lateral - fx * span / 2, base_y + h, p['z'] + rz * lateral - fz * span / 2)
+                hit = cast(origin, (fx, 0, fz), span)
+                record('door_clearance', hit is None, {'door': d['id'], 'lateral': round(lateral, 2), 'height': round(h, 2)})
+
+    door_by_id = {d['id']: d for d in doors}
+    for l in level.get('extras', {}).get('links', []):
+        a, b = volumes.get(l['from']), volumes.get(l['to'])
+        if not a or not b:
+            record('link_clearance', False, {'link': l, 'reason': 'unknown volume'})
+            continue
+        waypoints = [tuple(a['position'])]
+        if l.get('door'):
+            d = door_by_id.get(l['door'])
+            if not d:
+                record('link_clearance', False, {'link': l, 'reason': 'unknown door'})
+                continue
+            waypoints.append((d['position']['x'], d['position']['y'] - d['height'] / 2 + 0.9, d['position']['z']))
+        waypoints.append(tuple(b['position']))
+        for i in range(len(waypoints) - 1):
+            (x0, y0, z0), (x1, y1, z1) = waypoints[i], waypoints[i + 1]
+            n = max(1, int(math.hypot(x1 - x0, z1 - z0) / 0.5))
+            for k in range(n + 1):
+                t = k / n
+                x, z = x0 + (x1 - x0) * t, z0 + (z1 - z0) * t
+                # Probe for the floor from just above waist height: a door waypoint sits under its
+                # header, and a ray from higher up would start inside the lintel.
+                probe_y = y0 + (y1 - y0) * t + 0.5
+                floor = cast((x, probe_y, z), (0, -1, 0), 3.0)
+                record('link_clearance', floor is not None, {'link': [l['from'], l['to']], 'at': [round(x, 2), round(z, 2)], 'reason': 'no floor'})
+                if floor is None:
+                    continue
+                fy = probe_y - floor
+                for h in (0.5, 1.5):
+                    for dx, dz in ((1, 0), (-1, 0), (0, 1), (0, -1)):
+                        # Rays run along the march direction's perpendiculars and along it; a wall
+                        # within capsule radius means the route squeezes through something.
+                        blocked = cast((x, fy + h, z), (dx, 0, dz), 0.4)
+                        record('link_clearance', blocked is None, {'link': [l['from'], l['to']], 'at': [round(x, 2), round(z, 2)], 'height': h, 'dir': [dx, dz], 'reason': 'wall within 0.4 m'})
+
+# Z-fighting candidates: two boxes sharing a face plane with overlapping extents (axis-aligned only).
+warnings = []
+def faces_of(b):
+    if abs(b.get('yaw', 0.0)) > 1e-6:
+        return []
+    px, py, pz = b['position']
+    sx, sy, sz = b['size']
+    out = []
+    rect = [(px - sx / 2, px + sx / 2), (py - sy / 2, py + sy / 2), (pz - sz / 2, pz + sz / 2)]
+    for axis in range(3):
+        for sign, plane in ((-1, rect[axis][0]), (1, rect[axis][1])):
+            out.append((axis, sign, plane, rect))
+    return out
+for i in range(len(boxes)):
+    for j in range(i + 1, len(boxes)):
+        for axis, sign, plane, rect in faces_of(boxes[i]):
+            for axis2, sign2, plane2, rect2 in faces_of(boxes[j]):
+                # Same plane AND same facing: two visible faces fighting. A wall standing on a floor
+                # (floor top against wall bottom) is a contact, not a fight.
+                if axis != axis2 or sign != sign2 or abs(plane - plane2) > 0.001:
+                    continue
+                overlap = all(min(rect[k][1], rect2[k][1]) - max(rect[k][0], rect2[k][0]) > 0.01 for k in range(3) if k != axis)
+                if overlap:
+                    warnings.append({'a': boxes[i]['name'], 'b': boxes[j]['name'], 'axis': 'xyz'[axis], 'plane': round(plane, 3)})
+                    break
+
+# ---------------------------------------------------------------- report
+
+failed = 0
+mode = 'doors closed' if DOORS_CLOSED else 'doors open'
+print(f'AUDIT {os.path.basename(LEVEL_PATH)} ({mode}): {len(level["colliders"])} colliders, {len(doors)} doors')
+for check, r in results.items():
+    n = len(r['failures'])
+    failed += n
+    print(f'  {check:18s} {r["checks"]:6d} rays  {n:4d} failed' + ('' if n == 0 else '   e.g. ' + json.dumps(r['failures'][0])))
+if not results:
+    print('  (no volumes, doors or links to audit — declare volume()/link() in the level script)')
+if warnings:
+    print(f'  coplanar_overlap   {len(warnings):4d} warning(s) — shared face planes, likely z-fighting: ' + ', '.join(f"{w['a']} / {w['b']}" for w in warnings[:6]))
+if JSON_OUT:
+    json.dump({'mode': mode, 'results': results, 'coplanar_warnings': warnings}, open(JSON_OUT, 'w'), indent=1)
+    print(f'  wrote {JSON_OUT}')
+print('AUDIT_RESULT ' + ('PASS' if failed == 0 else f'FAIL {failed}'))
+sys.exit(0 if failed == 0 else 1)