@bitmagic/cli 0.1.61-dev.9 → 0.1.62-dev.0

package/assets/unity-import/fbx_axis.py

@@ -0,0 +1,174 @@
+"""Work out, per asset pack, how Unity's mesh axes relate to the raw FBX vertex axes.
+
+They are not always the same. One pack's models import with their axes untouched, while another
+kit's come in cyclically permuted — Unity's mesh is `(raw_y, raw_z, raw_x)`. The
+difference lives in the exporter's node/geometric transforms and is a property of how each pack was
+authored, so it cannot be read off the file's declared up-axis (both packs declare Y-up).
+
+Rather than guess, this derives the permutation from Unity's own data: a GameObject carrying both a
+MeshFilter and a BoxCollider states the mesh's dimensions outright in `m_Size`, with no FBX parsing
+involved. Comparing that against the raw bounds identifies the permutation, and the answer is
+consistent across a pack, so a pack with any evidence at all resolves every model in it.
+
+Both the collider extractor and the GLB build must apply the same correction, or the geometry a
+player sees and the geometry they collide with disagree.
+"""
+import os
+import re
+
+# Candidate axis permutations, as index tuples into the raw FBX bounds.
+PERMUTATIONS = {
+    'identity': (0, 1, 2),
+    'swapYZ': (0, 2, 1),
+    'swapXY': (1, 0, 2),
+    'swapXZ': (2, 1, 0),
+    'cycYZX': (1, 2, 0),
+    'cycZXY': (2, 0, 1),
+}
+
+# Unity converts a right-handed FBX into its own left-handed space by negating X, so a model's
+# axes are not merely permuted — one of them is flipped. Sizes alone cannot see that (a box is the
+# same size mirrored), which is why deriving from `m_Size` produced meshes that looked right on
+# their own and assembled wrongly: every one was mirrored. `m_Center` does see it, because a mesh
+# whose geometry sits off its own origin lands on the opposite side when flipped.
+#
+# Used when a pack has no BoxCollider evidence at all, in place of the old plain identity.
+# Unity negates X converting a right-handed FBX into its left-handed space — on every import.
+# This is the second half of the orientation fix (the first is the geometric transform, applied in
+# fbx_bounds). It was found, lost and found again: m_Center fits said (-1,1,1) for 157 of 181
+# models, an arena-symmetry metric that cannot see a uniform mirror said "worse", and the metric
+# was wrongly trusted. A pair of end caps settled it: two quarter-rounds only join into one
+# smooth half-round with the negation applied. Proven afterwards with no extra sign needed on top
+# of the reader's output for 157/181 boxes, 137 of which are X-offset and can see a mirror.
+DEFAULT_TRANSFORM = ((0, 1, 2), (-1, 1, 1))
+
+
+def pack_of(path, assets_root):
+    """The top-level folder under Assets/ a model belongs to."""
+    rel = os.path.relpath(path, assets_root)
+    return rel.split(os.sep)[0]
+
+
+def _ground_truth(ue, assets_root):
+    """Every (fbx path -> (mesh fileID, Unity m_Size, m_Center)) a mesh+BoxCollider pair gives us."""
+    out = {}
+    for base, _dirs, files in os.walk(assets_root):
+        for f in files:
+            if not f.endswith('.prefab'):
+                continue
+            docs = ue.parse_file(os.path.join(base, f))
+            for _goid, (cls, body) in docs.items():
+                if cls != '1':
+                    continue
+                mesh = box = None
+                for m in re.finditer(r'- component: \{fileID: (\d+)\}', body):
+                    cd = docs.get(m.group(1))
+                    if not cd:
+                        continue
+                    if cd[0] == '33':
+                        mm = re.search(r'm_Mesh: \{fileID: (-?\d+), guid: ([0-9a-f]{32})', cd[1])
+                        if mm:
+                            mesh = (mm.group(2), mm.group(1))
+                    elif cd[0] == '65':
+                        box = cd[1]
+                if mesh and box:
+                    mp = ue.guid2path.get(mesh[0]) if isinstance(mesh, tuple) else ue.guid2path.get(mesh)
+                    fid = mesh[1] if isinstance(mesh, tuple) else None
+                    if mp and mp.lower().endswith('.fbx') and mp not in out:
+                        out[mp] = (fid,
+                                   ue.vec3(box, 'm_Size', (0, 0, 0)),
+                                   ue.vec3(box, 'm_Center', (0, 0, 0)))
+    return out
+
+
+def build_axis_map(ue, assets_root, verbose=False):
+    """{pack name: (permutation, signs)}, derived from Unity's own collider boxes.
+
+    Both halves matter. The permutation says which raw axis becomes which Unity axis; the signs say
+    which of them are flipped. Matching `m_Size` alone fixes only the first and silently leaves every
+    mesh mirrored.
+    """
+    import itertools
+    votes = {}
+    counts = {}
+    for mp, (fid, size, center) in _ground_truth(ue, assets_root).items():
+        guid = next((g for g, p in ue.guid2path.items() if p == mp), None)
+        bounds = ue.mesh_bounds_raw(guid, ue.guid2path, fid) if guid else None
+        if not bounds:
+            continue
+        mn, mx = bounds
+        if max(mx[i] - mn[i] for i in range(3)) < 1e-6:
+            continue
+        lo = [center[i] - size[i] / 2 for i in range(3)]
+        hi = [center[i] + size[i] / 2 for i in range(3)]
+        pack = pack_of(mp, assets_root)
+        counts[pack] = counts.get(pack, 0) + 1
+        bucket = votes.setdefault(pack, {})
+        for name, perm in PERMUTATIONS.items():
+            for signs in ((1, 1, 1),):   # see DEFAULT_TRANSFORM: signed fits measured worse
+                ok = True
+                for i in range(3):
+                    a = signs[i] * mn[perm[i]]
+                    b = signs[i] * mx[perm[i]]
+                    if abs(min(a, b) - lo[i]) > 0.15 or abs(max(a, b) - hi[i]) > 0.15:
+                        ok = False
+                        break
+                if ok:
+                    key = (perm, signs)
+                    bucket[key] = bucket.get(key, 0) + 1
+
+    axis_map = {}
+    for pack, bucket in votes.items():
+        if not bucket:
+            continue
+        best, n = max(bucket.items(), key=lambda kv: kv[1])
+        axis_map[pack] = best
+        if verbose:
+            print(f'   axis: {pack:24s} -> perm {best[0]} signs {best[1]} '
+                  f'({n} of {counts.get(pack, 0)} models)')
+    return axis_map
+
+
+def _override():
+    """`axisOverride` in unity-import.json (or UNITY_AXIS_OVERRIDE): "Pack=swapYZ:-1,1,1;Sci-Fi Base=identity" — for experiments."""
+    from import_config import CFG as _CFG
+    raw = _CFG['axisOverride']
+    out = {}
+    for item in raw.split(';'):
+        if '=' not in item:
+            continue
+        pack, spec = item.split('=', 1)
+        name, _, signs = spec.partition(':')
+        perm = PERMUTATIONS.get(name.strip())
+        if not perm:
+            continue
+        sg = tuple(int(v) for v in signs.split(',')) if signs else (1, 1, 1)
+        out[pack.strip()] = (perm, sg)
+    return out
+
+
+# No pins. What this file used to guess per pack is stated outright in the FBX itself
+# (see fbx_bounds.apply_geometric); permutation_for returns identity.
+PINNED = {}
+
+
+def permutation_for(path, assets_root, axis_map):
+    """Always identity now.
+
+    The per-pack permutation this file derived was a stand-in for something the FBX states
+    outright: the Model node's GeometricRotation/GeometricTranslation, which Unity bakes into the
+    mesh and which `fbx_bounds.read_fbx` now applies to the raw vertices. With that in place, no
+    axis guessing is needed for any pack — a 3ds Max kit and a Maya kit both came out right from
+    the same code path. Kept so callers keep working; the
+    env override remains for experiments.
+    """
+    pack = pack_of(path, assets_root)
+    over = _override()
+    if pack in over:
+        return over[pack]
+    return DEFAULT_TRANSFORM
+
+
+def apply_permutation(vec, transform):
+    perm, signs = transform
+    return [signs[0] * vec[perm[0]], signs[1] * vec[perm[1]], signs[2] * vec[perm[2]]]

