lecodes-assets 0.2.1 → 2.5.0

package/README.md

@@ -4,6 +4,10 @@ FBX → GLB converter + GLB doctor, one package on one glTF-Transform `Document`
 `lecodes assets …` (optional peer of the `lecodes` CLI) or `bun src/cli.ts …` in the monorepo.
 Plan/rationale: [docs/animation-plan.md §2.9](../../docs/animation-plan.md).
 
+`lecodes assets` lists the commands, `lecodes assets <command> --help` prints one command's flags
+(`lecodes assets unreal tex --help` for a subcommand). The help is generated from the command
+declarations, so it is always the full and current list — this README explains the workflows.
+
 Install it the same way you installed the CLI — the peer is loaded by a bare `import` that resolves
 upward from the CLI's own file, so a global `lecodes` only sees a global peer:
 
@@ -11,18 +15,22 @@ upward from the CLI's own file, so a global `lecodes` only sees a global peer:
 npm install -g lecodes-assets
 ```
 
-KTX2 (`--ktx2`) additionally needs KTX-Software's `toktx` on PATH; `sharp` is an optional dependency
-used to normalize exotic texture formats.
+KTX2 (`--ktx2`) additionally needs [KTX-Software](https://github.com/KhronosGroup/KTX-Software/releases):
+its `toktx`, or — where there is none, e.g. KTX-Software 5 / the macOS installer — its `ktx` tool
+(`ktx create`, ≥ 4.4). Looked up at `KTX_TOKTX` / `KTX_TOOL`, the installer's folder
+(`%LOCALAPPDATA%\Programs\KTX-Software\bin`, `/usr/local/bin`, `/opt/homebrew/bin`), then PATH.
+`sharp` is an optional dependency used to normalize exotic texture formats.
 
 ```
 lecodes assets convert "Erika Archer.fbx" --clips Idle.fbx Walking.fbx "Fast Run.fbx" --drop-model-clips -o hero.glb
 lecodes assets convert hero.glb --clips Jump.fbx                 # add clips to an existing GLB
 lecodes assets convert hero.fbx --fix                            # + doctor passes (bone cap, texture normalize)
-lecodes assets convert hero.fbx --ktx2                           # + textures → KTX2 (needs KTX-Software toktx)
+lecodes assets convert hero.fbx --ktx2                           # + textures → KTX2 (needs KTX-Software)
 lecodes assets probe hero.fbx | hero.glb                         # skeleton / clips / meshes / textures / bind sanity / world size
 lecodes assets doctor hero.glb [--fix] [--ktx2] [--dump]         # the old tools/glb-reduce
 lecodes assets doctor hero.glb --fix-scale                       # bake a unit fix (see Scale below)
