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

package/assets/blender-level/example_level.py

@@ -0,0 +1,80 @@
+"""A complete small level — a two-room hut with a porch and a walled courtyard — exercising every
+bmlevel helper once. It is the reference a level script starts from, and the fixture the tests
+run through the null backend.
+
+    "$BLENDER" -b --python tools/blender-level/example_level.py -- --out build/level
+    python3 tools/blender-level/example_level.py --dry-run          # counts and JSON only
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from bmlevel import (  # noqa: E402
+    box, context, decor, door, export, glazing, lamp, landmark, link, mat, prism, slab, spawn, spot, stairs, text, volume, wall,
+)
+
+
+def build() -> None:
+    mat('plaster', (0.82, 0.78, 0.7))
+    mat('timber', (0.45, 0.3, 0.16), roughness=0.7)
+    mat('stone', (0.42, 0.42, 0.4), roughness=0.9)
+    mat('deck', (0.3, 0.25, 0.18), roughness=0.8)
+    mat('glass_pane', (0.55, 0.75, 0.9), alpha=0.25)
+    mat('emissive_lamp', (1.0, 0.85, 0.55), glow=4.0)
+    mat('brass', (0.75, 0.6, 0.3), metal=0.8, roughness=0.35)
+
+    with context('hut', origin=(0, 0, 0)):
+        # Two rooms, 8 x 6 m and 5 x 6 m, sharing an internal wall with a doorway.
+        slab('hut floor', (2.5, 0), (13, 6), 'deck', y=0.0, thickness=0.4)
+        slab('hut ceiling', (2.5, 0), (13, 6), 'timber', y=3.2, thickness=0.2)
+        wall('west', (-4, -3), (-4, 3), 3.0, 'plaster')
+        wall('east', (9, -3), (9, 3), 3.0, 'plaster')
+        wall('south', (-4, 3), (9, 3), 3.0, 'plaster')
+        wall('north', (-4, -3), (9, -3), 3.0, 'plaster', opening={'at': 4, 'width': 1.4, 'height': 2.2})
+        door('front', (0, 0, -3), yaw=0, jamb='timber')
+        wall('partition', (4, -3), (4, 3), 3.0, 'plaster', opening={'at': 3, 'width': 1.2, 'height': 2.1})
+        door('inner', (4, 0, 0), yaw=1.5707963, width=1.2, height=2.1, animation='hinge', jamb='timber')
+        glazing('south window', (5, 3.01), (8, 3.01), 3.0, 'glass_pane', 'plaster', thickness=0.28)
+        box('table', (-2.2, 0.4, 1.6), (1.6, 0.8, 0.9), 'timber', group='environment', bevel=0.02)  # off the walk line: the audit marches room centre to door
+        decor('rug', (0, 0.006, 0.5), (3, 0.012, 2.4), 'stone')
+        decor('lamp shade', (0, 2.9, 0), (0.5, 0.15, 0.5), 'emissive_lamp')
+        lamp('hut lamp', (0, 2.7, 0), '#ffd9a0', intensity=10, distance=12)
+        lamp('back room lamp', (6.5, 2.7, 0), '#ffe0b0', intensity=8, distance=10)
+        text('sign', 'HUT', (0, 2.55, -3.2), 'brass', size=0.35, both_faces=True)
+        volume('front room', (0, 1.6, 0), (8, 3.2, 6), tags=['indoors'])
+        volume('back room', (6.5, 1.6, 0), (5, 3.2, 6), tags=['indoors'])
+        link('front room', 'back room', door='inner')
+        landmark('table', (-2.2, 0.8, 1.6), tags=['prop'])
+
+    with context('porch', origin=(0, 0, -3)):
+        # Porch deck 1.2 m below the hut floor, four steps up to the door.
+        slab('porch deck', (0, -4.5), (6, 3), 'deck', y=-1.2, thickness=0.3)
+        stairs('porch steps', (0, -1.2, -3.05), rise=1.2, run=3.05, material='stone', width=2.0, rail='brass')  # overlaps the hut floor edge by 5 cm: abutting edges leave a seam
+        # A mitred corner piece: a convex prism, the way angled junctions are built.
+        prism('porch corner', [(-3, -3), (-3, -6), (-4.5, -6)], -1.5, -0.9, 'stone')
+        spot('porch spot', (0, 2.8, -4.5), (0, 0, -1.5), '#cfe6ff', intensity=18)
+        volume('porch', (0, -0.3, -4.5), (6, 2.6, 3), roofed=False)
+        link('porch', 'front room', door='front')
+
+    with context('courtyard', origin=(0, -1.2, -15)):  # starts where the porch deck ends (z = -9), no overlapping slabs
+        slab('courtyard ground', (0, 0), (16, 12), 'stone', y=0.0, thickness=0.4)
+        for name, a, b in (('yard west', (-8, -6), (-8, 6)), ('yard east', (8, -6), (8, 6)), ('yard south', (-8, -6), (8, -6))):
+            wall(name, a, b, 1.2, 'stone', thickness=0.4)
+        box('well', (5, 0.5, -2), (1.4, 1.0, 1.4), 'stone', group='environment', bevel=0.05)
+        lamp('yard lamp', (-4, 2.5, 0), '#ffffff', intensity=6, distance=16)
+        volume('courtyard', (0, 1.0, 0), (16, 2.0, 12), roofed=False)
+        link('courtyard', 'porch')
+        landmark('well', (5, 1.0, -2), tags=['prop'])
+        landmark('guard post', (-5, 0.1, 3), yaw=0.0, tags=['guard'])
+        spawn((0, 0.1, 4), yaw=3.14159)
+
+
+def main() -> None:
+    argv = sys.argv[sys.argv.index('--') + 1:] if '--' in sys.argv else sys.argv[1:]
+    out = argv[argv.index('--out') + 1] if '--out' in argv else 'build/level'
+    build()
+    export(out, 'hut')
+
+
+if __name__ == '__main__':
+    main()

package/assets/blender-level/find_blender.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Print the Blender executable to use, or say how to install one and exit 1.
+
+    BLENDER="$(python3 tools/blender-level/find_blender.py)"
+    python3 tools/blender-level/find_blender.py --check     # also runs `blender -b --version`
+
+Order: $BLENDER, `blender` on PATH, the macOS app bundle, the Windows install directory.
+"""
+import glob
+import os
+import shutil
+import subprocess
+import sys
+
+CANDIDATES = [
+    '/Applications/Blender.app/Contents/MacOS/Blender',
+    os.path.expanduser('~/Applications/Blender.app/Contents/MacOS/Blender'),
+    '/usr/bin/blender',
+    '/snap/bin/blender',
+]
+INSTALL_HINT = (
+    'Blender was not found. `building-levels-in-blender` builds the level with it — install it '
+    '(macOS: brew install --cask blender · Debian/Ubuntu: sudo apt install blender · '
+    'Windows: winget install BlenderFoundation.Blender) and set BLENDER=<path> if it lives somewhere else.'
+)
+
+
+def find_blender() -> str | None:
+    env = os.environ.get('BLENDER')
+    if env and os.path.isfile(env):
+        return env
+    on_path = shutil.which('blender')
+    if on_path:
+        return on_path
+    for c in CANDIDATES:
+        if os.path.isfile(c):
+            return c
+    for pattern in ('C:/Program Files/Blender Foundation/Blender*/blender.exe',):
+        hits = sorted(glob.glob(pattern))
+        if hits:
+            return hits[-1]
+    return None
+
+
+def main() -> int:
+    path = find_blender()
+    if not path:
+        print(INSTALL_HINT, file=sys.stderr)
+        return 1
+    if '--check' in sys.argv:
+        probe = subprocess.run([path, '-b', '--version'], capture_output=True, text=True)
+        if probe.returncode != 0:
+            print(f'{path} exists but `-b --version` failed:\n{probe.stderr.strip()}', file=sys.stderr)
+            return 1
+        version = next((line for line in probe.stdout.splitlines() if line.startswith('Blender')), '').strip()
+        print(f'{version} at {path}', file=sys.stderr)
+    print(path)
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/assets/blender-level/review.py