package/assets/unity-import/fbx_bounds.py

@@ -0,0 +1,202 @@
+import struct, zlib, sys, os, json
+
+# A MeshCollider collides with triangles, not with its bounding box. Reading the vertices lets the
+# caller ask whether a mesh actually reaches the gameplay plane, instead of assuming its box does.
+KEEP_VERTICES = False
+MAX_VERTICES = 4000
+UNITY_NEGATE_X = True
+
+
+def _rx(a):
+    import math
+    c, s_ = math.cos(a), math.sin(a); return ((1, 0, 0), (0, c, -s_), (0, s_, c))
+def _ry(a):
+    import math
+    c, s_ = math.cos(a), math.sin(a); return ((c, 0, s_), (0, 1, 0), (-s_, 0, c))
+def _rz(a):
+    import math
+    c, s_ = math.cos(a), math.sin(a); return ((c, -s_, 0), (s_, c, 0), (0, 0, 1))
+def _mm(a, b):
+    return tuple(tuple(sum(a[i][k]*b[k][j] for k in range(3)) for j in range(3)) for i in range(3))
+def _mv(m, v):
+    return tuple(sum(m[i][k]*v[k] for k in range(3)) for i in range(3))
+
+
+def apply_geometric(v, g):
+    """Apply a Model node's geometric transform to one raw vertex, the way Unity bakes it.
+
+    FBX geometric rotation is an XYZ Euler (rotate about X, then Y, then Z, i.e. Rz*Ry*Rx), in
+    degrees; scaling is applied first and translation last. Verified against Unity's own
+    BoxCollider for Wall_7.FBX: raw vertices land a full unit away with the axes cycled, this
+    lands on the collider box to the millimetre.
+    """
+    import math
+    sc = g.get('GeometricScaling', (1.0, 1.0, 1.0))
+    rot = g.get('GeometricRotation', (0.0, 0.0, 0.0))
+    tr = g.get('GeometricTranslation', (0.0, 0.0, 0.0))
+    x, y, z = v[0]*sc[0], v[1]*sc[1], v[2]*sc[2]
+    if any(abs(r) > 1e-9 for r in rot):
+        R = _mm(_rz(math.radians(rot[2])), _mm(_ry(math.radians(rot[1])), _rx(math.radians(rot[0]))))
+        x, y, z = _mv(R, (x, y, z))
+    x, y, z = x + tr[0], y + tr[1], z + tr[2]
+    # Unity converts the right-handed FBX into its left-handed space by negating X — on every
+    # import, geometric transform or not. A bounding box cannot see a mirror, so this was invisible
+    # to every collider-box check; a pair of quarter-round end caps could see it, and
+    # curved the wrong way until it was applied.
+    return (-x, y, z) if UNITY_NEGATE_X else (x, y, z)
+
+
+def read_fbx(path, keep_vertices=False):
+    global KEEP_VERTICES
+    KEEP_VERTICES = keep_vertices
+    data = open(path,'rb').read()
+    if not data.startswith(b'Kaydara FBX Binary'):
+        return None
+    version = struct.unpack_from('<I', data, 23)[0]
+    off = 27
+    wide = version >= 7500
+    meshes = []
+    _pending_verts = []   # list of (name, [ (minx,miny,minz),(maxx,maxy,maxz) ])
+    # FBX geometric transforms live on the Model node and apply to that node's mesh vertices
+    # ONLY. Unity bakes them into the mesh data; reading the raw vertex array skips them and
+    # leaves every 3ds Max export cycled by two right angles and displaced.
+    geo_list = []
+    _geo_cur = {}
+
+    def read_record(off, path_names):
+        if wide:
+            end, nprops, plen = struct.unpack_from('<QQQ', data, off); off += 24
+        else:
+            end, nprops, plen = struct.unpack_from('<III', data, off); off += 12
+        nlen = data[off]; off += 1
+        name = data[off:off+nlen].decode('utf-8','replace'); off += nlen
+        if end == 0:
+            return 0, None
+        props = []
+        pend = off + plen
+        for _ in range(nprops):
+            t = chr(data[off]); off += 1
+            if t in 'SR':
+                L = struct.unpack_from('<I', data, off)[0]; off += 4
+                props.append(data[off:off+L].decode('utf-8', 'replace') if t == 'S' else b''); off += L
+                continue
+            if t == 'Y': props.append(struct.unpack_from('<h', data, off)[0]); off += 2
+            elif t == 'C': props.append(data[off] != 0); off += 1
+            elif t == 'I': props.append(struct.unpack_from('<i', data, off)[0]); off += 4
+            elif t == 'F': props.append(struct.unpack_from('<f', data, off)[0]); off += 4
+            elif t == 'D': props.append(struct.unpack_from('<d', data, off)[0]); off += 8
+            elif t == 'L': props.append(struct.unpack_from('<q', data, off)[0]); off += 8
+            elif t in 'fdlib':
+                alen, enc, clen = struct.unpack_from('<III', data, off); off += 12
+                raw = data[off:off+clen]; off += clen
+                if enc == 1:
+                    raw = zlib.decompress(raw)
+                fmt = {'f':'f','d':'d','l':'q','i':'i','b':'b'}[t]
+                if t in 'fd' or t in 'li':
+                    props.append(('array', fmt, alen, raw))
+                else:
+                    props.append(('array', fmt, alen, raw))
+            elif t in 'SR':
+                slen = struct.unpack_from('<I', data, off)[0]; off += 4
+                props.append(data[off:off+slen]); off += slen
+            else:
+                off = pend
+                break
+        off = pend
+        if name == 'Model':
+            if _geo_cur:
+                geo_list.append(dict(_geo_cur))
+            _geo_cur.clear()
+            _geo_cur['_model'] = True
+        if name == 'P' and props and _geo_cur.get('_model') and isinstance(props[0], str) \
+                and props[0] in ('GeometricRotation', 'GeometricTranslation', 'GeometricScaling'):
+            vals = [v for v in props[4:] if isinstance(v, (int, float))]
+            if len(vals) == 3:
+                _geo_cur[props[0]] = tuple(float(v) for v in vals)
+        if name == 'Vertices' and props and isinstance(props[0], tuple):
+            _, fmt, alen, raw = props[0]
+            vals = struct.unpack('<%d%s' % (alen, fmt), raw[:alen*struct.calcsize(fmt)])
+            mn = [1e30]*3; mx = [-1e30]*3
+            for i in range(0, len(vals)-2, 3):
+                for k in range(3):
+                    v = vals[i+k]
+                    if v < mn[k]: mn[k] = v
+                    if v > mx[k]: mx[k] = v
+            _pending_verts.append(len(meshes))
+            verts = None
+            if KEEP_VERTICES:
+                # Kept whole: PolygonVertexIndex refers to these by position, so subsampling
+                # would silently scramble the faces.
+                verts = [(vals[i], vals[i + 1], vals[i + 2])
+                         for i in range(0, len(vals) - 2, 3)]
+            meshes.append((path_names[-1] if path_names else '', mn, mx, verts, None, None))
+        if name == 'PolygonVertexIndex' and KEEP_VERTICES and props and isinstance(props[0], tuple):
+            _, fmt, alen, raw = props[0]
+            idx = struct.unpack('<%d%s' % (alen, fmt), raw[:alen*struct.calcsize(fmt)])
+            if _pending_verts:
+                at = _pending_verts[-1]
+                if at < len(meshes):
+                    e = meshes[at]
+                    meshes[at] = (e[0], e[1], e[2], e[3], idx, e[5])
+        # nested
+        nullsz = 25 if wide else 13
+        while off < end - nullsz:
+            off, _ = read_record(off, path_names + [name])
+        if off < end:
+            off = end
+        return off, name
+
+    unit_scale = None
+    nullsz = 25 if wide else 13
+    while off < len(data) - nullsz:
+        noff, nm = read_record(off, [])
+        if noff == 0 or noff <= off: break
+        off = noff
+    idx = data.find(b'UnitScaleFactor')
+    if idx > 0:
+        seg = data[idx:idx+120]
+        j = seg.find(b'\x04', 15)   # 'D' type marker is 0x44; properties are S,S,S,S,D
+        k = seg.find(b'D', 15)
+        if k > 0 and k + 9 <= len(seg):
+            try:
+                unit_scale = struct.unpack_from('<d', seg, k+1)[0]
+            except Exception:
+                unit_scale = None
+    if _geo_cur:
+        geo_list.append(dict(_geo_cur))
+    geos = [g for g in geo_list if any(k in g for k in ('GeometricRotation', 'GeometricTranslation', 'GeometricScaling'))]
+    # Only Model records that are meshes carry geometry; pair in order when the counts line up,
+    # and otherwise only when there is exactly one of each.
+    paired = []
+    for i, e in enumerate(meshes):
+        g = None
+        if len(geos) == len(meshes):
+            g = geos[i]
+        elif len(geos) == 1 and len(meshes) == 1:
+            g = geos[0]
+        paired.append((e[0], e[1], e[2], e[3], e[4], g))
+    meshes = paired
+    # Bounds are reported AFTER the geometric transform, so every consumer sees Unity's mesh.
+    fixed = []
+    for (nm, mn, mx, verts, idx, g) in meshes:
+        if not g:
+            g = {}   # still run apply_geometric: the X negation applies to every file
+        if True:
+            corners = [(x, y, z) for x in (mn[0], mx[0]) for y in (mn[1], mx[1]) for z in (mn[2], mx[2])]
+            tc = [apply_geometric(c, g) for c in corners]
+            mn = [min(c[k] for c in tc) for k in range(3)]
+            mx = [max(c[k] for c in tc) for k in range(3)]
+            if verts:
+                verts = [apply_geometric(v, g) for v in verts]
+        fixed.append((nm, mn, mx, verts, idx, g))
+    return fixed, unit_scale
+
+if __name__ == '__main__':
+    for p in sys.argv[1:]:
+        r = read_fbx(p)
+        ms, us = (r if r else (None, None))
+        if not ms:
+            print(os.path.basename(p), 'FAILED'); continue
+        mn = [min(m[1][k] for m in ms) for k in range(3)]
+        mx = [max(m[2][k] for m in ms) for k in range(3)]
+        print(os.path.basename(p), 'meshes=%d' % len(ms), 'unit=', us, 'min=', [round(v,3) for v in mn], 'max=', [round(v,3) for v in mx])

