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

package/dist/scaffold/unity-skill-files.js

@@ -0,0 +1,474 @@
+/**
+ * The `converting-unity-levels` skill: a Unity scene + prefabs + FBX + colliders into one GLB and
+ * collider data for a Bitmagic game. Distilled from a 2D arena-shooter port, where every rule in
+ * it was paid for with a level that looked plausible and was wrong.
+ *
+ * Same contract as `skill-files.ts`: pure functions returning file contents, registered in
+ * `SHIPPED_SKILLS` (project.ts), so every skills directory the project holds receives a copy. The
+ * skill is prose plus four references; the Python and Blender scripts it drives ship in the
+ * package's `assets/unity-import/` (see `files` in package.json) rather than being rendered into
+ * every project, since most games never port a Unity level and the scripts are large. Nothing
+ * game-specific is in those scripts: each project describes itself in `tools/unity-import.json`,
+ * which the skill's step 0 walks through.
+ *
+ * Scope, stated in the skill itself: the visual pipeline is general; collider extraction is
+ * general; the emitted level data is shaped for 2D-on-a-plane games, and a 3D game builds its
+ * physics from the raw collider JSON instead.
+ *
+ * Generated from the markdown in the origin project's `.claude/skills/converting-unity-levels/`;
+ * backticks and `${` are escaped for the template literal, and `project-files.test.ts` checks the
+ * rendered frontmatter.
+ */
+export function renderUnityLevelsSkill() {
+    return `---
+name: converting-unity-levels
+description: Convert a Unity level — a .unity scene, its prefabs, FBX models, materials and 2D/3D colliders — into a Bitmagic engine level with matching visuals (one GLB) and matching physics (collider data). Use this whenever a creator wants a Unity game or Unity scene ported, replicated, "converted to Bitmagic", "brought over", "made to look like the original", or asks to reuse original Unity assets, prefabs or level blocks — even if they only mention one symptom (pieces rotated 90 degrees, wrong scale, walls the ship flies through, a base that cannot be exited, an empty corner). Also use it when a converted level looks wrong in any of those ways, or after an engine upgrade changes how a ported level lights or collides.
+---
+
+# Converting a Unity level to Bitmagic
+
+A Unity level is three things that Unity keeps apart and the port must reunite: **placement** (the
+scene and prefab files), **art** (FBX models plus \`.mat\` files and textures), and **collision**
+(colliders on prefabs, which may be 2D or 3D). The tools in \`scripts/\` read Unity's YAML directly,
+rebuild the art in Blender into one GLB, and emit the collision as data the game builds physics
+from. Every step below exists because skipping it produced a level that looked plausible and was
+wrong — the references say which symptom each step prevents.
+
+## What this covers, and what it does not
+
+- **Visuals are general.** Scene and prefab reading, the override rules, FBX geometry, materials
+  and textures, and the Blender rebuild into one GLB apply to any Unity project, 2D or 3D.
+- **Collision extraction is general; the emitted level data is 2D-on-a-plane.**
+  \`unity_colliders2d.py\` and \`unity_extract.py\` read every 2D and 3D collider Unity has
+  (BoxCollider2D, CircleCollider2D, BoxCollider, SphereCollider, MeshCollider). \`build_parts.py\`
+  and \`write_arena_data.py\` then reduce them to a gameplay plane — walls, floors, backdrop,
+  foreground, bases — which is the right shape for a top-down or side-on game and the wrong shape
+  for a 3D one.
+- **For a 3D game**, stop after \`unity_extract.py\`: \`tools/colliders.json\` holds every collider
+  with its world transform, size, centre and mesh, and the GLB holds the art. Build the game's
+  physics from those directly (Rapier boxes and trimeshes from the same data), and skip the plane
+  emitters. That consumer does not exist yet; write it for the game at hand and it becomes the
+  next thing this skill ships.
+- **The receiving game code is not part of the skill.** \`ArenaData.ts\` is a data contract; the
+  code that builds physics bodies, occluders and stand-ins from it lives in the game. The origin
+  game's \`Arena.ts\` is a worked example of that consumer, not a library.
+
+Treat this as a **measured** conversion: after every stage, count things and render things, and
+compare with the Unity editor. A symmetry score or a passing typecheck is not evidence; a top-down
+render next to the creator's Unity screenshot is.
+
+## 0. Install the tools and describe the project
+
+The conversion scripts ship inside the Bitmagic CLI package, under \`assets/unity-import/\`. Copy
+them into \`tools/\` of the game project once:
+
+\`\`\`
+CLI_ROOT="$(cd "$(dirname "$(readlink -f "$(which bitmagic)")")/.." && pwd)"
+mkdir -p tools && cp "$CLI_ROOT"/assets/unity-import/*.py "$CLI_ROOT"/assets/unity-import/*.json tools/
+\`\`\`
+
+They need Python 3, Blender 4.x
+(\`/Applications/Blender.app/Contents/MacOS/Blender\` on macOS) and the Unity project on disk.
+
+Everything that belongs to a particular game lives in one file, \`tools/unity-import.json\`. Copy the
+example and fill it in — the scripts read it and never need editing:
+
+| Key | What it is |
+|---|---|
+| \`unityRoot\` | the Unity tree holding \`Assets/\` and \`ProjectSettings/\` (see step 1 — a repo can hold two) |
+| \`scene\`, \`levelName\` | the scene file relative to \`unityRoot\`, and the level name the game data is written under |
+| \`planeZ\`, \`planeHalf\` | the gameplay plane's Unity z and the half-thickness a collider must cross to count (the ship's radius) |
+| \`arenaLimit\` | instances farther than this from the origin are stray copies parked outside the level |
+| \`glb\`, \`assetName\`, \`outputTs\` | where the GLB is built, the asset name it is uploaded under, where the level data is emitted |
+| \`markerScripts\`, \`markerPrefabs\` | the MonoBehaviour scripts and prefab files that mark spawns, bases and pickups in this game |
+| \`badTags\` | prefab tags whose colliders are never walls (decoration that would seal a room) |
+| \`wallFamilies\` | render-mesh name families that must be solid although they carry no 2D collider |
+| \`prefabs\`, \`axisOverride\` | prefabs for non-scene conversions; a per-pack axis override for experiments |
+
+\`UNITY_IMPORT_CONFIG\` points at a different file; \`UNITY_ROOT\`, \`UNITY_PLANE_Z\` and
+\`UNITY_AXIS_OVERRIDE\` override single values for an experiment. The scripts refuse to start with
+an \`unityRoot\` that has no \`Assets/\`, and reject unknown keys, so a typo fails early.
+
+## 1. Find the right scene, and the right project tree
+
+Before extracting anything, answer three questions; on the game this skill was built from, each
+wrong answer cost a full round of work:
+
+1. **Which tree does the creator's editor open?** A repo can hold two Unity trees (a modern
+   port and a legacy one) with different \`TagManager\` layer numbering. Unity Hub's recent-projects
+   list (\`~/Library/Application Support/UnityHub/projects-v1.json\`) says which path was opened;
+   \`ProjectSettings/EditorBuildSettings.asset\` lists the scenes in the build.
+2. **Which scene?** Ask, or take the one the creator screenshots. A "Room for 10" in one tree and
+   a "Room for 9" in the other were different games entirely.
+3. **Does the scene match the creator's memory?** Instances can be parked off-map, root-inactive,
+   or under a parent group with an offset (a \`WallsLeft\` group at x = −161). Run the census in
+   step 3 before believing either the creator or the file.
+
+## 2. Decide the physics model first
+
+Open the player prefab. If it carries \`Rigidbody2D\` and \`BoxCollider2D\`/\`CircleCollider2D\`, the
+game uses Unity **2D physics**, and the only walls that exist are the 2D colliders on the level —
+the 3D \`MeshCollider\`s on the art are for raycasts and shadows and never touch a 2D body. Extract
+with \`unity_colliders2d.py\` and stop guessing from geometry. If the player is a \`Rigidbody\`, use
+the 3D path (\`unity_extract.py\` + \`build_parts.py\`, which slices MeshColliders at the plane).
+Mixing the two produced sealed bases and invisible walls; see \`references/physics-and-shadows.md\`.
+
+## 3. Extract and census
+
+\`\`\`
+python3 tools/unity_renderers.py  "<scene>.unity"   # visible geometry with world transforms
+python3 tools/unity_colliders2d.py "<scene>.unity" > tools/colliders2d.json    # 2D games
+python3 tools/unity_extract.py    "<scene>.unity" > tools/colliders.json       # 3D colliders
+python3 tools/unity_markers.py    "<scene>.unity" > tools/markers.json         # spawns, bases
+\`\`\`
+
+Then census before converting: renderers and colliders **per prefab name**, positions of the big
+structural pieces, anything beyond the arena limit, and which scene instances are switched off.
+The walkers already honour what bit the origin port — nested prefab expansion, \`m_Layer\`,
+\`m_IsActive\` and \`m_Enabled\` overrides (including on objects inside nested prefabs), parent
+groups with offsets, LOD-named objects without an LODGroup. \`references/unity-scene-traps.md\`
+lists each trap, the symptom it caused, and how the walkers handle it, so you can recognise a new one.
+
+## 4. Build the GLB
+
+\`\`\`
+python3 tools/convert_assets.py "scene:<Scene Name>"     # ~15 min; run in the background
+\`\`\`
+
+It writes \`build/glb/<scene>.glb\`, one draw call per material, textures capped and JPEG-compressed.
+The FBX rules that took longest to get right — geometric transforms, Unity's X negation, unit
+scale, multi-mesh files, ASCII FBX — are in \`references/fbx-conversion.md\`. When a piece looks
+rotated or scaled wrong, read that file before touching axis permutations: the fix was never a
+permutation.
+
+Immediately render it and look:
+
+\`\`\`
+blender -b --python tools/render_topdown.py -- build/glb/<scene>.glb .bitmagic/topdown.png
+\`\`\`
+
+Put the render next to the creator's Unity screenshot. Crosses, corners, perimeter, statue — if
+any differ, fix them now, not after the physics is built on top.
+
+## 5. Emit collision and gameplay data
+
+\`\`\`
+python3 tools/write_arena_data.py "<Scene Name>"      # -> src/work/ArenaData.ts
+bitmagic check
+\`\`\`
+
+For geometry that must be solid but has no collider in Unity (a decorative perimeter ring a 2D
+ship would fly through), slice the render mesh at the play plane instead of inventing boxes:
+
+\`\`\`
+blender -b --python tools/mesh_walls.py -- build/glb/<scene>.glb tools/render_walls.json
+\`\`\`
+
+Then run the **reachability flood** (in \`references/verification.md\`): every spawn must reach
+the same connected region. A level that seals when a wall is "fixed" is telling you the scene
+differs from what you think — investigate, do not patch.
+
+## 6. Upload, verify, confirm on screen
+
+\`\`\`
+bitmagic assets add build/glb/<scene>.glb --name <asset-name> --keep-glb --asset-id <id>
+bitmagic verify && grep -q "\\[YourGame\\] loaded" .bitmagic/verify/console.log
+\`\`\`
+
+\`verify\` passing means the game boots. It does not mean the walls are where the art is, the
+crosses cast solid shadows, or the statue is the right size. Drive the running game in the
+browser pane, get past the pre-match menus, teleport the ship next to the thing in question, and
+look — \`references/verification.md\` has the exact moves, and the two traps that once let three
+"fixes" be presented that had not reached the browser.
+
+## 7. Iterate with patches, not rewrites
+
+Genuine gameplay edits (move a corner block so it overlaps the wall, remove a stray instance) go in
+\`tools/level_patches.json\` and are applied identically by the visual and collider walkers. Every
+entry that file ever held before the corner-block one turned out to be a walker bug in disguise:
+when a patch is needed to make Unity's own scene coherent, suspect the extraction first.
+
+## Where the deep material is
+
+| Read when… | File |
+|---|---|
+| a piece is missing, doubled, parked, rotated by a parent, or "not in Unity" | \`references/unity-scene-traps.md\` |
+| pieces are rotated, mirrored, wrongly scaled, or a multi-mesh FBX picks the wrong mesh | \`references/fbx-conversion.md\` |
+| walls do not collide, a base seals, shadows leak or floors cast, lights vanish after an upgrade | \`references/physics-and-shadows.md\` |
+| deciding whether a change is real: census, render, flood, browser drive, stale-server checks | \`references/verification.md\` |
+`;
+}
+/** `<skills dir>/converting-unity-levels/references/unity-scene-traps.md` */
+export function renderUnityLevelsTrapsReference() {
+    return `# Reading Unity scenes and prefabs: the traps, by symptom
+
+Unity's YAML is readable without Unity, but the *meaning* of a scene is spread across prefab
+files, \`.meta\` files, \`ProjectSettings/TagManager.asset\` and per-instance override lists. Every
+entry below was found by a wrong level during the port this skill comes from, in the order the
+walkers now handle them.
+
+## Symptom → cause → what the walker does
+
+| Symptom in the port | Cause in the Unity data | Handling |
+|---|---|---|
+| Walls treated as decoration, or decoration treated as walls | Layer numbers guessed by majority; the repo held two project trees with different \`TagManager\` numbering | \`build_parts.layer_index(name)\` resolves \`Terrain\`, \`Shadows\`, … by NAME from the tree in \`UTOPOS_UNITY_ROOT\` |
+| A prefab arrives with 6 of its 56 colliders, or a Towers prefab arrives empty | Nested prefab instances (class \`1001\`) show up in their parent's \`m_Children\` only as stripped stubs the transform walk cannot follow | Every expanded file is swept for its own \`1001\` records (\`expand_file\` / \`RendererWalk.expand\`); never guard on \`(path, transformId)\` — that blocked the 2nd..nth instance of the same prefab |
+| 167 "walls" that seal a base shut | The same geometry exists twice: the visible copy and a low-poly stand-in on the SHADOWS layer (18), placed with the same transform; the stand-in's layer is a per-instance \`m_Layer\` override | \`go_layer(docs, goid, mods)\` honours the override; layer 18 is excluded from visuals and from physics |
+| Tower blocks in front of every base exit; a ring of bars that seals the arena when completed | Every \`Towers\` and \`Long Side Wall\` instance is **root-inactive** in the scene (\`m_IsActive: 0\` on the prefab root), so Unity never shows them | \`go_active(docs, goid, mods)\` honours \`m_IsActive\` overrides; \`prefab()\` skips an instance whose root is off |
+| A component behaves as if enabled when Unity has it off (or vice versa) | \`m_Enabled\` overrides target the component; when the component lives inside a *nested* prefab, the target id is \`(nestedObjectFileID ^ nestedInstanceFileID) & 0x7FFFFFFFFFFFFFFF\` in the outer file's namespace | \`instance_mods()\` re-keys outer overrides into the nested file's ids as it descends — verified on the Barrier: its override hit a 3D MeshCollider, leaving the 2D strip live |
+| A whole wall "parked" at x = −161, or spawners at (50, 1171, 2004) | Scene-level instances sit under parent groups with their own transforms (\`WallsLeft\`, \`Spawners\`); the placement is local to the group | Compose the parent chain (\`expand\` walks \`m_Father\` up to the root, applying each group's TRS) — and then *believe* the composed position: \`WallsLeft\` really is parked off-map |
+| Corners and the middle of every side empty while Unity shows them | 16 objects named \`…_L2\` placed by hand under plain groups (\`TunnelTop\`, \`CornerTower*\`); the Sci-Fi Base pack ships one FBX per LOD level | \`_is_lod_child\` only drops a LOD-named object when its parent carries an LODGroup (class 205) |
+| A statue 141 units long, or the wrong statue | A multi-mesh FBX (\`GatheredStatues.FBX\`, 8 meshes); the MeshFilter's \`fileID\` (\`43000xx\`) maps to a mesh name through the FBX's \`.meta\` table | \`mesh_index_for(fbx, fileId)\` reads the \`.meta\`; the reader returns meshes in file order |
+| The "corner element" that is not in the extracted data | The perimeter ring and corner towers are **plain scene GameObjects**, not prefab instances | Both walkers walk scene-native objects too; a census by prefab name alone never lists them — census renderers by mesh family as well |
+| A sealed inner arena after adding the one bar that "should" be there | The scene as checked out really has only three bars; the fourth was never placed | Treat a level that only becomes coherent with a patch as evidence that the extraction, not the scene, is wrong — see the flood in \`verification.md\` |
+
+## The census (run it before converting anything)
+
+For the scene and every prefab it places, print:
+
+- instances per prefab name, with world positions of the structural ones (bars, towers, crosses,
+  bases), and anything beyond the arena limit;
+- top-level groups and their transforms (a non-zero group transform moves everything under it);
+- objects that are inactive (\`m_IsActive: 0\`) and instances that override \`m_IsActive\` /
+  \`m_Enabled\` / \`m_Layer\`, with what the override targets;
+- renderers by mesh family (the \`_L2\`, \`Tunnel\`, \`Staircase\`, \`Floor\` stems), with counts and
+  extents — this is how the missing corners were found;
+- the collider inventory of the key prefabs: kind (Box2D/Circle2D/Box3D/Mesh3D), layer, active,
+  enabled, trigger.
+
+Compare those counts with the built GLB (Blender can list objects by name and extents) and with
+the creator's Unity screenshot. Counts that agree and a picture that does not means a transform
+bug; counts that disagree means a walker bug. Both are cheaper to find at this stage than after the
+physics is layered on top.
+
+## Which tree, which scene
+
+\`ProjectSettings/EditorBuildSettings.asset\` lists the scenes a tree builds; Unity Hub's
+\`projects-v1.json\` lists the paths the creator actually opened. \`Library/\` is created when Unity
+opens a project but is often deleted or ignored, so its absence proves nothing. When a pulled
+commit changes nothing in the scene yet the creator's screenshot differs, the screenshot is of
+another scene or tree — or of this scene with the overrides above honoured.
+`;
+}
+/** `<skills dir>/converting-unity-levels/references/fbx-conversion.md` */
+export function renderUnityLevelsFbxReference() {
+    return `# Rebuilding Unity art from FBX: the rules that produce Unity's mesh
+
+Unity does not render the FBX as authored. It applies an import pipeline, and the GLB must
+reproduce that pipeline, not the file. These are the rules, each learned from a piece that was
+"rotated 90 degrees", mirrored, split in half, or a quarter of its size.
+
+## Coordinates
+
+- Unity is left-handed, Y up, camera looking down +Z for this 2D-on-a-plane genre. Blender's FBX
+  importer maps Unity (x, y, z) to Blender (x, z, y); glTF export from Blender gives the engine
+  (ux, uy, −uz). \`Arena.ts\` uses that depth convention, so "Unity z" reads as \`−z\` in the game.
+- **Unity negates X on FBX import** (right-handed to left-handed). The reader applies
+  \`(−x, y, z)\` to every vertex (\`UNITY_NEGATE_X\`), and \`blender_build\` uses signs \`(−1, 1, 1)\`.
+  This was the residual mirror that split the round end caps: the \`Top_1_H\` tips only join into a
+  half-round with X negated. Do not apply it twice — the collider path once did (reader plus
+  \`apply_permutation\`) and every collider landed mirrored.
+- Unity's own glTF exporters (UnityGLTF, glTFast) do the same with scale (−1, 1, 1) and
+  quaternion (x, −y, −z, w); that is the cross-check when in doubt.
+
+## Geometric transforms (the 90-degree bug)
+
+3ds Max exports put a **geometric transform** on the Model node — \`GeometricRotation\`,
+\`GeometricTranslation\`, \`GeometricScaling\` — that applies to the mesh vertices only, not to
+children. Unity bakes it into the mesh asset. The Euler order is XYZ, composed as Rz·Ry·Rx, and
+was verified against Unity's own BoxCollider boxes (21 of 30 off-centre boxes match only with that
+order). \`Wall_7\` reproduces Unity's box exactly: lo (−1, −0.003, −0.042), hi (1, 2.597, 0.042).
+
+Blender's importer folds the geometric transform into the **object** matrix. \`bake_to_blender\`
+works from the raw vertices and applies the geometric matrix itself, so it must take only the unit
+scale from the object — and divide \`GeometricScaling\` back out of \`matrix_world.to_scale()\`,
+otherwise that scaling is applied twice. That is exactly why the centre statue (GeometricScaling
+0.28) came out at a quarter of its size while the Pack pieces (GeometricScaling 1) hid the bug.
+
+## Axis permutations: do not derive them
+
+An earlier version derived a per-pack axis permutation from collider sizes or from a symmetry
+score of the assembled level. Both are blind to a uniform rotation or mirror of every piece, so
+they happily chose a "best" permutation that rotated everything 90 degrees. The real causes were
+the two rules above. \`fbx_axis.py\` now returns the identity with X negated
+(\`DEFAULT_TRANSFORM = ((0,1,2), (−1,1,1))\`); \`UTOPOS_AXIS_OVERRIDE="Pack=cycYZX:-1,1,1"\` exists
+for a pack that genuinely needs one, and the test of "needs one" is a Unity BoxCollider box that
+does not match — never a picture that "looks more symmetric".
+
+## Units and scale
+
+A mesh asset in Unity is: raw vertices × baked geometric transform × **file unit scale**
+(\`useFileScale: 1\` in the \`.meta\` times the FBX \`UnitScaleFactor\` / 100 — \`GatheredStatues.FBX\` is
+in inches, factor 2.54). Nothing from the node's own \`Lcl Scaling\` reaches a mesh asset; that
+lands on the imported GameObject, which a hand-built prefab does not use. \`read_fbx\` returns the
+unit factor alongside the meshes; check \`.meta\` \`globalScale\` too.
+
+## Multi-mesh files and ASCII files
+
+- A MeshFilter references a mesh by \`fileID\` (\`43000xx\`); the FBX \`.meta\` maps those to mesh
+  names in file order. \`mesh_index_for\` does the lookup — without it the walker picks the first
+  mesh, which is how a 141-unit statue appeared.
+- The ship packs are ASCII FBX 6100 from Blender 2.71, which Blender no longer imports;
+  \`fbx_ascii.py\` reads the handful of arrays that matter (vertices, polygon index, one material).
+
+## Materials and textures
+
+The FBX's embedded texture paths point into the vendor's authoring tree. What Unity renders is the
+Renderer's \`m_Materials\` GUID list → \`.mat\` → texture GUIDs; \`unity_assets.py\` resolves that
+chain. In Blender: textures capped (512 colour / 256 other) and JPEG q80 (a 68 MB GLB became
+0.33 MB); emissive only when the material enables it (\`_EMISSION\` / \`_UseEmissiveIntensity\`),
+preferring \`_EmissiveColor\` over \`_EmissionColor\` — otherwise the whole arena whites out; metalness
+capped at 0.45 because the arena is lit by the ship's lamp alone and full metal renders black.
+
+## Checking a converted piece
+
+1. Its Unity BoxCollider box (from the prefab) against the mesh bounds the reader produces — the
+   only objective test of orientation and scale.
+2. One piece with a known shape (an end cap, a cross bar) rendered from above next to the Unity
+   editor view.
+3. Family extents in the finished GLB (Blender lists objects by name) against the census.
+`;
+}
+/** `<skills dir>/converting-unity-levels/references/physics-and-shadows.md` */
+export function renderUnityLevelsPhysicsReference() {
+    return `# Physics, walls and line-of-sight shadows
+
+## Decide 2D or 3D from the player, not from the art
+
+Open the player prefab. In the game this skill was built from, the player was a \`Rigidbody2D\` with
+two \`BoxCollider2D\` and a \`CircleCollider2D\` (radius 0.8). Unity's 2D physics only ever collides
+2D colliders with 2D colliders, so for such a game the playable walls are the small
+designer-authored set of \`BoxCollider2D\` / \`CircleCollider2D\` on the level prefabs (there: tower
+blocks, cross bars at 45° with circle tips, base door posts, barrier strips). The 3D
+\`MeshCollider\`s on the art serve the land-check sphere-cast and shadows and never touch the ship.
+Building physics from the 3D colliders (box-approximated, then triangle-rasterised) produced sealed
+bases and walls of air; switching to the 2D set fixed both in one step and made every wall nameable.
+
+\`unity_colliders2d.py\` emits \`{kind: box, cx, cy, hw, hh, rot}\` and \`{kind: circle, cx, cy, r}\`
+with layer, trigger flag and prefab tag. \`write_arena_data.py\` turns them into \`ARENA_BOXES\` /
+\`ARENA_CIRCLES\`; \`Arena.buildWalls\` makes a fixed body per collider (\`cuboid(hw, hh)\` with
+\`setRotation(rot)\`, \`ball(r)\`), and an axis-aligned bound per collider for the flood and the
+wall-hit log. Respect the Physics2D collision matrix (players hit Default and Terrain, not Shadows)
+and skip triggers.
+
+## Rapier needs to be told to report contacts
+
+\`PhysicsWorld2D.createCollider\` does not enable collision events. Without
+\`.setActiveEvents(R.ActiveEvents.COLLISION_EVENTS)\` on the ship's collider, no wall-hit callback
+ever fires — wall damage and ship-ship damage silently never worked. Keep \`setCcdEnabled(true)\`
+too; a fast ship tunnels through a 0.8-thick bar otherwise.
+
+## Geometry that must be solid but has no collider
+
+The perimeter tunnel ring is plain scene decoration a 2D ship flies through. Rather than invent
+boxes, \`mesh_walls.py\` slices the *render* mesh at the play plane inside Blender: sample every
+triangle crossing a thin slab (half-depth 0.45 — wide enough for the walls, narrow enough to miss
+the tunnel floor at depth 0, which otherwise fills the corridor solid), rasterise at 0.5 units,
+close one-cell holes, merge greedily into rectangles. \`write_arena_data.load_2d\` appends the result
+as axis-aligned boxes. Re-run it after every GLB rebuild that moves that geometry, and keep the
+\`FAMILIES\` tuple to what genuinely needs it.
+
+## Line-of-sight shadows: casters are the collision set
+
+The original lit the arena from the player and projected a shadow-camera render back as a
+visibility mask. The port does it with two shadow-casting point lights on the ship (a warm lantern
+with falloff, a cool decay-0 fill whose shadow map *is* the mask). What casts matters more than
+what receives:
+
+- Let the **collision set** cast, not the art. \`Arena.buildOccluders\` extrudes every 2D collider
+  and every sliced wall through the plane (z −8 … +8) into one merged mesh with a material that
+  writes neither colour nor depth, \`castShadow = true\`; every art mesh has \`castShadow = false\`.
+  This fixed two complaints at once: floor decks a hair behind the plane no longer darken the map,
+  and a cross built of many small pieces no longer leaks light between them.
+- Consequence to state explicitly: anything that is not a collider no longer occludes. In the
+  origin game the base walls were not colliders (only their door posts were), so a ship inside a
+  base lit the level around it. Unity's own SHADOWS layer held only the cross stand-ins, so this is closer to the
+  original than art-casting was — but it is a design decision the creator should make.
+- Visibility map 512 once the casters are a few hundred blocks; the six cube faces are cheap then.
+
+## Lighting configuration, and what an engine upgrade does to it
+
+- The engine reads scene lighting from \`worldProfileData.lightingConfig\` (\`sunIntensity\`,
+  \`sunColor\`, \`environmentIntensity\`, \`skyboxIntensity\`, \`ambientFloor\`). A block under any other
+  key is silently ignored and the sun runs at its daylight default of 5.0, colour-compensated —
+  bright enough to wash the shadow mask out entirely.
+- The game's own \`dimSceneLighting\` then scales every non-ship light by 0.35, sun included, so the
+  effective sun is \`5 / luminance(sunColor) × sunIntensity × 0.35\`.
+- After the upgrade from engine 3.1094 to 3.1122 the same point light read roughly **eight times
+  weaker** (three.js itself unchanged). The fill at 2.6 no longer reached the arena; 22 restored
+  the mask, 35 blew the deck out. Re-measure after every engine upgrade before trusting the
+  constants in \`VisibilityLight.ts\` — and measure in the running game, not by reasoning about it
+  (see \`verification.md\`).
+`;
+}
+/** `<skills dir>/converting-unity-levels/references/verification.md` */
+export function renderUnityLevelsVerificationReference() {
+    return `# Verifying a conversion: what counts as evidence
+
+The order of trust, highest first: a gameplay frame you took yourself → a top-down render next to
+the Unity editor → counts and extents from the data → \`bitmagic verify\` → a typecheck. During the
+port this skill comes from, three "fixes" were presented on the strength of the bottom three and
+none had reached the creator's screen.
+
+## Data checks
+
+- **Census** (see \`unity-scene-traps.md\`): per-prefab instance counts, group transforms, inactive
+  and overridden instances, renderer families with extents.
+- **Collider map**: draw every solid 2D collider (oriented boxes, circles, sliced walls) and the
+  spawns as a PNG; a ring with a missing side or a strip in the middle is obvious at a glance.
+- **Reachability flood**: rasterise the wall bounds (plus the arena boundary) at 0.25 units,
+  inflate by the ship radius, flood-fill from every spawn, and report the reachable fraction per
+  spawn. Every spawn must reach the same region; a spawn "IN WALL" or a 31 % / 69 % split means a
+  sealed arena. A level that only becomes coherent after adding or removing a wall is telling you
+  the scene differs from your reading — go back to the census.
+- **GLB inventory**: Blender lists objects by name family with extents (\`Tunnel 52 where Unity has
+  56\`, \`Staircase 0\`) — the fastest way to see what the visual walker dropped.
+
+## Renders
+
+\`\`\`
+blender -b --python tools/render_topdown.py -- build/glb/<scene>.glb .bitmagic/topdown.png
+\`\`\`
+
+Orthographic, whole arena; crop a corner or the centre when the question is local. Put it beside
+the creator's Unity screenshot; that comparison found the missing left bar, the empty corners and
+the tiny statue. Billboard textures may read mirrored in the render — cosmetic.
+
+## In the running game (the browser pane)
+
+Open \`http://localhost:<gamePort>/\` (from \`.bitmagic/dev.json\`). Then:
+
+- The pre-match menus must be clicked through: game mode, opponents, Launch. At 800×450 the
+  buttons sat at (400, 264), (352, 302), (400, 325); take a screenshot first — coordinate clicks
+  need one — and re-check positions if the HUD changes.
+- Shader warm-up after a cold reload takes 2–3 minutes in the pane. \`computer.wait\` caps at
+  10 s; chain several.
+- The engine is reachable as \`window.gameTemplate.getGameEngine()\`: \`.scene\` (traverse for lights
+  and meshes), \`.renderer\` (shadow map state), \`.directionalLight\`, \`.currentLightingConfig\`,
+  \`.genreModule\` (this game's module: \`.player.body.setTranslation({x, y}, true)\` teleports the
+  ship next to whatever needs looking at; \`.started\` / \`.phase\` say whether the match runs).
+- A/B toggles beat reasoning: switch \`castShadow\` off on the ship lights and screenshot; set an
+  intensity to 100 and screenshot. Two frames settled in minutes what probes could not.
+
+## Two ways a change fails to reach the screen
+
+1. **The dev server serves a stale module.** \`bitmagic dev\` serves \`/dist/src/work/*.js\` (tsc
+   watch output). It kept serving a 4,579-byte copy of \`VisibilityLight.js\` after the file on disk
+   was 5,132 bytes with new constants — even to \`fetch(..., {cache: 'reload'})\`, so forced page
+   reloads and \`bitmagic reload\` still ran old code. Check with
+   \`curl localhost:<port>/dist/src/work/<File>.js | grep <constant>\`; if stale, restart the dev
+   server (\`kill $(jq .pid .bitmagic/dev.json)\`, then \`bitmagic dev --port … --editor-port …\` in
+   the background) and force-navigate. Never touch a port another project's dev server owns.
+2. **Verify passed on fallback geometry.** During a network drop the arena GLB failed to fetch and
+   the game kept procedural stand-ins; verify still passed. Grep the verify console for
+   \`arena model failed to load\` and for your own \`[Game] loaded\` line
+   (\`grep -q "\\[YourGame\\] loaded" .bitmagic/verify/console.log\`) before trusting a screenshot.
+
+## Presenting
+
+Say what was measured, with the number, and what was only inferred. If the creator is the judge
+of a look (brightness, size, "large"), give them the single knob and its range rather than a
+value dressed up as a restoration.
+`;
+}
+//# sourceMappingURL=unity-skill-files.js.map