@@ -0,0 +1,117 @@
+"""Headless review renders of a built level, run inside Blender:
+
+    "$BLENDER" -b --python tools/blender-level/review.py -- build/level/hut.blend build/level/hut.mesh-level.json build/level/review/
+
+Opens the .blend (named parts intact) and renders a deterministic set of shots from the level
+JSON — `overview` (top-down), `door-<id>-a/b` (both approaches of every door), `stairs-<name>`
+(from the foot), `volume-<name>` (inside every room) — into the output directory, plus
+`contact-sheet.png` with all of them. Read the sheet, then the shots that look wrong.
+
+EEVEE, 960 x 540, a camera-mounted fill light so interiors are legible whatever the JSON lights
+say. This is a look at the geometry, not the game's lighting — `bitmagic verify` shows that.
+"""
+import json
+import math
+import os
+import sys
+
+import bpy
+from mathutils import Vector
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from bmlevel.core import review_cameras, to_blender  # noqa: E402
+
+argv = sys.argv[sys.argv.index('--') + 1:] if '--' in sys.argv else sys.argv[1:]
+if len(argv) < 3:
+    print(__doc__)
+    sys.exit(2)
+BLEND, LEVEL_PATH, OUT = argv[0], argv[1], argv[2]
+WIDTH, HEIGHT = 960, 540
+
+level = json.load(open(LEVEL_PATH))
+doors_path = LEVEL_PATH.replace('.mesh-level.json', '.doors.json')
+doors = json.load(open(doors_path)) if os.path.exists(doors_path) else []
+os.makedirs(OUT, exist_ok=True)
+
+bpy.ops.wm.open_mainfile(filepath=os.path.abspath(BLEND))
+scene = bpy.context.scene
+engines = [e.identifier for e in bpy.types.RenderSettings.bl_rna.properties['engine'].enum_items]
+scene.render.engine = 'BLENDER_EEVEE_NEXT' if 'BLENDER_EEVEE_NEXT' in engines else 'BLENDER_EEVEE'
+if hasattr(scene, 'eevee'):
+    scene.eevee.taa_render_samples = 16
+scene.render.resolution_x, scene.render.resolution_y = WIDTH, HEIGHT
+scene.render.resolution_percentage = 100
+scene.render.image_settings.file_format = 'PNG'
+if scene.world is None:
+    scene.world = bpy.data.worlds.new('review')
+scene.world.use_nodes = True
+bg = scene.world.node_tree.nodes['Background']
+bg.inputs[0].default_value = (0.35, 0.4, 0.5, 1)
+bg.inputs[1].default_value = 0.6
+
+cam_data = bpy.data.cameras.new('review')
+cam = bpy.data.objects.new('review', cam_data)
+scene.collection.objects.link(cam)
+scene.camera = cam
+fill_data = bpy.data.lights.new('review-fill', 'POINT')
+fill_data.energy = 400
+fill_data.shadow_soft_size = 2
+fill = bpy.data.objects.new('review-fill', fill_data)
+scene.collection.objects.link(fill)
+sun_data = bpy.data.lights.new('review-sun', 'SUN')
+sun_data.energy = 2.5
+sun = bpy.data.objects.new('review-sun', sun_data)
+scene.collection.objects.link(sun)
+sun.rotation_euler = (math.radians(50), math.radians(15), math.radians(30))
+
+
+def render(shot: dict) -> str:
+    pos = Vector(to_blender(shot['position']))
+    target = Vector(to_blender(shot['target']))
+    cam.location = pos
+    cam.rotation_euler = (target - pos).to_track_quat('-Z', 'Y').to_euler()
+    if shot['kind'] == 'ortho':
+        cam_data.type = 'ORTHO'
+        sx, sz = shot['extent']
+        cam_data.ortho_scale = max(sx, sz * WIDTH / HEIGHT) * 1.15  # fit both axes into a 16:9 frame
+        fill.hide_render = True
+    else:
+        cam_data.type = 'PERSP'
+        cam_data.lens = 24
+        fill.hide_render = False
+        fill.location = pos + Vector((0, 0, 0.6))
+    path = os.path.join(OUT, f"{shot['name']}.png")
+    scene.render.filepath = path
+    bpy.ops.render.render(write_still=True)
+    return path
+
+
+shots = review_cameras(level, doors)
+paths = [render(s) for s in shots]
+for s, p in zip(shots, paths):
+    print(f'SHOT {s["name"]} -> {p}')
+
+# Contact sheet: every shot at half size, four per row, labelled by file name in the log.
+import numpy as np  # Blender bundles numpy  # noqa: E402
+
+cols = 4
+thumb_w, thumb_h = WIDTH // 2, HEIGHT // 2
+rows = math.ceil(len(paths) / cols)
+sheet = np.zeros((rows * thumb_h, cols * thumb_w, 4), dtype=np.float32)
+sheet[..., 3] = 1
+for i, p in enumerate(paths):
+    img = bpy.data.images.load(p)
+    px = np.array(img.pixels[:], dtype=np.float32).reshape(img.size[1], img.size[0], 4)
+    small = px[::2, ::2][:thumb_h, :thumb_w]
+    r, c = divmod(i, cols)
+    y0 = (rows - 1 - r) * thumb_h  # Blender image rows run bottom-up
+    sheet[y0:y0 + small.shape[0], c * thumb_w:c * thumb_w + small.shape[1]] = small
+    bpy.data.images.remove(img)
+out_img = bpy.data.images.new('contact', cols * thumb_w, rows * thumb_h, alpha=True)
+out_img.pixels = sheet.ravel().tolist()
+sheet_path = os.path.join(OUT, 'contact-sheet.png')
+out_img.filepath_raw = sheet_path
+out_img.file_format = 'PNG'
+out_img.save()
+order = ', '.join(f'{i + 1}:{s["name"]}' for i, s in enumerate(shots))
+print(f'CONTACT_SHEET {sheet_path} ({cols} per row, left to right, top to bottom: {order})')