package/assets/unity-import/import_config.py

@@ -0,0 +1,86 @@
+"""Per-project settings for the Unity level import, read from `tools/unity-import.json`.
+
+Every value that belongs to a particular game — where its Unity project lives, which scene is the
+level, which MonoBehaviour scripts mark spawns and bases, where the play plane sits — comes from
+this one file, so the scripts themselves never need editing to run on another game. Copy
+`unity-import.example.json` to `unity-import.json` and fill it in; the keys and their defaults are
+listed in DEFAULTS. `UNITY_IMPORT_CONFIG` names a different file; `UNITY_ROOT`, `UNITY_PLANE_Z` and
+`UNITY_AXIS_OVERRIDE` override single values from the environment for experiments.
+"""
+import json
+import os
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+
+DEFAULTS = {
+    # The Unity tree that holds Assets/ and ProjectSettings/ for the level (a repo can hold more
+    # than one; pick the one the creator's editor opens).
+    'unityRoot': '',
+    # Scene path relative to unityRoot, and the level name the game data is written under.
+    'scene': 'Assets/Scenes/Main.unity',
+    'levelName': 'Main',
+    # Gameplay plane for a 2D-on-a-plane game: Unity z of the plane and the half-thickness a
+    # collider must cross to count as a wall (the ship's radius is a good value).
+    'planeZ': -1.0,
+    'planeHalf': 0.8,
+    # Instances farther than this from the origin are stray copies parked outside the level.
+    'arenaLimit': 80.0,
+    # Output GLB (from convert_assets) and the asset name it is uploaded under.
+    'glb': 'build/glb/level.glb',
+    'assetName': 'level-arena',
+    # Where write_arena_data emits the game's level data.
+    'outputTs': 'src/work/ArenaData.ts',
+    # Prefabs to convert when convert_assets is not run in scene mode.
+    'prefabs': [],
+    # Prefab tags whose colliders are never walls (decoration that would seal a room).
+    'badTags': [],
+    # MonoBehaviour scripts (file names) and prefab files that mark spawns, bases and pickups.
+    'markerScripts': ['Spawner.cs', 'SpawnPoint.cs', 'PowerupSpawnPoint.cs'],
+    'markerPrefabs': ['Base.prefab', 'Spawner.prefab', 'SpawnPoint.prefab', 'PowerupSpawnPoint.prefab'],
+    # Render-mesh name families that must be solid although they carry no 2D collider
+    # (mesh_walls slices them at the play plane).
+    'wallFamilies': [],
+    # Per-pack axis override for experiments: "Pack=cycYZX:-1,1,1;Other=identity".
+    'axisOverride': '',
+}
+
+
+def _load():
+    path = os.environ.get('UNITY_IMPORT_CONFIG') or os.path.join(_HERE, 'unity-import.json')
+    cfg = dict(DEFAULTS)
+    if os.path.exists(path):
+        with open(path, encoding='utf-8') as fh:
+            data = json.load(fh)
+        unknown = sorted(set(data) - set(DEFAULTS) - {'_comment'})
+        if unknown:
+            raise SystemExit(f'{path}: unknown keys {unknown}; known keys are {sorted(DEFAULTS)}')
+        cfg.update({k: v for k, v in data.items() if k != '_comment'})
+    if os.environ.get('UNITY_ROOT'):
+        cfg['unityRoot'] = os.environ['UNITY_ROOT']
+    if os.environ.get('UNITY_PLANE_Z'):
+        cfg['planeZ'] = float(os.environ['UNITY_PLANE_Z'])
+    if os.environ.get('UNITY_AXIS_OVERRIDE'):
+        cfg['axisOverride'] = os.environ['UNITY_AXIS_OVERRIDE']
+    cfg['unityRoot'] = os.path.expanduser(cfg['unityRoot'])
+    cfg['_path'] = path
+    return cfg
+
+
+CFG = _load()
+
+
+def unity_root():
+    root = CFG['unityRoot']
+    if not root or not os.path.isdir(os.path.join(root, 'Assets')):
+        raise SystemExit(f"unityRoot {root!r} has no Assets/ directory; set it in {CFG['_path']} "
+                         f"(or UNITY_ROOT) to the Unity tree that holds the level")
+    return root
+
+
+def scene_path():
+    return os.path.join(unity_root(), CFG['scene'])
+
+
+def project_root():
+    """The game project (the directory that holds tools/)."""
+    return os.path.dirname(_HERE)