-lecodes assets doctor props/*.glb --lightmap-uv -o props/         # + TEXCOORD_1 lightmap UVs (xatlas) for `lecodes lightmap bake`
+lecodes assets unwrap props/                                     # TEXCOORD_1 lightmap UVs (xatlas), in place (see Lightmap UVs below)
+lecodes assets doctor hero.glb --merge [--atlas-size 4096]       # ONE draw call: parts → one primitive, maps → atlases (see Merge below)
 lecodes assets retarget fox.glb --from wolf.fbx --map auto       # clips from a DIFFERENT skeleton (map from skeleton shape)
 lecodes assets avatar girl.glb --meta SK_Girl.fbx.meta           # a humanoid's bones in the Unity/VRM canon (vs Unity's own map)
 lecodes assets unpack pack.unitypackage -o out [--only re …]      # stream a .unitypackage: unity-index.txt + assets (+ .meta)
@@ -31,9 +39,11 @@ lecodes assets convert Barrel_v1.FBX --keep Barrel_v1_LD1 -o barrel.glb   # one
 lecodes assets convert Barrel_v1.FBX --split props/              # every top-level node → its own GLB
 lecodes assets convert Body.FBX --merge-skins Shirt.FBX Gloves.FBX --clips … -o hero.glb   # modular character → ONE skeleton
 lecodes assets probe hero.glb --filmstrip                        # a CPU-skinned PNG strip per clip (no GPU)
-lecodes assets scene Map_v8.unity -o level.json                  # Unity scene → placed prefabs with world TRS
+lecodes assets scene Map_v8.unity -o level.json                  # Unity scene → kinds + placements as JSON
+lecodes assets scene Outdoor.unity --project . --name school     # …or built INTO a LeCodes project (GLBs + scene files)
 lecodes assets unreal ls "Stairs Set/StairsSet"                  # what an UNREAL pack holds (see below)
 lecodes assets unreal tex T_Manny_01_D.uasset -o manny_d.png     # a texture's SOURCE image (needs Oodle, see below)
+lecodes assets unreal wav EngineSfx/Sound -o assets/engine --ogg  # every SoundWave's imported WAV → mono OGG (Oodle + ffmpeg)
 lecodes assets convert SKM_Manny.uasset --clips Anims/**/*.uasset -o manny.glb   # Unreal mesh + clips → GLB
 ```
 
@@ -63,20 +73,85 @@ renders a software-skinned PNG strip of every clip (`--clip` for one, `--frames
 side|front|top|threequarter|lowfront`, `--bones` for the skeleton overlay, `--cell` px per frame);
 `tools/filmstrip.ts` is the same renderer with reference frames from other files.
 
-**Unity scenes.** `scene Map.unity [-o level.json]` reads a text-serialised scene: every
-`PrefabInstance` (source prefab GUID, the position/rotation/scale/name/active overrides, its parent)
-and every `MeshFilter` object, composes the scene's own `Transform` hierarchy on top (groups like
-`Static/Roads`), and writes the instances with their **world** TRS plus a prefab table — path, use
-count, and a guess at the FBX + `--keep` node that renders it (the FBX from the prefab's folder /
-`Source/` whose stem prefixes the prefab name; most packs ship their prefabs binary-serialised, so
-the prefab's own contents are not read). Frame: Unity is left-handed and its FBX importer mirrors X,
-so the default undoes that — position `(−x, y, z)`, quaternion `(x, −y, −z, w)` — `--handedness z`
-mirrors Z instead (content authored inside Unity), `none` keeps Unity's numbers. Subsets:
-`--filter <re>` (prefab path / name / group), `--group <name>`, `--region x0,z0,x1,z1` (Unity
-metres), `--include-inactive`. A parent that sits inside a binary prefab resolves to that prefab's
-root and the instance is marked `approximate`. The output is plain JSON:
-`{ prefabs: { guid: { path, name, fbx, node, count } }, instances: [ { name, prefab, group,
-position, rotation, scale } ] }` — one `Model.load` per prefab, one `clone()` per instance.
+**Unity scenes.** `scene Map.unity` reads a text-serialised scene and expands it the way the Unity
+editor shows it: nested `PrefabInstance`s cloned from their source prefabs (a model file is a prefab
+too), their `m_Modifications` applied, stripped stubs resolved. Every placed prefab becomes a **kind**
+— its mesh parts with the material GUIDs per submesh, LOD levels, colliders, lights — keyed by
+CONTENT, so two instances of one prefab share a kind unless the scene overrode something inside one
+of them (that one becomes `<Kind>_v2`). Kinds stop at nested prefab roots: a wall built from rock
+prefabs is placements of the rocks. The terrain is read from its binary `TerrainData` (heights, splat
+layers merged down to four by coverage; an HDRP layer's smoothness — the mask map's alpha × `m_Smoothness` —
+becomes the roughness map in the albedo's alpha, `1 − smoothness`, which is where terrain.mat reads it),
+its painted trees and detail meshes become placements too. A VEGETATION kind (the `--foliage` list, or the
+importer's folder / name rule) keeps its vertex colours as DATA and gets its sky visibility baked into them at
+import — `COLOR_0 = (ao, 1, 1, wind weight)`, what foliage.mat reads (`src/doctor/vertexAo.ts`); a material that
+draws a DETAIL layer through another UV set (NatureManufacture's bark: `_DETALUSEUV3_ON` under a white
+`_DetailMask`) takes that layer's textures on TEXCOORD_0 = that set × its tiling. Output without `--project` is
+plain JSON: `{ kinds, instances: [ { kind, name, group, position, rotation, scale } ], lights,
+cameras, terrain, stats }`.
+
+`--project <dir> [--name map]` builds it INTO a LeCodes project instead: `assets/<map>/<Kind>.glb`
+(meshes pulled from the FBX files, materials written from the `.mat` files the renderers name,
+textures capped by `--max-size` and KTX2 unless `--png`), `src/<map>/<Kind>.scene.ts` (the model +
+its colliders as `Shape` / `Physics` aspects), `assets/<map>/terrain/…` and `src/<map>.scene.ts`
+placing everything, grouped like the Unity scene. GLBs are rebuilt only when their kind changed
+(`assets/<map>/kinds.json`) or with `--force`. Everything is regenerated by the next import — a game
+level instances `src/<map>.scene.ts` as a prefab and adds its gameplay there. **The command line is
+written into that file's header: re-import with the same line**, because the flags carry decisions
+the file cannot show — `--collider-fit <m>` (how far a pack's BOX collider face may stand off the
+art before the kind takes a mesh collider instead, default 1.5 cm: the shooting range's wall module is
+flat at ±0.100 m while its box was fitted to the ±0.138 m of its trim, so bullets stopped 3.8 cm in
+front of the wall and their holes and sparks landed in mid-air), `--drop <re>` (props a pack sinks into the geometry they decorate), `--drop-at
+"x,y,z;…"` (the placements standing at these points, in the frame the scene file prints: the one instance
+of a kind the game moves while its namesakes stay — the range's five lane targets),
+`--no-lightmap <re>` (lamp fixtures and anything the game moves take `lightmap: false`), `--foliage
+<re>` / `--no-foliage` (which kinds wear the vegetation tier; the default verdict — a material in a
+Vegetation/Plants/Grass/Trees folder or named so — is printed), `--no-sun`, `--no-trim-cards`,
+`--max-tris <n>` (a kind over this many triangles is simplified at import, default 50 000, 0 = no cap:
+a photogrammetry scan otherwise arrives as a million-triangle prop AND mesh collider — a faceted scan
+loses its per-face normals to weld and gets smooth ones back; its detail is in the normal map).
+Shader Graph materials whose textures go through a **Triplanar** node (URP walls and floors) get the
+projection baked into their UVs — the node's own planes and Tile — so they stay stock PBR and can
+take part in a lightmap bake.
+Subsets: `--filter <re>` (kind / group / node name), `--group <name>`, `--region x0,z0,x1,z1` (Unity
+metres), `--no-trees`, `--no-details`, `--include-inactive`.
+
+Frame: Unity is left-handed and its FBX importer mirrors X, so everything read from Unity is
+conjugated by that mirror — position `(−x, y, z)`, quaternion `(x, −y, −z, w)` — while mesh geometry
+comes from the FBX itself, which already is right-handed (`--handedness none` keeps Unity's numbers).
+Two importer rules matter for models whose FBX has a single top node that IS the mesh (the prefab's
+root in Unity): its position and rotation are never the model's — every `PrefabInstance` overrides
+them — and what does survive is the model importer's `bakeAxisConversion`, which bakes `RotY(180°) ·
+R_node` into the mesh (a Blender export's Z-up→Y-up correction lives there; without it the doors of a
+kit stand beside their doorways).
+
+A re-import renames nodes, so a **baked lightmap is invalid after it** — re-bake the level. The
+imported GLBs carry no lightmap UVs; `lecodes lightmap bake` unwraps them itself (below).
+
+## Lightmap UVs — `unwrap`
+
+```
+lecodes assets unwrap assets/props                                # every GLB in the folder, in place
+lecodes assets unwrap "assets/school/*.glb" --force               # again, over the sets they have
+lecodes assets unwrap assets/arena/arena.glb --groups 12 --zone "-30,0,-20,30,3,20" --zone-max 16
+```
+
+The lightmap bake traces a second UV set, `TEXCOORD_1`: every triangle of the file in ONE
+non-overlapping unit square, cut into charts by xatlas (`src/unwrap/lightmapUv.ts`, the wasm in
+`src/wasm/lightmapUv.js`). `unwrap` writes it **into the file itself** — scenes reference the
+original, so there is no `.fixed.glb` to copy over it — through a temp file renamed over the target
+(`-o` writes elsewhere). A file whose primitives all carry `TEXCOORD_1` is skipped (`--force` unwraps
+it again); skinned meshes are left as they are; `<name>_LOD<n>` siblings take level 0's layout by
+projection. Seam vertices are split (the report says how many); every other attribute, the
+materials and the textures stay as they were.
+
+`lecodes lightmap bake` runs the same code on every GLB the app references that has no
+`TEXCOORD_1`, so a raw import needs no step of its own. By hand it is for what the bake cannot
+decide: a whole level in one GLB wants `--groups <n>` (n unit squares = n atlas rects: one rect
+cannot span pages) and `--zone` (what is far from where the player walks is cut and baked at a
+coarser texel). The bake re-packs every file's charts at its own density (engines/bake, the
+`<stem>-uv1.bin` sidecar), so only the CUTTING matters here: the layout padding is fixed, and
+`--texel` (the bake's, 0.05) only sizes it for the files whose square the bake keeps as it is.
 
 ## Unity packs — `unpack` + materials from `.mat`
 
@@ -107,6 +182,18 @@ formats through `sharp`) — one metallic-roughness(+occlusion) texture per mate
 keeps the FBX references; `--unity-mats <dir>` looks elsewhere. Only YAML-serialised `.mat` files are
 readable (Unity "Force Text", the asset-store default since 2017); binary ones are listed and skipped.
 
+**Emission and baked light.** A material that glows keeps Unity's answer to "does the glow light the
+level": its inspector's *Global Illumination* setting, `m_LightmapFlags` in the `.mat` (bit 2 =
+Baked, bit 1 = Realtime — which a project without realtime GI bakes too, neither = None). None
+becomes the glTF material's extras `{"lecodes":{"emissiveBake":false}}` (merged with the foliage
+`wind` profile when both are there) and the slot summary says `emissiveBake=false (Unity GI: None)`:
+the surface still glows, but `lecodes lightmap bake` makes no lamp of it. That is how packs lit by
+their own lamps arrive — the shooting range's `M_Lamp_long` glows (`_EmissiveColor` 4) with flags 4
+(HDRP leaves EmissiveIsBlack on materials that do glow), and its rooms are lit by area lights. A
+`.mat` without `m_LightmapFlags` keeps the default: it bakes. A level that wants none of its panels
+in the bake says so once, `bake('…', { emissiveBake: false })` (the SDK's lightmap docs, "Emission:
+three forms, one switch").
+
 ## Retarget — clips from a different skeleton
 
 `convert --clips` binds tracks by BONE NAME and copies them verbatim; that only works when both
@@ -342,7 +429,7 @@ BIND=1 BONES=1 bun tools/filmstrip.ts fox.glb bind.png 1 - side
 CELL=440 bun tools/filmstrip.ts fox-anim.glb strip.png 4 wolf_walk side "fox.glb|-|0"   # rest pose first
 ```
 