package/assets/blender-level/sync_world.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Carry a built level's doors and spawn into the game's world.json.
+
+    python3 tools/blender-level/sync_world.py build/level/hut.doors.json build/level/hut.mesh-level.json src/work/world.json
+        [--level-id <id>] [--keep-spawn] [--keep-terrain]
+
+- doors: upserts `worldProfileData.doors[]` by id. The build owns the geometry fields (position,
+  rotationY, width, height, thickness) and the animation; creator-owned fields on an existing
+  entry — kind, keyId, assetId, color, autoOpenRadius, maxOpenAngleDeg — survive unless the
+  build sets them. Doors in world.json that the build no longer has are reported, never deleted.
+- spawn: the `spawn` landmark becomes playerSpawnPosition / playerSpawnRotation (skip: --keep-spawn).
+- terrain: sets `terrain.shape` to 'none' so no voxel ground is built under the level (skip:
+  --keep-terrain).
+
+A script rather than jq because the merge rule IS the point.
+"""
+import json
+import sys
+
+BUILD_OWNED = ('position', 'rotationY', 'width', 'height', 'thickness', 'animation')
+
+
+def merge_doors(existing: list, built: list, level_id: str | None) -> tuple[list, dict]:
+    by_id = {d['id']: dict(d) for d in existing}
+    added, updated = [], []
+    for door in built:
+        entry = by_id.get(door['id'])
+        if entry is None:
+            entry = dict(door)
+            added.append(door['id'])
+        else:
+            for key in BUILD_OWNED:
+                entry[key] = door[key]
+            for key in ('kind', 'autoOpenRadius'):
+                if key in door and key not in entry:
+                    entry[key] = door[key]
+            updated.append(door['id'])
+        if level_id:
+            entry['levelId'] = level_id
+        by_id[door['id']] = entry
+    built_ids = {d['id'] for d in built}
+    orphans = [d['id'] for d in existing if d['id'] not in built_ids]
+    return list(by_id.values()), {'added': added, 'updated': updated, 'orphans': orphans}
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 3:
+        print(__doc__, file=sys.stderr)
+        return 2
+    doors_path, level_path, world_path = argv[:3]
+    level_id = argv[argv.index('--level-id') + 1] if '--level-id' in argv else None
+    with open(doors_path) as f:
+        built_doors = json.load(f)
+    with open(level_path) as f:
+        level = json.load(f)
+    with open(world_path) as f:
+        world = json.load(f)
+    profile = world.setdefault('worldProfileData', {})
+
+    profile['doors'], report = merge_doors(profile.get('doors', []), built_doors, level_id)
+    print(f"doors: {len(report['added'])} added, {len(report['updated'])} updated" + (f", not in this build: {', '.join(report['orphans'])}" if report['orphans'] else ''))
+
+    spawn = next((l for l in level.get('landmarks', []) if l['name'] == 'spawn'), None)
+    if spawn and '--keep-spawn' not in argv:
+        x, y, z = spawn['position']
+        profile['playerSpawnPosition'] = {'x': x, 'y': y, 'z': z}
+        profile['playerSpawnRotation'] = spawn.get('yaw', 0.0)
+        print(f'spawn: playerSpawnPosition ({x}, {y}, {z}) yaw {spawn.get("yaw", 0.0)}')
+    elif not spawn:
+        print('spawn: no `spawn` landmark in the level — playerSpawnPosition left as is')
+
+    if '--keep-terrain' not in argv:
+        terrain = profile.setdefault('terrain', {})
+        if terrain.get('shape') != 'none':
+            terrain['shape'] = 'none'
+            print("terrain: shape set to 'none' (no voxel ground under the level)")
+
+    with open(world_path, 'w') as f:
+        json.dump(world, f, indent=2)
+        f.write('\n')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))

package/assets/blender-level/tests/test_core.py

@@ -0,0 +1,189 @@
+"""Blender-free checks of bmlevel: `python3 -m unittest discover -s tools/blender-level/tests`.
+
+Runs the example level through the null backend and checks the invariants the engine relies on:
+the axis round trip, collider records that match what was built, the door records' shape
+(exactly the engine's DoorDefinition), the JSON the exporter writes, review cameras, and the
+world.json merge.
+"""
+import importlib
+import json
+import math
+import os
+import sys
+import tempfile
+import unittest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(HERE)
+sys.path.insert(0, ROOT)
+
+from bmlevel import core  # noqa: E402
+
+
+def fresh_bmlevel():
+    import bmlevel
+    bmlevel.reset()
+    return bmlevel
+
+
+class CoordinateTests(unittest.TestCase):
+    def test_axis_round_trip(self):
+        for p in ((1, 2, 3), (-4.5, 0, 9), (0, -1, 0)):
+            self.assertEqual(core.from_blender(core.to_blender(p)), tuple(float(v) for v in p))
+
+    def test_forward_at_yaw_matches_the_engine_convention(self):
+        x, z = core.rotate_xz(0, 1, math.pi / 2)
+        self.assertAlmostEqual(x, 1.0)
+        self.assertAlmostEqual(z, 0.0)
+
+    def test_frames_compose(self):
+        outer = core.Frame((10, 0, 0), math.pi / 2)
+        inner = outer.child((0, 0, 2), 0.0)
+        wx, wy, wz = inner.world((0, 1, 0))
+        self.assertAlmostEqual(wx, 12.0)
+        self.assertAlmostEqual(wy, 1.0)
+        self.assertAlmostEqual(wz, 0.0)
+
+    def test_box_corners_rotate(self):
+        corners = core.box_corners((0, 0, 0), (2, 2, 4), math.pi / 2)
+        xs = sorted(round(c[0], 6) for c in corners)
+        self.assertEqual(xs[0], -2.0)
+        self.assertEqual(xs[-1], 2.0)
+
+    def test_concave_outline_is_rejected(self):
+        with self.assertRaises(ValueError):
+            core.require_convex_outline('L', [(0, 0), (2, 0), (2, 1), (1, 1), (1, 2), (0, 2)])
+        core.require_convex_outline('tri', [(0, 0), (2, 0), (1, 2)])
+
+    def test_hex_color(self):
+        self.assertEqual(core.hex_color((1, 0.5, 0)), '#ff8000')
+        self.assertEqual(core.hex_color('#ABCDEF'), '#abcdef')
+        with self.assertRaises(ValueError):
+            core.hex_color('red')
+
+
+class ExampleLevelTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.bm = fresh_bmlevel()
+        example = importlib.import_module('example_level')
+        example.build()
+        cls.level = cls.bm.level
+        cls.out = tempfile.mkdtemp()
+        cls.paths = cls.bm.export(cls.out, 'hut')
+        with open(cls.paths['level']) as f:
+            cls.level_json = json.load(f)
+        with open(cls.paths['doors']) as f:
+            cls.doors_json = json.load(f)
+
+    def test_counts(self):
+        self.assertEqual(len(self.level.doors), 2)
+        self.assertEqual(len(self.level.volumes), 4)
+        self.assertEqual(len(self.level.links), 3)
+        self.assertGreater(len(self.level.colliders), 20)
+        self.assertTrue(any(l.name == 'spawn' for l in self.level.landmarks))
+
+    def test_solid_boxes_become_colliders_and_decor_does_not(self):
+        names = {c.name for c in self.level.colliders}
+        self.assertIn('table', names)
+        self.assertIn('west', names)
+        self.assertNotIn('rug', names)
+        self.assertNotIn('lamp shade', names)
+        for c in self.level.colliders:
+            if c.name == 'table':
+                self.assertEqual(c.group, 'environment')
+
+    def test_stairs_emit_a_ramp_hull_and_rails(self):
+        hulls = {c.name for c in self.level.colliders if isinstance(c, core.HullCollider)}
+        self.assertIn('porch steps ramp', hulls)
+        self.assertIn('porch steps rail L', hulls)
+        self.assertEqual(len(self.level.stairs), 1)
+
+    def test_door_records_are_door_definitions(self):
+        for d in self.doors_json:
+            self.assertEqual(set(d), {'id', 'position', 'rotationY', 'width', 'height', 'thickness', 'kind', 'animation'})
+            self.assertEqual(set(d['position']), {'x', 'y', 'z'})
+        inner = next(d for d in self.doors_json if d['id'] == 'inner')
+        self.assertAlmostEqual(inner['rotationY'], 1.5707963)
+        self.assertEqual(inner['animation'], 'hinge')
+
+    def test_yawed_door_jambs_flank_the_opening(self):
+        jambs = [c for c in self.level.colliders if c.name.startswith('inner jamb')]
+        self.assertEqual(len(jambs), 2)
+        zs = sorted(c.position[2] for c in jambs)
+        self.assertLess(zs[0], -0.6)
+        self.assertGreater(zs[1], 0.6)
+        for c in jambs:
+            self.assertAlmostEqual(c.position[0], 4.0)
+
+    def test_mesh_level_json_shape(self):
+        j = self.level_json
+        self.assertEqual(j['format'], core.MESH_LEVEL_FORMAT)
+        self.assertEqual(j['version'], core.MESH_LEVEL_VERSION)
+        self.assertEqual(j['units'], 'meters')
+        self.assertEqual(set(j), {'format', 'version', 'units', 'colliders', 'volumes', 'landmarks', 'lights', 'extras'})
+        for c in j['colliders']:
+            self.assertIn(c['shape'], ('box', 'convexHull'))
+            if c['shape'] == 'convexHull':
+                self.assertEqual(len(c['vertices']) % 3, 0)
+                self.assertGreaterEqual(len(c['vertices']), 12)
+        self.assertEqual(len(j['extras']['links']), 3)
+        self.assertIn('unroofed', next(v for v in j['volumes'] if v['name'] == 'porch')['tags'])
+        spot = next(l for l in j['lights'] if l['type'] == 'spot')
+        self.assertEqual(set(spot), {'name', 'type', 'position', 'target', 'color', 'intensity', 'angle', 'penumbra', 'castShadow'})
+
+    def test_native_height_and_summary(self):
+        self.assertAlmostEqual(self.level.native_height(), 4.8, places=2)
+        summary = self.level.summary('hut', 'build/level/hut.glb')
+        self.assertIn('--keep-glb --asset-id level-hut --height 4.8', summary)
+
+    def test_review_cameras(self):
+        shots = core.review_cameras(self.level_json, self.doors_json)
+        names = [s['name'] for s in shots]
+        self.assertEqual(names[0], 'overview')
+        self.assertIn('door-front-a', names)
+        self.assertIn('door-inner-b', names)
+        self.assertIn('stairs-porch steps', names)
+        self.assertEqual(sum(1 for n in names if n.startswith('volume-')), 4)
+
+    def test_duplicate_names_are_refused(self):
+        bm = fresh_bmlevel()
+        bm.mat('m', (1, 1, 1))
+        bm.box('twice', (0, 0, 0), (1, 1, 1), 'm')
+        bm.box('twice', (3, 0, 0), (1, 1, 1), 'm')
+        with self.assertRaises(ValueError):
+            bm.level.mesh_level_json()
+
+    def test_link_to_unknown_volume_is_refused_at_export(self):
+        bm = fresh_bmlevel()
+        bm.mat('m', (1, 1, 1))
+        bm.volume('a', (0, 1, 0), (2, 2, 2))
+        bm.link('a', 'nowhere')
+        with self.assertRaises(ValueError):
+            bm.export(tempfile.mkdtemp(), 'x')
+
+
+class SyncWorldTests(unittest.TestCase):
+    def test_merge_keeps_creator_fields_and_reports_orphans(self):
+        sync = importlib.import_module('sync_world')
+        existing = [
+            {'id': 'front', 'position': {'x': 0, 'y': 0, 'z': 0}, 'rotationY': 0, 'width': 1, 'height': 2, 'thickness': 0.1, 'kind': 'locked', 'keyId': 'brass', 'animation': 'slide', 'color': '#123456'},
+            {'id': 'gone', 'position': {'x': 9, 'y': 0, 'z': 0}, 'rotationY': 0, 'width': 1, 'height': 2, 'thickness': 0.1, 'kind': 'plain', 'animation': 'slide'},
+        ]
+        built = [
+            {'id': 'front', 'position': {'x': 1, 'y': 1.1, 'z': -3}, 'rotationY': 0.5, 'width': 1.4, 'height': 2.2, 'thickness': 0.1, 'kind': 'plain', 'animation': 'hinge'},
+            {'id': 'new', 'position': {'x': 4, 'y': 1, 'z': 0}, 'rotationY': 0, 'width': 1.2, 'height': 2, 'thickness': 0.1, 'kind': 'plain', 'animation': 'slide'},
+        ]
+        merged, report = sync.merge_doors(existing, built, None)
+        front = next(d for d in merged if d['id'] == 'front')
+        self.assertEqual(front['kind'], 'locked')
+        self.assertEqual(front['keyId'], 'brass')
+        self.assertEqual(front['color'], '#123456')
+        self.assertEqual(front['position'], {'x': 1, 'y': 1.1, 'z': -3})
+        self.assertEqual(front['animation'], 'hinge')
+        self.assertEqual(report, {'added': ['new'], 'updated': ['front'], 'orphans': ['gone']})
+        self.assertEqual({d['id'] for d in merged}, {'front', 'gone', 'new'})
+
+
+if __name__ == '__main__':
+    unittest.main()

package/dist/editor/asset-detail-panel.d.ts

@@ -16,12 +16,17 @@
  * The surface, the pills and the modal backdrop come from `design.ts` (`.bm-overlay`,
  * `.bm-dialog`, `.bm-pill`); only what is specific to this dialog's layout lives here.
  */
-export declare const ASSET_DETAIL_CSS = "\n  /* Above #hq-overlay, which sits at 10 \u2014 a preview opened from a row must cover it. */\n  #asset-overlay { z-index: 11; }\n  #asset-dialog { display: flex; width: min(1100px, 94vw); height: min(760px, 88vh);\n                  overflow: hidden; }\n  /* The viewer takes the room. Everything else is a caption. The near-black ground is the\n     brand's: a creation is the only thing on this surface that carries colour. */\n  #asset-view { flex: 1; min-width: 0; position: relative; background: var(--bm-bg); }\n  #asset-view iframe { display: block; width: 100%; height: 100%; border: 0; }\n  #asset-view img { display: block; width: 100%; height: 100%; object-fit: contain;\n                    background: var(--bm-bg); }\n  #asset-view audio { position: absolute; left: 50%; top: 50%; width: min(420px, 80%);\n                      transform: translate(-50%, -50%); }\n  /* A note here is always a failure or a wait that has gone on too long \u2014 the negative accent. */\n  #asset-note { position: absolute; inset: auto 0 0 0; padding: 10px 12px;\n                background: var(--bm-scrim); color: var(--bm-pink-hover); font-size: 12px; }\n  #asset-note.hidden, #asset-view > .hidden { display: none; }\n  /* Wide enough for the action pills to sit on one row (wrapping to two once Edit voxels shows):\n     uppercase tracked labels are wider than the sentence-case ones this panel used to have. */\n  #asset-meta { width: 360px; flex: none; padding: 16px; overflow-y: auto;\n                border-left: 1px solid var(--bm-border-muted); }\n  #asset-meta h2 { margin: 0 0 4px; word-break: break-word; }\n  #asset-meta .sub { color: var(--bm-text-dim); font-size: 12px; margin-bottom: 16px; }\n  #asset-facts { display: grid; grid-template-columns: auto 1fr; gap: 6px 12px; font-size: 12px; }\n  #asset-facts dt { color: var(--bm-text-dim); }\n  #asset-facts dd { margin: 0; color: var(--bm-text); word-break: break-word; }\n  #asset-facts dd.mono { font-family: var(--bm-font-mono); }\n  #asset-actions { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 16px; }\n  /* The .hidden rules above are scoped to the viewer side; the actions row needs its own. */\n  #asset-actions .hidden { display: none; }\n  #asset-close { margin-left: auto; }\n";
+export declare const ASSET_DETAIL_CSS = "\n  /* Above #hq-overlay, which sits at 10 \u2014 a preview opened from a row must cover it. */\n  #asset-overlay { z-index: 11; }\n  #asset-dialog { display: flex; width: min(1100px, 94vw); height: min(760px, 88vh);\n                  overflow: hidden; }\n  /* The viewer takes the room. Everything else is a caption. The near-black ground is the\n     brand's: a creation is the only thing on this surface that carries colour. */\n  #asset-view { flex: 1; min-width: 0; position: relative; background: var(--bm-bg); }\n  #asset-view iframe { display: block; width: 100%; height: 100%; border: 0; }\n  #asset-view img { display: block; width: 100%; height: 100%; object-fit: contain;\n                    background: var(--bm-bg); }\n  #asset-view audio { position: absolute; left: 50%; top: 50%; width: min(420px, 80%);\n                      transform: translate(-50%, -50%); }\n  /* Fitted rather than filled, like the image rule above: a generated clip is 16:9 by default but\n     follows its first frame when one was given, so the dialog cannot assume a shape. */\n  #asset-view video { display: block; width: 100%; height: 100%; object-fit: contain;\n                      background: var(--bm-bg); }\n  /* A note here is always a failure or a wait that has gone on too long \u2014 the negative accent. */\n  #asset-note { position: absolute; inset: auto 0 0 0; padding: 10px 12px;\n                background: var(--bm-scrim); color: var(--bm-pink-hover); font-size: 12px; }\n  #asset-note.hidden, #asset-view > .hidden { display: none; }\n  /* Wide enough for the action pills to sit on one row (wrapping to two once Edit voxels shows):\n     uppercase tracked labels are wider than the sentence-case ones this panel used to have. */\n  #asset-meta { width: 360px; flex: none; padding: 16px; overflow-y: auto;\n                border-left: 1px solid var(--bm-border-muted); }\n  #asset-meta h2 { margin: 0 0 4px; word-break: break-word; }\n  #asset-meta .sub { color: var(--bm-text-dim); font-size: 12px; margin-bottom: 16px; }\n  #asset-facts { display: grid; grid-template-columns: auto 1fr; gap: 6px 12px; font-size: 12px; }\n  #asset-facts dt { color: var(--bm-text-dim); }\n  #asset-facts dd { margin: 0; color: var(--bm-text); word-break: break-word; }\n  #asset-facts dd.mono { font-family: var(--bm-font-mono); }\n  #asset-actions { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 16px; }\n  /* The .hidden rules above are scoped to the viewer side; the actions row needs its own. */\n  #asset-actions .hidden { display: none; }\n  #asset-close { margin-left: auto; }\n";
 /**
  * The overlay itself.
  *
  * `<audio controls>` rather than a play button of our own: the web Creator withholds native
  * controls because its player sits in a 46px row, and here there is a whole dialog. A creator
- * checking a sound effect wants the scrubber.
+ * checking a sound effect wants the scrubber. `<video controls>` is here for the same reason —
+ * a cutscene is watched, scrubbed and watched again.
+ *
+ * `preload="metadata"` on the video, not `none`: the dialog is opened BY a click on the row, so
+ * the creator has already asked for it, and a poster frame beats a black rectangle. Muted is
+ * deliberately absent — a generated clip may carry audio and this is where you would check.
  */
-export declare const ASSET_DETAIL_HTML = "\n  <div id=\"asset-overlay\" class=\"bm-overlay\">\n    <div id=\"asset-dialog\" class=\"bm-dialog\">\n      <div id=\"asset-view\">\n        <iframe id=\"asset-frame\" class=\"hidden\" title=\"Asset preview\"></iframe>\n        <img id=\"asset-image\" class=\"hidden\" alt=\"\">\n        <audio id=\"asset-audio\" class=\"hidden\" controls preload=\"none\"></audio>\n        <div id=\"asset-note\" class=\"hidden\"></div>\n      </div>\n      <aside id=\"asset-meta\">\n        <h2 id=\"asset-name\"></h2>\n        <div class=\"sub\" id=\"asset-sub\"></div>\n        <dl id=\"asset-facts\"></dl>\n        <div id=\"asset-actions\">\n          <button id=\"asset-edit-voxels\" class=\"bm-pill bm-pill--primary hidden\" type=\"button\" title=\"Open the 3D voxel editor: add, delete and recolor voxels, and set which ones glow\">Edit voxels</button>\n          <button id=\"asset-reset\" class=\"bm-pill\" type=\"button\" title=\"Back to the angle the thumbnail uses\">Reset view</button>\n          <button id=\"asset-copy\" class=\"bm-pill\" type=\"button\" title=\"Copy this asset's id\">Copy id</button>\n          <button id=\"asset-close\" class=\"bm-pill bm-pill--ghost\" type=\"button\">Close</button>\n        </div>\n      </aside>\n    </div>\n  </div>\n";
+export declare const ASSET_DETAIL_HTML = "\n  <div id=\"asset-overlay\" class=\"bm-overlay\">\n    <div id=\"asset-dialog\" class=\"bm-dialog\">\n      <div id=\"asset-view\">\n        <iframe id=\"asset-frame\" class=\"hidden\" title=\"Asset preview\"></iframe>\n        <img id=\"asset-image\" class=\"hidden\" alt=\"\">\n        <audio id=\"asset-audio\" class=\"hidden\" controls preload=\"none\"></audio>\n        <video id=\"asset-video\" class=\"hidden\" controls playsinline preload=\"metadata\"></video>\n        <div id=\"asset-note\" class=\"hidden\"></div>\n      </div>\n      <aside id=\"asset-meta\">\n        <h2 id=\"asset-name\"></h2>\n        <div class=\"sub\" id=\"asset-sub\"></div>\n        <dl id=\"asset-facts\"></dl>\n        <div id=\"asset-actions\">\n          <button id=\"asset-edit-voxels\" class=\"bm-pill bm-pill--primary hidden\" type=\"button\" title=\"Open the 3D voxel editor: add, delete and recolor voxels, and set which ones glow\">Edit voxels</button>\n          <button id=\"asset-reset\" class=\"bm-pill\" type=\"button\" title=\"Back to the angle the thumbnail uses\">Reset view</button>\n          <button id=\"asset-copy\" class=\"bm-pill\" type=\"button\" title=\"Copy this asset's id\">Copy id</button>\n          <button id=\"asset-close\" class=\"bm-pill bm-pill--ghost\" type=\"button\">Close</button>\n        </div>\n      </aside>\n    </div>\n  </div>\n";

package/dist/editor/asset-detail-panel.js

@@ -29,6 +29,10 @@ export const ASSET_DETAIL_CSS = `
                     background: var(--bm-bg); }
   #asset-view audio { position: absolute; left: 50%; top: 50%; width: min(420px, 80%);
                       transform: translate(-50%, -50%); }
+  /* Fitted rather than filled, like the image rule above: a generated clip is 16:9 by default but
+     follows its first frame when one was given, so the dialog cannot assume a shape. */
+  #asset-view video { display: block; width: 100%; height: 100%; object-fit: contain;
+                      background: var(--bm-bg); }
   /* A note here is always a failure or a wait that has gone on too long — the negative accent. */
   #asset-note { position: absolute; inset: auto 0 0 0; padding: 10px 12px;
                 background: var(--bm-scrim); color: var(--bm-pink-hover); font-size: 12px; }
@@ -53,7 +57,12 @@ export const ASSET_DETAIL_CSS = `
  *
  * `<audio controls>` rather than a play button of our own: the web Creator withholds native
  * controls because its player sits in a 46px row, and here there is a whole dialog. A creator
- * checking a sound effect wants the scrubber.
+ * checking a sound effect wants the scrubber. `<video controls>` is here for the same reason —
+ * a cutscene is watched, scrubbed and watched again.
+ *
+ * `preload="metadata"` on the video, not `none`: the dialog is opened BY a click on the row, so
+ * the creator has already asked for it, and a poster frame beats a black rectangle. Muted is
+ * deliberately absent — a generated clip may carry audio and this is where you would check.
  */
 export const ASSET_DETAIL_HTML = `
   <div id="asset-overlay" class="bm-overlay">
@@ -62,6 +71,7 @@ export const ASSET_DETAIL_HTML = `
         <iframe id="asset-frame" class="hidden" title="Asset preview"></iframe>
         <img id="asset-image" class="hidden" alt="">
         <audio id="asset-audio" class="hidden" controls preload="none"></audio>
+        <video id="asset-video" class="hidden" controls playsinline preload="metadata"></video>
         <div id="asset-note" class="hidden"></div>
       </div>
       <aside id="asset-meta">

package/dist/editor/asset-detail-panel.js.map

@@ -1 +1 @@
-{"version":3,"file":"asset-detail-panel.js","sourceRoot":"","sources":["../../src/editor/asset-detail-panel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+B/B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsBhC,CAAC"}
+{"version":3,"file":"asset-detail-panel.js","sourceRoot":"","sources":["../../src/editor/asset-detail-panel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmC/B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;CAuBhC,CAAC"}