package/assets/unity-import/level_patches.example.json

@@ -0,0 +1,23 @@
+{
+  "_comment": "Declarative scene edits applied identically by unity_colliders2d.py and unity_renderers.py. EMPTY on purpose: every earlier entry turned out to be a walker bug (scene overrides that deactivate whole prefab instances or disable components were being ignored); the walkers honour those now. Keep for genuine gameplay edits only. move_objects: the four corner tower groups slide 3 units toward the centre on both axes so they overlap the tunnel runs (the scene leaves a 1-2 unit seam at the play plane).",
+  "add_instances": [],
+  "remove_instances": [],
+  "move_objects": [
+    {
+      "name": "CornerTowerTopLeft",
+      "toward_center": 3.0
+    },
+    {
+      "name": "CornerTowerTopRight",
+      "toward_center": 3.0
+    },
+    {
+      "name": "CornerTowerBottomLeft",
+      "toward_center": 3.0
+    },
+    {
+      "name": "CornerTowerBottomRight",
+      "toward_center": 3.0
+    }
+  ]
+}

package/assets/unity-import/mesh_walls.py

@@ -0,0 +1,78 @@
+"""Slice render meshes at the play plane into 2D wall rectangles.
+
+Some level geometry has no 2D collider in Unity yet must be solid for gameplay here: the
+perimeter wall ring of the origin game was plain scene decoration, and a
+Rigidbody2D ship flies straight through it. This runs inside Blender: it loads the built arena
+GLB, samples every triangle of the named families that crosses the slab around the play plane,
+rasterises the hits into a 0.5-unit occupancy grid and merges runs into axis-aligned rectangles.
+
+    blender -b --python tools/mesh_walls.py -- build/glb/room-for-9.glb tools/render_walls.json
+
+Coordinates: the GLB is (ux, uy, -uz); Blender imports glTF Y-up as Z-up, so Blender x = Unity x,
+Blender z = Unity y (the map's vertical axis), Blender y = Unity z (depth, negative toward the
+camera). The play plane is `planeZ` in unity-import.json.
+"""
+import sys, os, json
+import bpy, mathutils
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from import_config import CFG as _CFG  # noqa: E402
+argv = sys.argv[sys.argv.index('--') + 1:] if '--' in sys.argv else []
+GLB = argv[0] if argv else _CFG['glb']
+OUT = argv[1] if len(argv) > 1 else 'tools/render_walls.json'
+FAMILIES = tuple(_CFG['wallFamilies'])
+PLANE = float(_CFG['planeZ'])
+HALF = 0.45           # slab half-depth: the tunnel floor sits at depth 0, keep it out
+CELL = 0.5
+LIMIT = 72.0
+
+bpy.ops.wm.read_factory_settings(use_empty=True)
+bpy.ops.import_scene.gltf(filepath=GLB)
+N = int(2 * LIMIT / CELL)
+grid = [[False] * N for _ in range(N)]
+
+def mark(x, y):
+    i = int((x + LIMIT) / CELL); j = int((y + LIMIT) / CELL)
+    if 0 <= i < N and 0 <= j < N: grid[j][i] = True
+
+count = 0
+for o in bpy.data.objects:
+    if o.type != 'MESH' or not any(f in o.name for f in FAMILIES): continue
+    count += 1
+    m = o.matrix_world; me = o.data
+    vs = [m @ v.co for v in me.vertices]
+    for poly in me.polygons:
+        pts = [vs[i] for i in poly.vertices]
+        ds = [p.y for p in pts]                    # Blender y = Unity depth
+        if max(ds) < PLANE - HALF or min(ds) > PLANE + HALF: continue
+        for k in range(1, len(pts) - 1):           # fan-triangulate
+            a, b, c = pts[0], pts[k], pts[k + 1]
+            steps = 14
+            for ui in range(steps + 1):
+                for vi in range(steps + 1 - ui):
+                    u, v = ui / steps, vi / steps
+                    q = a + (b - a) * u + (c - a) * v
+                    if PLANE - HALF <= q.y <= PLANE + HALF: mark(q.x, q.z)
+
+# close one-cell sampling holes (dilate then erode), then greedy maximal rectangles
+def closed(g):
+    d = [[any(g[jj][ii] for jj in range(max(0, j - 1), min(N, j + 2)) for ii in range(max(0, i - 1), min(N, i + 2))) for i in range(N)] for j in range(N)]
+    return [[all(d[jj][ii] for jj in range(max(0, j - 1), min(N, j + 2)) for ii in range(max(0, i - 1), min(N, i + 2))) or g[j][i] for i in range(N)] for j in range(N)]
+grid = closed(grid)
+rects = []
+free = [row[:] for row in grid]
+for j in range(N):
+    for i in range(N):
+        if not free[j][i]: continue
+        i1 = i
+        while i1 < N and free[j][i1]: i1 += 1
+        j1 = j + 1
+        while j1 < N and all(free[j1][ii] for ii in range(i, i1)): j1 += 1
+        for jj in range(j, j1):
+            for ii in range(i, i1): free[jj][ii] = False
+        rects.append([i, j, i1, j1])
+walls = [dict(x0=round(r[0] * CELL - LIMIT, 2), y0=round(r[1] * CELL - LIMIT, 2),
+              x1=round(r[2] * CELL - LIMIT, 2), y1=round(r[3] * CELL - LIMIT, 2), name='+'.join(FAMILIES) or 'sliced', tag='Sliced')
+         for r in rects]
+json.dump(walls, open(OUT, 'w'), indent=1)
+print(f"MESH_WALLS meshes {count} cells {sum(map(sum, grid))} rects {len(walls)} -> {OUT}")

