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

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/assets/keep-glb.d.ts

@@ -0,0 +1,20 @@
+import type { Environment } from '../config/environments.js';
+export interface KeepGlbRequest {
+    environment: Environment;
+    token: string;
+    gameId: string;
+    /** The forger's URL for the generated mesh. */
+    glbUrl: string;
+    /** The filename to store it under — the asset name plus `.glb`. */
+    filename: string;
+    fetchImpl: typeof globalThis.fetch;
+    log: (message: string) => void;
+}
+export interface KeptGlb {
+    /** The project-storage URL the asset now points at. */
+    url: string;
+    size: number;
+}
+/** Injectable in tests so the lane runs without a network, matching the `voxelize` seam. */
+export type KeepGlb = (request: KeepGlbRequest) => Promise<KeptGlb>;
+export declare function reuploadGeneratedGlb(request: KeepGlbRequest): Promise<KeptGlb>;

package/dist/assets/keep-glb.js

@@ -0,0 +1,45 @@
+/**
+ * Keep a GENERATED mesh as a `glb` asset instead of voxelizing it — the low-poly project's half of
+ * `generate model` and `generate prop` (`artStyle: "low-poly"` in game.json, or `--keep-glb`).
+ *
+ * The Asset Forger's URL is a job output, not a home: the voxelize path only ever reads it once
+ * (in the headless engine, minutes later) and stores the `.vxl` it made, so nothing in a published
+ * game depends on that URL surviving. A kept mesh would — every player's browser fetches it — so
+ * the bytes are re-uploaded into the project's own storage first, exactly as `assets add
+ * --keep-glb` stores a file the creator already had. The entry is then `glbAssetEntry`, the same
+ * record the Creator writes for a kept import, with the forger URL recorded as the generation's
+ * `production.sourceUrl` so a later "make this again" knows where the mesh came from.
+ */
+import { CliError } from '../errors.js';
+import { uploadProjectFile } from '../http/signed-upload.js';
+import { isGlb } from './vxl-summary.js';
+export async function reuploadGeneratedGlb(request) {
+    const { glbUrl, filename, log } = request;
+    log(`Keeping the mesh: fetching ${glbUrl}…`);
+    let bytes;
+    try {
+        const response = await request.fetchImpl(glbUrl);
+        if (!response.ok) {
+            throw new CliError(`Fetching the generated mesh failed: HTTP ${response.status}. ${retryHint(glbUrl)}`);
+        }
+        bytes = new Uint8Array(await response.arrayBuffer());
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError(`Fetching the generated mesh failed: ${message}. ${retryHint(glbUrl)}`);
+    }
+    if (!isGlb(bytes)) {
+        throw new CliError(`The generator's file at ${glbUrl} is not a binary GLB (no glTF magic), so it cannot be kept as a mesh. `
+            + 'world.json is unchanged.');
+    }
+    log(`Uploading ${filename} (${Math.round(bytes.byteLength / 1024)} KB) into the project…`);
+    const upload = await uploadProjectFile(request.environment, request.token, { gameId: request.gameId, filename, contentType: 'model/gltf-binary', bytes }, { fetch: request.fetchImpl });
+    log(`Uploaded: ${upload.url}`);
+    return { url: upload.url, size: bytes.byteLength };
+}
+function retryHint(glbUrl) {
+    return `The generated mesh is kept at ${glbUrl} — retry with \`--glb-url\` to skip the paid generation. world.json is unchanged.`;
+}
+//# sourceMappingURL=keep-glb.js.map

package/dist/assets/keep-glb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keep-glb.js","sourceRoot":"","sources":["../../src/assets/keep-glb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAuBzC,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAuB;IAChE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IAC1C,GAAG,CAAC,8BAA8B,MAAM,GAAG,CAAC,CAAC;IAC7C,IAAI,KAAiB,CAAC;IACtB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,QAAQ,CAAC,4CAA4C,QAAQ,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC1G,CAAC;QACD,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,QAAQ;YAAE,MAAM,KAAK,CAAC;QAC3C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,MAAM,IAAI,QAAQ,CAAC,uCAAuC,OAAO,KAAK,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAClB,MAAM,IAAI,QAAQ,CAChB,2BAA2B,MAAM,wEAAwE;cACvG,0BAA0B,CAC7B,CAAC;IACJ,CAAC;IACD,GAAG,CAAC,aAAa,QAAQ,KAAK,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,wBAAwB,CAAC,CAAC;IAC3F,MAAM,MAAM,GAAG,MAAM,iBAAiB,CACpC,OAAO,CAAC,WAAW,EACnB,OAAO,CAAC,KAAK,EACb,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,mBAAmB,EAAE,KAAK,EAAE,EAC7E,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE,CAC7B,CAAC;IACF,GAAG,CAAC,aAAa,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IAC/B,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;AACrD,CAAC;AAED,SAAS,SAAS,CAAC,MAAc;IAC/B,OAAO,iCAAiC,MAAM,mFAAmF,CAAC;AACpI,CAAC"}

package/dist/cli.d.ts

@@ -141,6 +141,10 @@ declare const rawCommands: {
             readonly type: "string";
             readonly description: "Game name.";
         };
+        readonly 'art-style': {
+            readonly type: "string";
+            readonly description: string;
+        };
         readonly idea: {
             readonly type: "string";
             readonly description: "One-line pitch. Seeds GAME-DESIGN.md and picks the template whose camera and controls fit it. Optional — you can write it yourself.";
@@ -515,6 +519,7 @@ declare const rawCommands: {
         };
     }>;
     ios: CommandDef<ArgsDef>;
+    tools: CommandDef<ArgsDef>;
 };
 type CommandName = keyof typeof rawCommands;
 export declare const subCommands: Record<CommandName, CommandDef<ArgsDef>>;

package/dist/cli.js

@@ -32,6 +32,7 @@ import { judgeCommand } from './commands/judge.js';
 import { forgeCommand } from './commands/forge.js';
 import { publishCommand } from './commands/publish.js';
 import { iosCommand } from './commands/ios.js';
+import { toolsCommand } from './commands/tools.js';
 // citty's runMain() catches every error thrown from a command's `run()` internally and calls
 // process.exit() itself — it never rejects the promise it returns, so the `.catch()` below
 // never runs for those. For anything that isn't citty's own internal CLIError class, its catch
@@ -223,6 +224,7 @@ const rawCommands = {
     forge: forgeCommand,
     publish: publishCommand,
     ios: iosCommand,
+    tools: toolsCommand,
 };
 export const subCommands = Object.fromEntries(Object.entries(rawCommands).map(([name, command]) => [name, withCleanErrors(command, name)]));
 // This module only builds `main` and exports it (along with `subCommands` and `withCleanErrors`)