@bitmagic/cli 0.1.64-dev.2 → 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/scaffold/blender-level-skill-files.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The `building-levels-in-blender` skill: a hand-designed low-poly world written as a Python script
+ * against the shipped `bmlevel` library, built by Blender into one GLB plus the collider / door /
+ * light / landmark JSON, audited with ray casts, reviewed from rendered stills, and loaded by the
+ * engine's `MeshLevel`. Distilled from a creator's space-station game whose agent installed Blender
+ * and hand-rolled every part of this — the build vocabulary, the audits, the review renders, the
+ * level loader — and hit the two failures the skill now names up front (a GLB fetched from a local
+ * path that 404s after publish; NPC spawns routed into an absent voxel grid).
+ *
+ * Same contract as `unity-skill-files.ts`: pure functions returning file contents, registered in
+ * `SHIPPED_SKILLS` (project.ts). The Python and Blender scripts ship in the package's
+ * `assets/blender-level/` (see `files` in package.json) rather than being rendered into every
+ * project; the skill's step 1 copies them into `tools/blender-level/`.
+ *
+ * The skill's first section is the gate: the path is for frontier models with Blender available,
+ * and everything else goes to `bitmagic forge`. The CLI cannot tell which model drives it, so the
+ * gate is the agent's own call — stated once, plainly, where the planning skill sends it.
+ *
+ * Backticks and `${` are escaped for the template literal; `project-files.test.ts` checks the
+ * rendered frontmatter and that no escape leaks into the output.
+ */
+export declare function renderBlenderLevelsSkill(): string;
+export declare function renderBlenderConventionsReference(): string;
+export declare function renderBlenderAuditsReference(): string;
+export declare function renderBlenderPassesReference(): string;
+export declare function renderBlenderEngineHandoffReference(): string;