package/assets/unity-import/render_topdown.py

@@ -0,0 +1,33 @@
+"""Orthographic top-down render of the built arena GLB, for eyeballing the level layout.
+
+    blender -b --python tools/render_topdown.py -- build/glb/room-for-9.glb .bitmagic/topdown.png
+
+Camera looks along Unity -z... in Blender terms: the GLB imports with Blender y = Unity depth
+(negative toward the camera), Blender z = Unity y (map vertical). So the camera sits at large
+negative Blender y looking toward +y, with Blender z as image up and Blender x as image right.
+"""
+import sys, os, bpy, math, mathutils
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from import_config import CFG as _CFG  # noqa: E402
+argv = sys.argv[sys.argv.index('--') + 1:] if '--' in sys.argv else []
+GLB = argv[0] if argv else _CFG['glb']
+OUT = argv[1] if len(argv) > 1 else '.bitmagic/topdown.png'
+bpy.ops.wm.read_factory_settings(use_empty=True)
+bpy.ops.import_scene.gltf(filepath=GLB)
+sc = bpy.context.scene
+cam_data = bpy.data.cameras.new('top'); cam_data.type = 'ORTHO'; cam_data.ortho_scale = 150
+cam = bpy.data.objects.new('top', cam_data); sc.collection.objects.link(cam)
+cam.location = (0, -200, 0)
+cam.rotation_euler = (math.radians(90), 0, 0)   # look along +y, z up
+sc.camera = cam
+sun = bpy.data.lights.new('sun', 'SUN'); sun.energy = 4.0
+so = bpy.data.objects.new('sun', sun); sc.collection.objects.link(so)
+so.rotation_euler = (math.radians(60), math.radians(20), 0)
+sc.render.engine = 'BLENDER_EEVEE_NEXT' if hasattr(bpy.types, 'SceneEEVEE') and 'BLENDER_EEVEE_NEXT' in [e.identifier for e in bpy.types.RenderSettings.bl_rna.properties['engine'].enum_items] else 'BLENDER_EEVEE'
+sc.render.resolution_x = 1400; sc.render.resolution_y = 1400
+sc.render.filepath = OUT
+sc.world = bpy.data.worlds.new('w'); sc.world.use_nodes = True
+sc.world.node_tree.nodes['Background'].inputs[0].default_value = (0.02, 0.02, 0.03, 1)
+sc.world.node_tree.nodes['Background'].inputs[1].default_value = 1.0
+bpy.ops.render.render(write_still=True)
+print('TOPDOWN', OUT)

package/assets/unity-import/unity-import.example.json

@@ -0,0 +1,27 @@
+{
+  "_comment": "Copy to unity-import.json and fill in. Every key is documented in import_config.py; the values here are placeholders.",
+  "unityRoot": "~/path/to/UnityProject",
+  "scene": "Assets/Scenes/Main.unity",
+  "levelName": "Main",
+  "planeZ": -1.0,
+  "planeHalf": 0.8,
+  "arenaLimit": 80.0,
+  "glb": "build/glb/level.glb",
+  "assetName": "level-arena",
+  "outputTs": "src/work/ArenaData.ts",
+  "prefabs": [],
+  "badTags": [],
+  "markerScripts": [
+    "Spawner.cs",
+    "SpawnPoint.cs",
+    "PowerupSpawnPoint.cs"
+  ],
+  "markerPrefabs": [
+    "Base.prefab",
+    "Spawner.prefab",
+    "SpawnPoint.prefab",
+    "PowerupSpawnPoint.prefab"
+  ],
+  "wallFamilies": [],
+  "axisOverride": ""
+}