-For the real thing on the real engine, `packages/viewer` → `node anim-check/model-check.mjs`.
+For the real thing on the real engine, `runtime/web` → `node anim-check/model-check.mjs`.
 
 ## Unreal packs — `.uasset` skeletons, clips, meshes
 
@@ -429,6 +516,13 @@ slot. The rest are listed in the report (`not in glTF: …`) rather than guessed
 vector parameters (colour tints, roughness powers) are read but not applied for the same reason:
 gear comes out in its neutral colours.
 
+**Sounds.** A `SoundWave` keeps the WAV it was imported from in the same Oodle `FCompressedBuffer`
+(cooked builds carry platform Vorbis/ADPCM instead — those are not read). `unreal wav <Sound dir> -o
+<dir>` writes every one as `<name>.wav` exactly as imported; `--ogg` re-encodes through ffmpeg (PATH
+or `LECODES_FFMPEG`) to mono Vorbis, a tenth of the size and what `Sound.load` decodes to anyway
+(`--stereo` keeps the channels, `--quality` is libvorbis' `-q`, default 5). `SoundCue` packages next
+to the waves are skipped. Loop points are untouched: an engine pack's RPM loops are cut to the sample.
+
 **Retargeting from a UE rig.** `--from x.uasset` builds the rig directly. The UE5 mannequin weights
 its limbs to the twist helpers (`thigh_twist_01_l`) and leaves `thigh_l` itself without a single
 vertex, so "part of the body" is the skinned subtree's INTERIOR, not just the bones carrying
@@ -483,6 +577,72 @@ extension with unlit") and silently falls back to lit if it is left in place.
 Both engines implement it: Filament through gltfio's `unlit_opaque` ubershader, web-lite through the
 `UNLIT` branch of its glTF shader (`viewer-lite/src/gl/glb.ts`, covered by `bun run render:check`).
 
+## Merge — one draw call per character
+
+A modular character (or any multi-material prop) arrives as a dozen parts — head, hands, shirt,
+pants, boots, vest, helmet, pouches — each its own mesh node, its own skin over a subset of the
+joints, its own material with its own base / normal / ORM maps. Every material is a draw call and
+three texture binds, so the character costs 16 draw calls and a squad of twelve costs 200.
+`doctor --merge` (also `convert … --merge`) folds all of it into **one primitive over one material
+per compatibility class**:
+
+- **Classes.** Primitives are grouped by what one draw cannot mix: alpha mode (+ cutoff for MASK),
+  double-sidedness, unlit. A Military kit becomes `merged` (everything opaque) plus `merged.blend`
+  (the goggles' glass). A material with an extension the pass does not understand, a
+  `KHR_texture_transform`, or UVs that tile a texture more than 4× forms a class of its own — its
+  geometry still merges with its siblings, its textures are kept as they are.
+- **Kinds.** A *skinned* part joins the union skin (joints in tree order, inverse bind matrices from
+  the skin that has most of them; a part bound in another bind space is moved into the canonical one
+  when its matrices differ by one rigid transform, and skipped when they disagree per joint). A
+  *rigid* part — a plain mesh sitting under a bone: a hat, a strap, a holstered gun — is skinned to
+  that bone with weight 1. A *static* part — a plain node — has its world transform baked and lands in
+  `merged.static`. Node-animated parts, morph targets and names matching `--merge-exclude <regex>`
+  stay as they are and are reported.
+- **Atlases.** Per class, one texture per map kind the parts use: base colour, normal, packed
+  occlusion-roughness-metallic, emissive. Each material gets a tile (materials with the same maps and
+  factors share one); its FACTORS are baked into the tile — base colour factor in linear light,
+  roughness / metallic into the ORM channels, normal scale, emissive factor, occlusion strength — so
+  the merged material is factor-free and reads as the parts did; a material without a map gets a flat
+  tile of its factor; UVs are remapped into the tile; every tile is padded by `--atlas-pad` (8)
+  texels of edge replication so bilinear filtering and the first mips stay clean.
+- **Tile sizes.** The atlas is the smallest power-of-two square (≤ `--atlas-size`, default 2048)
+  that holds every map at full size. When they do not fit, tiles shrink **by surface area**: each
+  material's area on the model (its triangles in bind / world space) over its UV coverage gives the
+  texel density its tile would have, and the tiles are sized so every part lands at the same
+  texels-per-metre, none past its native map — a torso keeps its map, a buckle gets the small tile
+  it needs. On the HorizonDemo hero at 2048 that is jacket and trousers at 89 %, straps and buckles
+  at 9 %; `--atlas-size 4096` keeps everything native. `--atlas-uniform` scales every tile by the
+  same factor instead. The report prints the range (`tiles 9–89% by area`).
+- **Order.** The pass runs before the LOD / card passes (they see the merged primitive)
+  and before the texture passes: the atlases are written as PNG and go through `--ktx2` and the
+  format normalisation like any map — except that an atlas is capped by `--atlas-size`, not
+  `--max-size` (the per-part cap), so `--merge --ktx2 --max-size 1024` keeps a 2048² atlas.
+- **Sources.** Run it from the source textures (PNG / JPEG) — a build that ends in the doctor just
+  adds the flag. A GLB that already carries KTX2 maps works too, decoded through KTX-Software's
+  `ktx extract` (`KTX_TOOL`, next to `KTX_TOKTX`, or found like the encoder), but that is a second lossy encode.
+- **Attributes.** The merged primitive carries the union: positions, normals (computed for a part
+  without any), UVs, colours (white where a part had none), joints / weights; tangents only when every
+  part has them, a lightmap UV set (`TEXCOORD_1`) only when every part has one. Indices go 32-bit past
+  65 535 vertices.
+
+What disappears: the parts' nodes (unless they still have children), meshes, skins, materials and
+textures. Code that addressed a part by node name needs `--merge-exclude`; bones and empties
+(`RH_WP`) are untouched, clips play as before. The merged skin's joint count is checked against the
+bone cap (`--target`).
+
+```
+🔍 chr1.glb
+  ── MERGE ──
+   • merge 21 primitive(s) over 15 material(s) → 2 draw call(s)
+     merged: 20 primitives, 14 material(s) → 1 (atlas 2048² base+normal+orm, 14 tiles (tiles 16–68% by area), pad 8), 61 joints in one skin
+   merge: 21 primitive(s) → 2 draw call(s)
+     merged: 20 primitives / 14 material(s) → 15129 vertices, 21150 triangles, atlas 2048² base+normal+orm (tiles 16–68% by area), 61 joints
+💾 wrote chr1.glb  (5880KB → 1510KB)
+```
+
+Without the flag the doctor still says what the merge would fold (`ℹ 21 primitive(s) over 15
+material(s) → 2 draw call(s) with --merge`) and what it would skip.
+
 ## What `convert` does
 
 - **Reads FBX with [ufbx](https://github.com/ufbx/ufbx)** compiled to wasm (`native/fbx_reader.c` +
@@ -517,7 +677,7 @@ Skipped in v1: cameras/lights, morph targets, NURBS.
 
 ## Verified with
 
-`packages/viewer` → `node anim-check/model-check.mjs anim-check/fixtures/<file>.glb --clip N`: loads the
+`runtime/web` → `node anim-check/model-check.mjs anim-check/fixtures/<file>.glb --clip N`: loads the
 GLB on the Filament wasm engine, binds every clip through the native Animator, screenshots the rest
 pose and a playing clip (the mesh must draw and deform). `bun test` here covers the reader/converter
 against the Mixamo sample set when `LECODES_FBX_SAMPLES` (or the default sample folder) exists.
@@ -530,7 +690,7 @@ with a reason, and the clips compared channel-by-channel against the pack's own
 exists, plus format/math unit tests that always run. The texture path was checked against the
 predecessor Python extractor with the same Oodle library: the images come out BYTE-IDENTICAL on
 both packs (67 MB, 21 MB and 1 MB payloads), and the converted mannequin renders with its own
-materials through `packages/viewer`'s Filament check.
+materials through `runtime/web`'s Filament check.
 
 Retargeting was tuned on the polyperfect *Low Poly Animated Animals* zoo (different authoring
 conventions within one pack: AdvancedSkeleton `Root_M/Hip_L`, Maya `actor:skin_*` with ×100 bind
@@ -547,15 +707,32 @@ vendor/ufbx/             ufbx.h / ufbx.c (MIT)
 src/wasm/fbxReader.js    generated single-file Emscripten module (tracked; rebuild with build-wasm.sh)
 src/fbx/                 read.ts (wasm boundary + IR) · toDocument.ts · convert.ts (merge, write)
 src/textures/            resolveImage.ts (sniff, TGA/BMP decode, PNG encode, external lookup)
-src/doctor/              doctor.ts (analyze/apply/report) · reduceGlbBones · transcodeTextures · transcodeKtx2 · normalizeScale · lightmapUv (xatlas wasm) · validateGlb (mirror of viewer's)
+src/doctor/              doctor.ts (analyze/apply/report) · reduceGlbBones · transcodeTextures · transcodeKtx2 · normalizeScale · cardTrim · lod · validateGlb (mirror of viewer's)
+src/unwrap/              lightmapUv.ts (xatlas wasm: charts, groups, zone, LOD projection) · index.ts (whole files, in place — `unwrap` and `lecodes lightmap bake`)
+src/doctor/merge/        --merge: classify (what can merge, as what) · bindSpace (one bind space for several skins) · atlasLayout (tiles by surface area) · atlasPixels (factors baked in) · geometry (the merged primitive + union skin) · plan · index (apply, cleanup)
 src/retarget/            rig.ts (hierarchy + bind pose + clip sampling) · retarget.ts (reference poses, world-delta transfer, leg IK, bridges) · automap.ts (quadruped classification + chain pairing) · humanoid.ts (humanoid canon, biped classifier, Unity .meta avatars, avatar↔avatar map) · unityAnim.ts (Unity .anim YAML reader)
 tools/humanoid-survey.ts bind-pose survey of the humanoid zoo (arm drop / elbow / facing / proportions per rig)
 tools/humanoid-phase3.ts every zoo clip onto every zoo target: planted frames, reach, twist, root motion (--strips for filmstrips)
 src/retarget/ghost.ts    a rig's skeleton alone with one clip — the character studio's donor "ghost"
-src/unreal/              package.ts (uncooked UE5 .uasset: summary/names/imports/exports/tagged properties/bulk data) · skeleton.ts · anim.ts (both data models) · sequencer.ts (MovieScene ControlRig channels) · mesh.ts (FSkeletalMeshImportData) · convert.ts (the UE→glTF coordinate recipe) · toDocument.ts · clipSource.ts (--clips merging) · rig.ts (retargeter) · resolve.ts (object path → file) · texture.ts (FCompressedBuffer + FTextureSource) · oodle.ts (the machine's own oo2core, via bun:ffi / koffi) · materials.ts (material instances → glTF slots) · probe.ts · list.ts (unreal ls) · convertAsset.ts · index.ts
-src/unity/               unpack.ts (.unitypackage streaming) · materials.ts (.mat → glTF materials, ORM packing) · png.ts · scene.ts (.unity → level JSON)
+src/unreal/              package.ts (uncooked UE5 .uasset: summary/names/imports/exports/tagged properties/bulk data) · skeleton.ts · anim.ts (both data models) · sequencer.ts (MovieScene ControlRig channels) · mesh.ts (FSkeletalMeshImportData) · convert.ts (the UE→glTF coordinate recipe) · toDocument.ts · clipSource.ts (--clips merging) · rig.ts (retargeter) · resolve.ts (object path → file) · texture.ts (FCompressedBuffer + FTextureSource) · sound.ts (SoundWave → WAV/OGG) · oodle.ts (the machine's own oo2core, via bun:ffi / koffi) · materials.ts (material instances → glTF slots) · probe.ts · list.ts (unreal ls) · convertAsset.ts · index.ts
+src/unity/               unpack.ts (.unitypackage streaming) · guid.ts (GUID → file: unity-index.txt / .meta) · matFile.ts (.mat reader, binary fallback) · materialWriter.ts (one .mat → one glTF material, ORM packing) · materials.ts (the FBX-convert flow + prefab overrides) · image.ts · png.ts
+                         scene import: yaml.ts · gameObjects.ts (the tree) · prefabTree.ts (nested prefabs + modifications) · fbxModel.ts (a model file as a prefab: ids, collapse, bakeAxisConversion) · propertyPath.ts · scene.ts (.unity → kinds + placements) · kindGlb.ts (one kind → one GLB) · materialSlots.ts (slot ↔ primitive by name) · lecodesLevel.ts + levelTerrain.ts (→ project files) · terrain.ts + serialized.ts (binary TerrainData) · foliage.ts · math.ts (the mirror-X frame)
 src/props.ts             --list-nodes / --keep / --split (subtree carving + re-origin)
 src/mergeSkins.ts        --merge-skins (skinned meshes onto one skeleton) · duplicateNodeNames
 src/filmstrip.ts         CPU-skinned PNG filmstrip renderer (probe --filmstrip; tools/filmstrip.ts wraps it)
-src/probe.ts · src/cli.ts · src/index.ts
+src/commands/            one file per command — a command is DATA: name, summary, flags, run (retarget/ is a folder); shared.ts = the flag groups several commands take (doctor passes, Unreal locations)
+src/cli-kit/             defineCommand + the argv parser that reads a line AGAINST a command's flags + the generated help
+src/probe.ts · src/cli.ts (runAssetsCli — what `lecodes assets` calls) · src/index.ts
 ```
+
+## Adding or changing a command
+
+A command is one `defineCommand({ name, summary, usage, description, flags, examples, run })` in
+`src/commands/`, listed in `src/commands/index.ts`. Flags are declared with `str` / `num` / `int` /
+`bool` / `list` (`bare:` lets a value flag stand alone — `--split` next to `--split dir`) and arrive
+in `run` typed; `given` tells a bare flag from an absent one. There is no hand-written help and no
+separate list of value-taking flags to keep in sync: a flag the code reads and the parser does not
+know cannot exist, and an unknown flag on the line is an error (its value would otherwise be read
+as an input file). `run` resolves to the exit code; throw `CliError` (1 = the work failed) /
+`usageError` / `missing(…)` (2 = the line is wrong, the latter followed by the command's help).
+`bun run build` afterwards — `lecodes assets` runs `dist/`.