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

package/README.md

@@ -202,7 +202,7 @@ 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 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 **Cutscene clips** 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 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. |
@@ -215,6 +215,7 @@ browser reloads itself on every change and the assets panel shows each generatio
 | `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 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,16 @@ 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`.
+
 ## 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)

package/assets/blender-level/bmlevel/__init__.py

@@ -0,0 +1,294 @@
+"""bmlevel — write a low-poly game level as a short Python script, build it in Blender, and get
+one GLB plus the collider / door / light JSON the Bitmagic engine's `MeshLevel` loads.
+
+    from bmlevel import *
+    mat('stone', (0.5, 0.5, 0.48))
+    with context('hut', origin=(0, 0, 0)):
+        slab('floor', (0, 0), (8, 6), material='stone')
+        wall('north', (-4, -3), (4, -3), height=3, material='stone', opening={'at': 4, 'width': 1.4, 'height': 2.2})
+        door('front', (0, 0, -3), yaw=0)
+        spawn((0, 0.1, 0))
+    export('build/level', 'hut')
+
+Every position is in GAME coordinates (metres, Y up, +Z forward, yaw about +Y) inside the current
+`context()`; the Blender axis flip happens once, in the scene backend. Anything built with
+`solid=True` (the default) also becomes a collider record; `decor()` is the same call for things
+the player must never bump into. See core.py for the coordinate argument and the JSON shapes.
+"""
+from __future__ import annotations
+
+import contextlib
+import math
+import os
+import sys
+from typing import Sequence
+
+from bmlevel.core import (
+    BoxCollider, DoorRecord, Frame, HullCollider, Landmark, LevelData, Link, MaterialRecord,
+    PointLight, SpotLight, Stairs, Volume, box_corners, hex_color, prism_vertices, ramp_vertices,
+    require_convex_outline, rotate_xz,
+)
+
+try:  # inside Blender
+    import bpy  # noqa: F401
+    from bmlevel.scene_bpy import BpyScene as Scene
+except ImportError:  # plain python3: record only
+    from bmlevel.scene_null import NullScene as Scene
+
+__all__ = [
+    'mat', 'context', 'box', 'decor', 'prism', 'slab', 'wall', 'glazing', 'door', 'stairs', 'text',
+    'volume', 'link', 'lamp', 'spot', 'landmark', 'spawn', 'export', 'level', 'scene', 'reset', 'DRY_RUN',
+]
+
+DRY_RUN = '--dry-run' in sys.argv or not Scene.available
+
+level = LevelData()
+scene = Scene()
+_frames: list[Frame] = [Frame()]
+
+
+def reset() -> None:
+    """Start over (a script that builds several levels calls this between them)."""
+    global level
+    level = LevelData()
+    scene.reset()
+    _frames[:] = [Frame()]
+
+
+def _frame() -> Frame:
+    return _frames[-1]
+
+
+def _vec3(p: Sequence[float], what: str) -> tuple[float, float, float]:
+    if len(p) != 3:
+        raise ValueError(f'{what} must be (x, y, z), got {p!r}')
+    return (float(p[0]), float(p[1]), float(p[2]))
+
+
+# ---------------------------------------------------------------- materials
+
+def mat(name: str, rgb: Sequence[float], metal: float = 0.0, roughness: float = 0.5, glow: float = 0.0, alpha: float = 1.0) -> None:
+    """Declare a material. Name conventions the engine reads: `glass*` renders as a thin
+    transparent pane, `emissive*` is guaranteed to glow (glow > 0 also exports emission)."""
+    if len(rgb) != 3:
+        raise ValueError(f'mat({name!r}): rgb must be (r, g, b) in 0..1')
+    level.materials[name] = MaterialRecord(name, tuple(float(c) for c in rgb), metal, roughness, glow, alpha)
+    scene.material(name, rgb, metal, roughness, glow, alpha)
+
+
+# ---------------------------------------------------------------- frames
+
+@contextlib.contextmanager
+def context(name: str, origin: Sequence[float] = (0, 0, 0), yaw: float = 0.0):
+    """A named part of the level with its own local frame (a room, a module, a corridor). Objects
+    made inside land in a Blender collection of that name. Contexts nest."""
+    _frames.append(_frame().child(_vec3(origin, 'context origin'), yaw))
+    scene.begin_collection(name)
+    try:
+        yield
+    finally:
+        scene.end_collection()
+        _frames.pop()
+
+
+# ---------------------------------------------------------------- solids
+
+def box(name: str, pos: Sequence[float], size: Sequence[float], material: str, solid: bool = True, yaw: float = 0.0, bevel: float = 0.0, group: str | None = None) -> None:
+    """An oriented box: `pos` is its centre, `size` its full (width, height, depth) in metres."""
+    p = _frame().world(_vec3(pos, f'box {name!r} pos'))
+    s = _vec3(size, f'box {name!r} size')
+    if min(s) <= 0:
+        raise ValueError(f'box {name!r}: every size must be > 0')
+    w_yaw = _frame().yaw + yaw
+    scene.box(name, p, s, w_yaw, material, bevel)
+    if solid:
+        level.colliders.append(BoxCollider(name, p, s, w_yaw, group))
+    else:
+        level.visual_points.extend(box_corners(p, s, w_yaw))
+
+
+def decor(name: str, pos: Sequence[float], size: Sequence[float], material: str, yaw: float = 0.0, bevel: float = 0.0) -> None:
+    """A box the player never collides with: cladding, trim, lamps, fasteners, signage plates."""
+    box(name, pos, size, material, solid=False, yaw=yaw, bevel=bevel)
+
+
+def prism(name: str, outline: Sequence[tuple[float, float]], bottom: float, top: float, material: str, solid: bool = True, group: str | None = None) -> None:
+    """A polygon in local XZ extruded from `bottom` to `top`. Solid prisms must be convex (a
+    concave one raises — split it), because the collider is a convex hull."""
+    if top <= bottom:
+        raise ValueError(f'prism {name!r}: top must be above bottom')
+    if solid:
+        require_convex_outline(name, outline)
+    verts = prism_vertices(_frame(), outline, bottom, top)
+    scene.prism(name, verts, material)
+    if solid:
+        level.colliders.append(HullCollider(name, verts, group))
+    else:
+        level.visual_points.extend((verts[i], verts[i + 1], verts[i + 2]) for i in range(0, len(verts), 3))
+
+
+def slab(name: str, pos_xz: Sequence[float], size_xz: Sequence[float], material: str, y: float = 0.0, thickness: float = 0.5, yaw: float = 0.0) -> None:
+    """A floor or ceiling plate whose TOP surface is at `y`."""
+    box(name, (pos_xz[0], y - thickness / 2, pos_xz[1]), (size_xz[0], thickness, size_xz[1]), material, yaw=yaw)
+
+
+def wall(name: str, start: Sequence[float], end: Sequence[float], height: float, material: str, thickness: float = 0.3, base: float = 0.0, opening: dict | None = None) -> None:
+    """A wall from local (x, z) `start` to `end`. `opening={'at': m, 'width': w, 'height': h}` cuts
+    a doorway centred `at` metres from the start, leaving a lintel above it."""
+    (x0, z0), (x1, z1) = (float(start[0]), float(start[1])), (float(end[0]), float(end[1]))
+    length = math.hypot(x1 - x0, z1 - z0)
+    if length <= 0:
+        raise ValueError(f'wall {name!r}: start and end coincide')
+    yaw = math.atan2(x1 - x0, z1 - z0)  # local +Z along the wall at yaw 0
+
+    def segment(seg_name: str, t0: float, t1: float, seg_base: float, seg_top: float) -> None:
+        if t1 - t0 <= 1e-6 or seg_top - seg_base <= 1e-6:
+            return
+        tm = (t0 + t1) / 2
+        cx, cz = x0 + (x1 - x0) * tm / length, z0 + (z1 - z0) * tm / length
+        box(seg_name, (cx, (seg_base + seg_top) / 2, cz), (thickness, seg_top - seg_base, t1 - t0), material, yaw=yaw)
+
+    if opening is None:
+        segment(name, 0.0, length, base, base + height)
+        return
+    unknown = set(opening) - {'at', 'width', 'height'}
+    if unknown:
+        raise ValueError(f'wall {name!r}: opening keys must be at/width/height, got {sorted(unknown)}')
+    at, w, h = float(opening['at']), float(opening['width']), float(opening['height'])
+    if not (0 < at - w / 2 and at + w / 2 < length):
+        raise ValueError(f'wall {name!r}: opening {at}±{w / 2} falls outside the wall length {length:.2f}')
+    if h >= height:
+        raise ValueError(f'wall {name!r}: opening height {h} must be below the wall height {height}')
+    segment(f'{name} left', 0.0, at - w / 2, base, base + height)
+    segment(f'{name} right', at + w / 2, length, base, base + height)
+    segment(f'{name} lintel', at - w / 2, at + w / 2, base + h, base + height)
+
+
+def glazing(name: str, start: Sequence[float], end: Sequence[float], height: float, glass: str, frame: str, sill: float = 0.9, head: float = 0.4, base: float = 0.0, thickness: float = 0.3) -> None:
+    """A window wall: solid sill and head bands in `frame`, a thin pane in `glass` between them.
+    The pane is not a collider — the sill and head are, which is what stops the player."""
+    wall(f'{name} sill', start, end, sill, frame, thickness, base)
+    wall(f'{name} head', start, end, head, frame, thickness, base + height - head)
+    (x0, z0), (x1, z1) = start, end
+    cx, cz = (x0 + x1) / 2, (z0 + z1) / 2
+    yaw = math.atan2(x1 - x0, z1 - z0)
+    pane_h = height - sill - head
+    box(f'{name} pane', (cx, base + sill + pane_h / 2, cz), (0.04, pane_h, math.hypot(x1 - x0, z1 - z0)), glass, solid=False, yaw=yaw)
+    # An invisible-to-decor but solid pane keeps the player from walking through the glass.
+    level.colliders.append(BoxCollider(f'{name} pane collider', _frame().world((cx, base + sill + pane_h / 2, cz)), (max(0.1, thickness / 2), pane_h, math.hypot(x1 - x0, z1 - z0)), _frame().yaw + yaw))
+
+
+def door(id: str, pos: Sequence[float], yaw: float = 0.0, width: float = 1.4, height: float = 2.2, thickness: float = 0.1, kind: str = 'plain', animation: str = 'slide', jamb: str | None = None, jamb_depth: float = 0.3, auto_open_radius: float | None = None) -> None:
+    """A doorway: `pos` is the floor point at its centre, the leaf spans `width` across local X at
+    `yaw`. Writes a `DoorDefinition` for world.json (the engine builds and animates the leaf) and,
+    when `jamb` names a material, solid jambs and a header around it."""
+    if kind not in ('plain', 'locked') or animation not in ('hinge', 'slide', 'dissolve'):
+        raise ValueError(f'door {id!r}: kind is plain|locked, animation is hinge|slide|dissolve')
+    p = _vec3(pos, f'door {id!r} pos')
+    w_yaw = _frame().yaw + yaw
+    centre = _frame().world((p[0], p[1] + height / 2, p[2]))
+    level.doors.append(DoorRecord(id, centre, w_yaw, width, height, thickness, kind, animation, auto_open_radius))
+    if jamb:
+        for side in (-1, 1):
+            ox, oz = rotate_xz(side * (width / 2 + 0.08), 0.0, yaw)  # the jambs sit across the leaf, whatever the door's yaw
+            box(f'{id} jamb {"L" if side < 0 else "R"}', (p[0] + ox, p[1] + height / 2 + 0.1, p[2] + oz), (0.16, height + 0.2, jamb_depth), jamb, yaw=yaw)
+        # The header is a little deeper and taller than the jambs, so no two faces share a plane.
+        box(f'{id} header', (p[0], p[1] + height + 0.15, p[2]), (width + 0.36, 0.3, jamb_depth + 0.04), jamb, yaw=yaw)
+
+
+def stairs(name: str, foot: Sequence[float], rise: float, run: float, material: str, width: float = 2.0, yaw: float = 0.0, steps: int | None = None, rail: str | None = None, treads_solid: bool = False) -> None:
+    """A straight flight climbing `rise` over `run` along local +Z from `foot` (the bottom edge's
+    centre, at floor level). Visual treads, one smooth ramp collider (so walking up is not a
+    stutter), optional rails in `rail`. `treads_solid=True` makes every tread a collider too."""
+    f = _vec3(foot, f'stairs {name!r} foot')
+    n = steps or max(2, math.ceil(rise / 0.18))
+    tread, riser = run / n, rise / n
+    for i in range(n):
+        top = f[1] + (i + 1) * riser
+        box(f'{name} tread {i:02d}', (f[0], (f[1] + top) / 2, f[2] + (i + 0.5) * tread), (width, top - f[1], tread), material, solid=treads_solid, yaw=yaw)
+    frame = _frame().child((0, 0, 0), yaw) if yaw else _frame()
+    level.colliders.append(HullCollider(f'{name} ramp', ramp_vertices(frame, f, width, rise, run)))
+    if rail:
+        for side in (-1, 1):
+            x = f[0] + side * (width / 2 + 0.05)
+            pts = []
+            for z, y in ((f[2], f[1]), (f[2] + run, f[1] + rise)):
+                for dy in (0.85, 0.95):
+                    for dx in (-0.03, 0.03):
+                        pts.extend(frame.world((x + dx, y + dy, z)))
+            level.colliders.append(HullCollider(f'{name} rail {"L" if side < 0 else "R"}', pts))
+            scene.hull(f'{name} rail {"L" if side < 0 else "R"}', pts, rail)
+            for i in range(0, n, max(1, n // 3)):
+                box(f'{name} post {"L" if side < 0 else "R"} {i}', (x, f[1] + (i + 1) * riser + 0.45, f[2] + (i + 0.5) * tread), (0.06, 0.9, 0.06), rail, solid=False, yaw=yaw)
+    level.stairs.append(Stairs(name, _frame().world(f), frame.world((f[0], f[1] + rise, f[2] + run))))
+
+
+def text(name: str, string: str, pos: Sequence[float], material: str, yaw: float = 0.0, size: float = 0.5, extrude: float = 0.01, both_faces: bool = False) -> None:
+    """3D signage, readable from local -Z at yaw 0 (facing an approaching player). Blender's
+    bundled font, no font file. `both_faces` adds a mirrored copy for the other approach."""
+    p = _frame().world(_vec3(pos, f'text {name!r} pos'))
+    scene.text(name, string, p, _frame().yaw + yaw, size, material, extrude, both_faces)
+    level.visual_points.append(p)
+
+
+# ---------------------------------------------------------------- data only
+
+def volume(name: str, pos: Sequence[float], size: Sequence[float], yaw: float = 0.0, tags: Sequence[str] = (), roofed: bool = True) -> None:
+    """A named region (a room, an airlock, a trigger area): `pos` is its centre. The audit checks
+    floor continuity inside it and, when `roofed`, a sealed envelope. Tags reach the game."""
+    p = _frame().world(_vec3(pos, f'volume {name!r} pos'))
+    t = [str(x) for x in tags]
+    if not roofed:
+        t.append('unroofed')
+    level.volumes.append(Volume(name, p, _vec3(size, f'volume {name!r} size'), _frame().yaw + yaw, t))
+
+
+def link(a: str, b: str, door: str | None = None) -> None:
+    """Declare that a player can walk from volume `a` to volume `b` (through `door`, if named).
+    The audit marches the route with a player-sized capsule."""
+    level.links.append(Link(a, b, door))
+
+
+def lamp(name: str, pos: Sequence[float], color, intensity: float = 8.0, distance: float = 20.0, decay: float = 2.0) -> None:
+    """A point light. Point lights share a small pool in the engine — place them where it matters."""
+    level.lights.append(PointLight(name, _frame().world(_vec3(pos, f'lamp {name!r} pos')), hex_color(color), intensity, distance, decay))
+
+
+def spot(name: str, pos: Sequence[float], target: Sequence[float], color, intensity: float = 20.0, angle: float = math.pi / 4, penumbra: float = 0.3, cast_shadow: bool = True) -> None:
+    """A spot light; the first two with `cast_shadow` bake shadows from the static level."""
+    level.lights.append(SpotLight(name, _frame().world(_vec3(pos, f'spot {name!r} pos')), _frame().world(_vec3(target, f'spot {name!r} target')), hex_color(color), intensity, angle, penumbra, cast_shadow))
+
+
+def landmark(name: str, pos: Sequence[float], yaw: float = 0.0, tags: Sequence[str] = ()) -> None:
+    """A named point the game asks for by name (`level.landmark('exit')`, `landmarksTagged('guard')`)."""
+    level.landmarks.append(Landmark(name, _frame().world(_vec3(pos, f'landmark {name!r} pos')), _frame().yaw + yaw, [str(t) for t in tags]))
+
+
+def spawn(pos: Sequence[float], yaw: float = 0.0) -> None:
+    """Where the player starts: the `spawn` landmark, which sync_world.py also writes into world.json."""
+    landmark('spawn', pos, yaw)
+
+
+# ---------------------------------------------------------------- output
+
+def export(out_dir: str, name: str) -> dict:
+    """Write `<name>.mesh-level.json`, `<name>.doors.json`, `<name>.blend` (named parts, editable)
+    and `<name>.glb` (joined per material) into `out_dir`, and print the summary — including the
+    exact `bitmagic assets add` line, whose `--height` must be the level's native height."""
+    for l in level.links:
+        names = {v.name for v in level.volumes}
+        for end in (l.a, l.b):
+            if end not in names:
+                raise ValueError(f'link({l.a!r}, {l.b!r}): no volume named {end!r}')
+        if l.door and l.door not in {d.id for d in level.doors}:
+            raise ValueError(f'link({l.a!r}, {l.b!r}, door={l.door!r}): no door with that id')
+    level_path, doors_path = level.write(out_dir, name)
+    glb_path = os.path.join(out_dir, f'{name}.glb')
+    blend_path = os.path.join(out_dir, f'{name}.blend')
+    size = 0
+    if not DRY_RUN:
+        scene.save_blend(blend_path)
+        size = scene.export_glb(glb_path)
+    print(level.summary(name, glb_path), flush=True)
+    print(f'WROTE {level_path} {doors_path}' + ('' if DRY_RUN else f' {blend_path} {glb_path} ({size} bytes)'), flush=True)
+    return {'level': level_path, 'doors': doors_path, 'glb': glb_path, 'blend': blend_path, 'dry_run': DRY_RUN}