package/dist/scaffold/unity-skill-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unity-skill-files.js","sourceRoot":"","sources":["../../src/scaffold/unity-skill-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,UAAU,sBAAsB;IACpC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgLR,CAAC;AACF,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,+BAA+B;IAC7C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDR,CAAC;AACF,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,6BAA6B;IAC3C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2ER,CAAC;AACF,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,iCAAiC;IAC/C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoER,CAAC;AACF,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,sCAAsC;IACpD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkER,CAAC;AACF,CAAC"}

package/dist/scaffold/upgrade-project.d.ts

@@ -1,3 +1,4 @@
+import { type AgentId } from './agent-targets.js';
 import { type AgentsMdOutcome } from './agents-md.js';
 import { type RepointedAsset } from './legacy-default-assets.js';
 export interface UpgradeOptions {
@@ -13,6 +14,13 @@ export interface UpgradeOptions {
      * answer in a committed file.
      */
     environmentToPin?: string;
+    /**
+     * Agents to ADD to the project's recorded set, from `--agent`. Unioned with whatever
+     * `bitmagic.json` already says and persisted, because "I also use Kiro" is a fact about the
+     * project rather than an aim for one command — the opposite of `--env`, which is deliberately not
+     * persisted. Nothing is ever removed: see `agent-targets.ts`.
+     */
+    addAgents?: readonly AgentId[];
 }
 export interface UpgradeResult {
     engineVersion: string;
@@ -33,6 +41,20 @@ export interface UpgradeResult {
      * never silent.
      */
     environmentPinned?: string;
+    /** The agent set this run wrote for, after unioning the recorded set with `--agent`. */
+    agents: AgentId[];
+    /**
+     * The agents just added to bitmagic.json, when any were — including the backfill a project
+     * scaffolded before the field existed receives. Reported for the same reason
+     * `environmentPinned` is: a permanent write to a committed file is never silent.
+     */
+    agentsAdded: AgentId[];
+    /**
+     * Values in the project's `agents` field this CLI does not recognise — a hand edit, or a newer
+     * CLI's. Reported and otherwise ignored, exactly as an unrecognised `environment` is: refusing to
+     * upgrade would be a strange way to report a typo.
+     */
+    agentsUnknown: string[];
     /**
      * The platform-owned default assets in `src/work/world.json` that were repointed from their
      * legacy JSON files to the VXL3 ones. Empty when there was nothing to repoint. This is the one
@@ -72,17 +94,15 @@ export interface UpgradeResult {
  * ever deleted, so a skill we stop shipping stays behind rather than being cleaned up — a stale
  * file being much cheaper than deleting one a creator wrote.
  *
- * Mirrors scaffoldProject's copy behaviour (same VENDORED_DIRS loop, same corrupt-tarball error
- * when a directory is missing from the extracted tree), except it clears engine/ first: unlike a
- * brand new project's empty target, an existing engine/ may hold files a since-removed
- * VENDORED_DIRS entry left behind, or a leftover from a bad manual edit, and cpSync alone would
- * merge over those rather than remove them.
+ * Mirrors scaffoldProject's copy behaviour (same VENDORED_DIRS loop, same
+ * `assertEngineBundleComplete` check), except it clears engine/ first: unlike a brand new
+ * project's empty target, an existing engine/ may hold files a since-removed VENDORED_DIRS entry
+ * left behind, or a leftover from a bad manual edit, and cpSync alone would merge over those
+ * rather than remove them.
  *
- * That "clear first" step is exactly why every VENDORED_DIRS source is validated to exist
- * *before* engine/ is touched at all, in its own pass below: scaffoldProject can afford to check
- * existence inside its copy loop because its target starts empty, so a missing source just leaves
- * a partially-populated (but otherwise harmless) new directory. Here the target is a live
- * project's engine/, already rm'd — the same ordering would demolish it and fail partway through
- * repopulating it, and a project not under version control has no way to recover that.
+ * That "clear first" step is what makes the up-front validation load-bearing here rather than
+ * merely tidy: the target is a live project's engine/, already rm'd, so a check inside the copy
+ * loop would demolish it and fail partway through repopulating it — and a project not under
+ * version control has no way to recover that.
  */
 export declare function upgradeProject(options: UpgradeOptions): UpgradeResult;