lecodes-assets 0.2.0 → 2.4.10

package/README.md

@@ -1,449 +1,738 @@
-# lecodes-assets — the LeCodes asset pipeline
-
-FBX → GLB converter + GLB doctor, one package on one glTF-Transform `Document`. Reachable as
-`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).
-
-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:
-
-```sh
-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.
-
-```
-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 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 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)
-lecodes assets convert Barrel_v1.FBX --list-nodes                # multi-variant prop file: what is in it
-lecodes assets convert Barrel_v1.FBX --keep Barrel_v1_LD1 -o barrel.glb   # one variant, re-origined on the ground
-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
-```
-
-## Props, modular characters, scenes — the Unity-pack workflow
-
-**Multi-variant prop files.** Packs put every LOD, colour set and arrangement of a prop in one FBX
-(`Barrel_v1.FBX` = 15 meshes). `--list-nodes [depth]` prints the scene's nodes with mesh/triangle
-counts and world sizes; `--keep <node> …` keeps only those subtrees (ancestors stay as the path,
-descendants come along) and **re-origins** the result — footprint centre at X/Z = 0, lowest vertex at
-Y = 0 — so `Model.load` places the prop exactly where the node is (`--no-ground` keeps the file's
-own placement); `--split [dir]` writes one re-origined GLB per top-level node. Both run before the
-doctor passes, so `--keep X --ktx2 --max-size 1024` is the whole prop pipeline.
-
-**Modular characters.** Body, shirt, gloves and boots each arrive as their own skinned FBX over the
-same skeleton. `--merge-skins b.fbx c.glb …` moves the donors' skinned meshes onto the model's skin
-(joints matched by name — exact, then the part after the last `:`/`|`, the Animator's own rule) and
-drops their skeleton copies. That last part matters: a hand merge that leaves the donor skeleton in
-gives every bone name a plain-node twin, and a name-bound `Animator` drives the twin while the mesh
-freezes in its rest pose. `probe` and `doctor` now flag duplicate node names, and the doctor marks
-the joint-shadowing case as BLOCKING. Donor bones the base lacks are reported with the skin weight
-that sat on them (it moves to the root).
-
-**Checking a clip without a GPU.** `probe` prints, per clip and skeleton root, how far the root
-travels (root motion) and how far its first frame is from the rest pose — a root that starts ~90°
-off is the double-axis-turn symptom of a clip from another export. `probe --filmstrip [out.png]`
-renders a software-skinned PNG strip of every clip (`--clip` for one, `--frames N`, `--view
-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 packs — `unpack` + materials from `.mat`
-
-```
-lecodes assets unpack "Tactical FPS Animations.unitypackage" -o D:/Unity/tactical            # everything
-lecodes assets unpack pack.unitypackage -o out --only 'Meshes/' 'Animations/' 'Materials/'   # regex subset
-lecodes assets unpack pack.unitypackage -o out --list --only '\.wav$'                        # just list
-lecodes assets convert out/Assets/Pack/Weapons/SKM_TR-15.FBX --clips … --ktx2 -o tr15.glb    # .mat-aware
-```
-
-A `.unitypackage` is a gzip'd tar of one folder per asset GUID. `unpack` streams it twice (flat
-memory on multi-GB packs): pass 1 writes `<out>/unity-index.txt` (GUID → path), pass 2 writes the
-matching assets + their `.meta` sidecars under `<out>/Assets/…`.
-
-`convert` then reads the **Unity `.mat` files** found next to (or one folder above) the FBX and
-rewrites the glTF materials from them — an FBX exported for Unity usually references only a legacy
-base colour and a normal map, while metallic / roughness / occlusion / emission and the alpha mode
-live in the material. Matching is by name modulo `M_`/`MI_`/`MAT_` prefixes, then by containment
-(`MI_Tshirt` ↔ `M_Shirt`), then by a shared base texture (`MI_Skin` ↔ `M_Body` through
-`TX_Body_BaseColor`). Texture GUIDs resolve through `unity-index.txt` (found walking up from the
-FBX, or `--unity-index`), else through `.meta` sidecars of a real Unity project. Slots understood:
-`_BaseMap/_MainTex/_BaseColor/_BC`, `_BumpMap/_Normal`, a ready `_ORM`, HDRP/URP `_MaskMap`
-(R metal, G AO, A smooth), Standard `_MetallicGlossMap` (R metal, A smooth), separate `_Metallic`,
-`_Roughness` / `_Smoothness`, `_OcclusionMap`, `_EmissionMap` (+ `_EMISSION` keyword / colour),
-`_Surface`/`_Mode`/`_AlphaClip`/`_Cutoff`/`_Cull`. Everything that is not already one texture is
-**packed the glTF way** (R = AO, G = roughness, B = metallic; PNG/TGA/BMP decoded in-process, other
-formats through `sharp`) — one metallic-roughness(+occlusion) texture per material. `--no-unity`
-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.
-
-## Retarget — clips from a different skeleton
-
-`convert --clips` binds tracks by BONE NAME and copies them verbatim; that only works when both
-files came from the same rig (the Mixamo case). `retarget` drives one rig with a completely
-different rig's clips — different bone names, different chain lengths, different proportions,
-different local axis conventions, even different facing:
-
-```
-lecodes assets retarget fox.glb --from Wolf_Animation.fbx --map auto --clips wolf_walk wolf_run -o fox-anim.glb
-lecodes assets retarget giraffe.glb --from Deer_Animation.fbx --auto-map      # writes giraffe-from-Deer_Animation.map.json to edit
-lecodes assets retarget giraffe.glb --from Deer_Animation.fbx --map giraffe-from-Deer_Animation.map.json -o giraffe-anim.glb
-lecodes assets retarget fox-anim.glb --from Wolf_Howl.fbx --map … --keep-clips --clip-names howl
-lecodes assets retarget fox.glb --from Wolf_Animation.fbx --skeletons        # both bone lists, to write a map by hand
-lecodes assets retarget fox.glb --from Cat.fbx --map auto --anim Cat_Sleep.anim   # donor clips that live outside the FBX
-```
-
-**The map** is target-bone → donor-bone; `root` names the bone that receives root motion. `--map auto`
-/ `--auto-map` derive it from the two skeletons' SHAPE — root, spine, neck, head, jaw, ears, tail and
-the four legs (side + front/back) are read off the bind pose, then paired chain by chain with bones
-matched by arc length (names only break ties when they agree: `backAnkle`↔`Ankle_L`). It works on
-`joint1…joint42` rigs and prints exactly what it paired — read it before trusting it. Optional keys:
-
-```json
-{ "root": "Hips",
-  "bones": { "Hips": "Root_M", "chest": "Chest_M", "backleg": "Hip_L", "backleg0": "Knee_L", "…": "…" },
-  "align": { "chest": "keep", "tail": "direction", "head": [ "headend" ] },   // per-bone reference policy (see below)
-  "legs": [ "backleg2", "R_backleg2", "frontleg2", "R_frontleg2" ],        // feet, when auto-detection picks wrong
-  "donorRef": "auto" | "bind" | { "clip": "wolf_idle", "time": 0 } }
-```
-
-**How it works.** Everything happens in WORLD space, where a rotation means the same thing in both
-rigs: `ΔR(t) = Rdonor(t)·Rdonor_ref⁻¹` is applied to the target's own reference orientation and
-converted back to local against the already-retargeted parent. That transfer is exact — the thing
-that decides quality is what the two REFERENCE poses are and what happens where proportions differ:
-
-- **Donor reference** (`donorRef`, default `auto`). An exporter's bind is often a posture the clips
-  never visit — the polyperfect wolf binds upright on vertical thighs and walks 10% lower with its
-  thighs 30° forward; measured from that bind every clip reads as "crouch and lean". When the two
-  binds put the legs differently (>12°: different conventions), the donor is referenced to the MEAN
-  pose of its walk (else idle, else the longest clip) — its actual neutral posture. When the binds
-  agree, bind-to-bind is the faithful transfer (an identity retarget reproduces the donor exactly).
-  `--donor-ref bind|auto|<clip>` overrides.
-- **Target reference**, per bone: `keep` its bind orientation, or `direction` — turn it so the bone
-  points the way the donor's does (an auto-T-pose step, measured to the nearest mapped descendant).
-  A target that binds in a STANCE (feet level, legs hanging) keeps everything: that is its natural
-  posture and the donor's deltas ride on it — the horse stays tall under wolf clips, the giraffe's
-  neck stays up under deer clips. A target that binds posed (T-pose, folded legs) keeps its core
-  (root, pelvis, chest, head — artists put those joints anywhere, so their joint lines are not
-  comparable) and direction-aligns its chains. `align` overrides per bone.
-- **Feet** (`--ik legs`, the default). Directions transfer, positions do not: with different
-  front/back leg ratios the feet float or sink, which the eye catches first. Legs are detected from
-  the map (lateral chains reaching the ground; a foot is what stands on the donor's ground, a horse's
-  wrist-ended front leg is not), the reference pose is planted (root lowered/raised, every foot bent
-  onto the ground), then every frame each foot gets a goal built as THE TARGET'S OWN STANCE plus the
-  donor's departure from ITS stance, scaled by that leg's length ratio, on all three axes — height
-  above each rig's own stance level, and the horizontal offset each rig plants its foot at under its
-  own hip — and a FABRIK pass from the FK pose bends the chain onto it. Both builds are therefore
-  preserved: a target that tucks its feet inboard of its hips keeps doing so against a donor that
-  stands on vertical legs. (Copying the donor's absolute foot-under-hip offset instead planted this
-  repo's fox — which tucks each foot ~8% of body height inboard, while every polyperfect animal
-  stands vertical — bow-legged in every clip.) When the legs are scaled copies the goal IS the FK
-  pose, so IK only ever spends the proportion residual; goals out of reach are reported per leg.
-- **Root motion** is scaled by the mean leg-length ratio (a stride is leg length, not body height),
-  so stance feet that were still on the donor stay still on the target.
-- **Chain lengths.** A longer donor chain collapses for free (the target's `chest` mapped to
-  `Chest_M` picks up Spine1+Spine2, because a world rotation already contains everything above it).
-  A longer target chain — unmapped bones between two mapped ones — interpolates the delta along the
-  chain (a 6-bone spine against a 2-bone one bends everywhere, not at one joint).
-- **Spaces.** The anchor is the BIND pose (inverse of the skin's inverse-bind matrices), never the TRS
-  on the nodes — the wolf's node pose is 0.37 m from its bind. A skin whose bind space is scaled
-  against node space (Maya "actor" exports, ×100) is rescaled; a donor facing the other way is turned
-  (facing is read from the skeleton shape, so `joint1…` rigs work too); non-uniform scales are refused.
-
-- **Second pass on proportions** (humanoid plan phase 3, 2026-08-27; the quadruped path shares the
-  planting and the root-motion switch):
-  - **A humanoid foot = contact + orientation** (2026-08-27). The leg's IK effector is the ankle,
-    but its goal comes from the BALL of the foot (the canonical `Toes` bone): the ball goes where
-    the donor's ball goes (leg and foot each scaled by their own ratio, stance-corrected), the foot
-    keeps the donor's rotation on the target's own flat bind, and the ankle follows from the two.
-    Rigs put the ankle at different places over the ball — a boot's foot bone dives 56° to the ball,
-    X-bot's 27°, both soles flat: driving the ball with the foot as an IK link let the solver pick
-    the foot's pitch (50° off the donor in the swing), transferring the ankle's position AND the
-    foot's rotation lifted the boot 10 cm off the ground at toe-off. Now the stance foot is flat,
-    toe-off has the heel up and the toes on the ground, and the report says `contact <ball>` when
-    it differs from the effector. What the two feet's shapes cost at full extension (a few cm) is
-    silent; `reach` reports what the LEG cannot do.
-  - **Foot planting** (default; `--no-plant`). While a donor foot stands still on its ground (under
-    15 % of a leg length per second, within 6 % of a leg length of its stance height, ≥ 3 frames),
-    the target's foot goal is held at ONE world point — the mean of where the FK would have put it
-    over the span, which splits the slide between landing and lift-off; a 4-frame ease at each end
-    hides both halves, a span across a cycle's seam is one plant held modulo the clip's travel. A
-    span whose mean sits more than 5 % of a leg length from some frame's FK goal is a shuffle, not a
-    plant, and is left alone. Per-leg ratios and the hips' own sway otherwise slide a planted foot a
-    few cm per step. The planted point is the contact (the ball rolls under a rising heel; the ankle
-    moves). Reported per leg (`planted N frames`) and per clip as spans.
-  - **Where the travel goes** (`--root-motion auto|hips|root|none`). A rig with a root ABOVE the hips
-    gets the donor's horizontal travel on the root and the vertical bob on the hips (`root`, the
-    default when such a root exists — a character controller reads the root's travel and must not
-    bob with it); `hips` puts everything on the hips as the donor had it; `none` strips the travel
-    for an in-place clip (feet still planted in the travelling frame, so they slide back under the
-    body like a treadmill). A donor whose hips bob relative to their own root (MoCap Central:
-    `root` travels, `pelvis` bobs) has that bob re-applied on the target's hips.
-  - **Hands as effectors** (`--ik hands`): the same ratio-scaled goal as a foot, measured from the
-    upper arm, chain capped at upper + lower arm, for clips where the hands meet or hold.
-  - **Twist helpers** (`--twist N`, default 0.5; `off` = ride rigidly). A helper at fraction `t`
-    along its limb bone takes `f·(t·twistOut − (1 − t)·twistIn)` about the bone's axis on top of
-    riding it — near the joint it counter-rotates the bone's own axial turn (the shoulder skin stays
-    with the clavicle), near the far end it follows the child's (the wrist follows the hand's
-    pronation). Helpers come from the avatar's `twist` map (shape classifier or `.avatar.json`).
-  - The stance correction inside a foot goal (where THIS rig rests its foot under its hip, against
-    where the donor does) is shrunk — never the donor's vector — when it would put the goal past the
-    leg's length (a running push-off on a rig whose hips sit higher above its feet); that removed
-    the "out of reach" residue on Humanoid_F.
-
-What it does not do yet: stride warping when a leg is far too short for the donor's reach (reported
-as "out of reach"), torso pitch to compensate for mismatched front/hind leg ratios; for humanoids
-the knee/elbow bend-plane roll of the UPPER arm and the legs —
-[docs/humanoid-retarget-plan.md](../../docs/humanoid-retarget-plan.md).
-
-### Humanoids — avatars
-
-A humanoid rig is described by its **avatar**: its bones named in the Unity/VRM humanoid canon
-(`Hips`, `Spine`/`Chest`/`UpperChest`, `Neck`, `Head`, `Jaw`, `LeftEye`…, `LeftShoulder`/`LeftUpperArm`/
-`LeftLowerArm`/`LeftHand`, `LeftUpperLeg`/`LeftLowerLeg`/`LeftFoot`/`LeftToes`, `Left Thumb Proximal`…
-— 55 bones). An avatar belongs to ONE rig; a humanoid map is two avatars joined on the canon, so
-each rig is mapped once and any pair retargets.
-
-```
-lecodes assets avatar girl.glb                                  # read the avatar off the skeleton's shape
-lecodes assets avatar girl.glb --meta SK_Girl.fbx.meta -o girl.avatar.json   # check vs Unity's map, write Unity's
-lecodes assets retarget girl.glb --from Swat.fbx --auto-map      # both rigs' avatars from shape → map.json
-lecodes assets retarget girl.glb --from Swat.fbx --avatar girl.avatar.json --map auto --clips Walking
-```
-
-`avatar` reads the structure off the bind pose (`src/retarget/humanoid.ts`): the hips are the joint
-two chains hang from that reach the ground on opposite sides; the hands are the lateral joints fanning
-out into short chains (fingers) — a weapon socket or IK target on the hand is shed; the spine is the
-centre path from the hips to where the arms meet; the head is the last branch above the arms (hair
-rigs branch below it, so a `head` name breaks that tie); the toes say which way is forward, and so
-which side is left. Spine bones: 1 → `Spine`, 2 → `+Chest`, 3 → `+UpperChest`, more → first /
-arc-middle / arm-attach with the rest **bridged**; a second neck bone and finger metacarpals bridge
-too. **Twist/roll helpers** (leaf children on their parent's axis — `upperarm_twist_01_l`,
-`calf_twist_02_r`) are recorded as `twist: { bone: canonical }`, never mapped. Names only break ties
-(thumb vs index when both are named; a `jaw` child) and the report says when they did. Everything
-else (hair, cloth, `ik_*`, bag, breasts) is listed as "not part of the body" and keeps its bind.
-
-**A person's word rides in the avatar** (`.avatar.json` `transfer`, written by the character studio,
-read by `retarget --avatar`): `align: { <canonical bone>: "keep" | "align" }` — this bone is BUILT
-that way (keep the bind, whatever the angle) or POSED (align to the donor, the 8° threshold
-notwithstanding; a standing leg too); `roll: { Left?, Right? }` — degrees added to the measured palm
-roll per arm, for a finger that lands almost right; and the transfer settings (`rootMotion`,
-`plant`, `hands`, `twist`) the CLI takes as defaults — flags still win. The report lists
-`under 8° kept` bones with their angle so the decision can be checked, and `avatar transfer: …`
-says what the file asked for.
-
-**The humanoid transfer** (`retarget` with both avatars — `--map auto`, `--avatar`, or a map.json
-that carries `avatars`) keeps the world-delta machinery above and decides the reference by canonical
-ROLE: hips, spine, neck, head, face and (standing) legs keep their bind; shoulder → upper arm →
-forearm → hand and every phalanx align to the donor's bind directions with explicit references (the
-hand to its finger bases), but only past an **8° threshold** — under it a mismatch is joint placement
-and stays, over it is posture (an A-pose against a T-pose, a bent elbow) and turns. Direction fixes
-two of three degrees of freedom; the **palm roll** — where the palm faces, the thing no direction can
-see — is read off the knuckle line (index base → little base) across the forearm, and the forearm
-chain turns until the target's line lies where the donor's does. Metacarpals ride the hand rigidly.
-The donor is referenced to its bind (its clips are authored on it); a target `root` above the pelvis
-that shares the donor's hips takes the hips' travel only. An identity retarget is exact
-(`tests/humanoidRetarget.test.ts`, key reduction off); Mixamo Walking on the zoo lands arm directions
-within 3° and palms within 10° on every frame.
-
-A Unity model importer's `.meta` carries Unity's own humanoid map: `--meta` diffs the shape result
-against it — the zoo in the plan agrees on every bone but the Chest/UpperChest picks on a 5-bone spine
-— and `-o` with `--meta` writes Unity's map as the `.avatar.json`. `retarget --avatar` / `--donor-avatar`
-accept either file; without them both rigs classify from shape (a biped↔quadruped pair is refused).
-
-Bind space: IBMs live in the MESH's geometry space. When an exporter parks the Z-up→Y-up turn on a
-geometry helper node (Female Runner's `Humanoid_F`) or ×100 on the mesh node (Maya "actor"), `rig.ts`
-folds that node's world transform in front of `inv(IBM)` — kept only when it brings the bind closer to
-the node rest pose.
-
-### Donors whose clips are not in the FBX
-
-Asset packs routinely ship the rig as FBX and the animations as Unity `.anim` assets — the
-polyperfect cat and all three dogs have EMPTY FBX files and eight `.anim` clips each. `--anim` reads
-those directly (`src/retarget/unityAnim.ts`, YAML only — a project saved with binary serialisation
-has to be re-exported with *Asset Serialization = Force Text*) and attaches them to the donor rig as
-clips, bound by the LAST segment of each curve's transform path:
-
-```
-lecodes assets retarget fox.glb --from Cat.fbx --map fox-from-cat.map.json   --anim Cat_Walk.anim Cat_Idle.anim Cat_Sleep.anim Cat_StandUp.anim   --clips Cat_Sleep Cat_StandUp --clip-names sleep stand_up -o fox-cat.glb
-```
-
-Pass the donor's locomotion clips even when you do not want them in the output: `--donor-ref auto`
-takes the donor's neutral posture from a walk/idle, and without one it falls back to the bind pose.
-
-**Skeleton-only clip files** — the other pack convention (Female Runner, MoCap Central, Mixamo
-"without skin"): each clip is an FBX of nodes + curves and NO mesh, so it has no skin to classify
-and no bind to measure from. `--donor-rig <model.fbx|.glb>` names the rig it was animated on; the
-clips bind to it by bone name (exact, then without the `namespace:` prefix — `rebindClips` in
-`rig.ts`) and the model's bind, skin and avatar carry the motion:
-
-```
-lecodes assets retarget vex.glb --from MCU_af_Loco_Walk_Fwd.FBX --donor-rig rig_MCUnity.fbx --map auto -o vex-mc-walk.glb
-```
-
-Whether a clip file IS the character's own rig (copy the tracks by name, the Mixamo flow) or only
-shares its naming convention (two Unreal-style rigs — retarget) is decided by `sameSkeleton`:
-≥ 80 % of the names must match AND every matched bone ≥ 5 cm must keep its local offset's
-DIRECTION (the child in its parent's frame — fixed by the rig, unlike the node rotations, which
-a clip file carries posed at its first frame). A Mixamo character against another's clip stays
-within ~20°; MoCap Central's rig against IdaFaber's turns the pelvis by 88° — a copied clip would
-lay the character down.
-
-### What a short spine cannot borrow
-
-Rotations transfer; positions follow from the TARGET's own bones. Leg IK covers that for feet, but
-nothing covers the spine, so a clip whose whole point is a spine CURL does not survive a target with
-fewer spine bones. The cat sits by curving a 7-bone spine to hold its chest up over a dropping
-pelvis; this fox has two spine bones and no way to curve, so its chest is simply carried down by the
-pelvis and the head ends up on the floor (4% of body height, against the cat's 79%). Hanging the
-pelvis on a mid-spine bone instead recovers part of it (27%) but then breaks lying-down clips, whose
-heads go through the floor. Clips that END lying (`Sleep`) or start there (`StandUp`) transfer fine —
-they need no upward curl.
-
-### Seeing the result
-
-A bone map is judged by eye. `tools/filmstrip.ts` skins a clip on the CPU and writes a PNG strip —
-no browser, no GPU, no engine, so it runs on every iteration:
-
-```
-bun tools/filmstrip.ts fox-anim.glb strip.png 6 wolf_walk threequarter
-BONES=1 CELL=360 bun tools/filmstrip.ts fox-anim.glb strip.png 5 wolf_walk side   # skeleton overlay
-BIND=1 BONES=1 bun tools/filmstrip.ts fox.glb bind.png 1 - side                     # the bind pose itself
-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`.
-
-## Scale
-
-`probe` and `doctor` always **report** the model's rendered world size; nothing is changed without a
-flag. A skinned primitive ignores its node's transform (glTF spec), so the size is measured through
-the skin's bind space (`world(joint₀)·IBM₀`) — measuring via the mesh node reports garbage on exactly
-the assets that are mis-scaled.
-
-| flag | what it does |
-|---|---|
-| `--fix-scale` | guess the unit and bake it: cm / mm / feet / inches / the Blender-FBX `0.01` armature quirk. Picks the **smallest** correction that lands the largest dimension in 0.1–100 m |
-| `--scale N` | bake an explicit factor (works on clip-only files too) |
-| `--scale-to M` | bake whatever makes the largest dimension `M` metres |
-
-The factor is **baked into the data** — positions, node translations, IBM offsets and translation
-tracks all × s — not parked on a wrapper node. No node is added and no local scale is rewritten, so
-every node path an app addresses stays what it was. Rotation and scale tracks are untouched by
-construction: scaling only translations gives `world' = S·world·S⁻¹`, and the skinning identity then
-needs `IBM' = S·IBM·S⁻¹`, which is just the IBM's translation column × s.
-
-Quantized (`KHR_mesh_quantization`) positions are refused rather than silently corrupted.
-
-## Shading — why a downloaded model renders too bright
-
-`doctor` always reports two material quirks that make an asset look washed out, and neither one is
-the usual suspect (metallic, or the texture):
-
-- **self-lit** — the base colour texture is *also* wired into `emissiveTexture` with
-  `emissiveFactor = [1,1,1]`, so the shader draws `lit(albedo) + albedo`: roughly twice as bright as
-  intended, with the shading flattened out. Common from Sketchfab downloads and several FBX
-  exporters. `--fix-emissive` drops it and leaves the material otherwise PBR.
-- **specular boost** — `KHR_materials_specular` with a `specularColorFactor` above 1.
-
-`--unlit` goes further and converts the material to **`KHR_materials_unlit`**: flat
-`baseColorFactor × baseColorTexture`, no lights, no IBL, no exposure — the shading model hand-painted
-stylised assets are usually authored for. It also clears the emissive and drops specular/ior/normal/
-occlusion/MR inputs, because gltfio *refuses* to combine specular with unlit ("Cannot use specular
-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`).
-
-## What `convert` does
-
-- **Reads FBX with [ufbx](https://github.com/ufbx/ufbx)** compiled to wasm (`native/fbx_reader.c` +
-  `vendor/ufbx`, built by `build-wasm.sh` into `src/wasm/fbxReader.js` — a single-file module, no
-  native builds, runs in Bun/Node/browsers). Everything is converted to glTF conventions in C:
-  meters, right-handed Y-up (`space_conversion = MODIFY_GEOMETRY`), geometry transforms / inherit
-  modes as helper nodes, triangulated + welded primitives, top-4 skin weights renormalized, UV v
-  flipped, animations **baked** (30 fps, key-reduced, trimmed to start at 0). One JSON description +
-  one binary arena cross the wasm boundary; `src/fbx/toDocument.ts` builds the Document.
-- **Textures** embedded: PNG/JPEG pass through, TGA/BMP decoded here (→ PNG), everything else via
-  `sharp` when installed; duplicates de-duplicated by content hash; external references resolved
-  next to the FBX / `textures/`.
-- **Materials**: ufbx's PBR view of FBX Phong/Lambert → metallic-roughness (opacity map → MASK,
-  opacity factor < 1 → BLEND, double-sided honored). Separate metallic/roughness maps are not
-  packed (factors used).
-- **`--clips`**: each clip file's animations are re-targeted onto the model **by bone name** (exact,
-  then the part after the last `:`/`|` — the same rule the SDK `Animator` uses); clip meshes/skins
-  dropped; unbound tracks counted + warned. Naming: a single-clip file → its stack name unless generic
-  (`mixamo.com`, `Take 001`, `Unreal Take`) → the file's basename; `--clip-names` overrides.
-  **Parent-space correction**: a track is a LOCAL transform, and two exports of one rig need not
-  agree on what sits above a bone — Unreal/Unity clip exports put `root` straight under the scene
-  (rest −90°X, the Z-up→Y-up turn) while the skinned-mesh export parks that turn on an armature node
-  and leaves `root` at identity; copied verbatim the turn applies twice and the character plays lying
-  on the floor (KINEMATION's Tactical Shooter Pack, every UE5 Mannequin export). For each bound bone
-  the converter compares the world transform of its parent in both files — with the clip's first
-  frame written onto every bone it animates, so only the unanimated STRUCTURE above differs, never
-  the hair-width rest-pose drift between re-exports — and re-expresses the track in the model's
-  parent space (`local_model = inv(Pmodel)·Pclip·local_clip`). Reported as an ℹ line per clip file.
-- Output goes through the same validation as the doctor (`validateGlb`) and a `probe` summary.
-
-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
-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.
-
-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
-space and −Z facing, unnamed `joint1…joint42`): wolf → Meshy fox, lion → cat, wolf → horse / golden
-retriever, deer → giraffe, lion → elephant, all through `--map auto`, judged on `BONES=1` filmstrips
-next to the donor's own walk. `tests/retarget.test.ts` pins the invariants on toy rigs (exact
-direction transfer, keep/direction policies, bridges, leg detection + IK goals, donor reference).
-
-## Layout
-
-```
-native/fbx_reader.c      ufbx → JSON + arena (compiled to wasm)
-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/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/unity/               unpack.ts (.unitypackage streaming) · materials.ts (.mat → glTF materials, ORM packing) · png.ts · scene.ts (.unity → level JSON)
-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
-```
+# lecodes-assets — the LeCodes asset pipeline
+
+FBX → GLB converter + GLB doctor, one package on one glTF-Transform `Document`. Reachable as
+`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:
+
+```sh
+npm install -g lecodes-assets
+```
+
+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)
+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 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)
+lecodes assets convert Barrel_v1.FBX --list-nodes                # multi-variant prop file: what is in it
+lecodes assets convert Barrel_v1.FBX --keep Barrel_v1_LD1 -o barrel.glb   # one variant, re-origined on the ground
+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 → 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
+```
+
+## Props, modular characters, scenes — the Unity-pack workflow
+
+**Multi-variant prop files.** Packs put every LOD, colour set and arrangement of a prop in one FBX
+(`Barrel_v1.FBX` = 15 meshes). `--list-nodes [depth]` prints the scene's nodes with mesh/triangle
+counts and world sizes; `--keep <node> …` keeps only those subtrees (ancestors stay as the path,
+descendants come along) and **re-origins** the result — footprint centre at X/Z = 0, lowest vertex at
+Y = 0 — so `Model.load` places the prop exactly where the node is (`--no-ground` keeps the file's
+own placement); `--split [dir]` writes one re-origined GLB per top-level node. Both run before the
+doctor passes, so `--keep X --ktx2 --max-size 1024` is the whole prop pipeline.
+
+**Modular characters.** Body, shirt, gloves and boots each arrive as their own skinned FBX over the
+same skeleton. `--merge-skins b.fbx c.glb …` moves the donors' skinned meshes onto the model's skin
+(joints matched by name — exact, then the part after the last `:`/`|`, the Animator's own rule) and
+drops their skeleton copies. That last part matters: a hand merge that leaves the donor skeleton in
+gives every bone name a plain-node twin, and a name-bound `Animator` drives the twin while the mesh
+freezes in its rest pose. `probe` and `doctor` now flag duplicate node names, and the doctor marks
+the joint-shadowing case as BLOCKING. Donor bones the base lacks are reported with the skin weight
+that sat on them (it moves to the root).
+
+**Checking a clip without a GPU.** `probe` prints, per clip and skeleton root, how far the root
+travels (root motion) and how far its first frame is from the rest pose — a root that starts ~90°
+off is the double-axis-turn symptom of a clip from another export. `probe --filmstrip [out.png]`
+renders a software-skinned PNG strip of every clip (`--clip` for one, `--frames N`, `--view
+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` 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`
+
+```
+lecodes assets unpack "Tactical FPS Animations.unitypackage" -o D:/Unity/tactical            # everything
+lecodes assets unpack pack.unitypackage -o out --only 'Meshes/' 'Animations/' 'Materials/'   # regex subset
+lecodes assets unpack pack.unitypackage -o out --list --only '\.wav$'                        # just list
+lecodes assets convert out/Assets/Pack/Weapons/SKM_TR-15.FBX --clips … --ktx2 -o tr15.glb    # .mat-aware
+```
+
+A `.unitypackage` is a gzip'd tar of one folder per asset GUID. `unpack` streams it twice (flat
+memory on multi-GB packs): pass 1 writes `<out>/unity-index.txt` (GUID → path), pass 2 writes the
+matching assets + their `.meta` sidecars under `<out>/Assets/…`.
+
+`convert` then reads the **Unity `.mat` files** found next to (or one folder above) the FBX and
+rewrites the glTF materials from them — an FBX exported for Unity usually references only a legacy
+base colour and a normal map, while metallic / roughness / occlusion / emission and the alpha mode
+live in the material. Matching is by name modulo `M_`/`MI_`/`MAT_` prefixes, then by containment
+(`MI_Tshirt` ↔ `M_Shirt`), then by a shared base texture (`MI_Skin` ↔ `M_Body` through
+`TX_Body_BaseColor`). Texture GUIDs resolve through `unity-index.txt` (found walking up from the
+FBX, or `--unity-index`), else through `.meta` sidecars of a real Unity project. Slots understood:
+`_BaseMap/_MainTex/_BaseColor/_BC`, `_BumpMap/_Normal`, a ready `_ORM`, HDRP/URP `_MaskMap`
+(R metal, G AO, A smooth), Standard `_MetallicGlossMap` (R metal, A smooth), separate `_Metallic`,
+`_Roughness` / `_Smoothness`, `_OcclusionMap`, `_EmissionMap` (+ `_EMISSION` keyword / colour),
+`_Surface`/`_Mode`/`_AlphaClip`/`_Cutoff`/`_Cull`. Everything that is not already one texture is
+**packed the glTF way** (R = AO, G = roughness, B = metallic; PNG/TGA/BMP decoded in-process, other
+formats through `sharp`) — one metallic-roughness(+occlusion) texture per material. `--no-unity`
+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
+files came from the same rig (the Mixamo case). `retarget` drives one rig with a completely
+different rig's clips — different bone names, different chain lengths, different proportions,
+different local axis conventions, even different facing:
+
+```
+lecodes assets retarget fox.glb --from Wolf_Animation.fbx --map auto --clips wolf_walk wolf_run -o fox-anim.glb
+lecodes assets retarget giraffe.glb --from Deer_Animation.fbx --auto-map      # writes giraffe-from-Deer_Animation.map.json to edit
+lecodes assets retarget giraffe.glb --from Deer_Animation.fbx --map giraffe-from-Deer_Animation.map.json -o giraffe-anim.glb
+lecodes assets retarget fox-anim.glb --from Wolf_Howl.fbx --map … --keep-clips --clip-names howl
+lecodes assets retarget fox.glb --from Wolf_Animation.fbx --skeletons        # both bone lists, to write a map by hand
+lecodes assets retarget fox.glb --from Cat.fbx --map auto --anim Cat_Sleep.anim   # donor clips that live outside the FBX
+```
+
+**The map** is target-bone → donor-bone; `root` names the bone that receives root motion. `--map auto`
+/ `--auto-map` derive it from the two skeletons' SHAPE — root, spine, neck, head, jaw, ears, tail and
+the four legs (side + front/back) are read off the bind pose, then paired chain by chain with bones
+matched by arc length (names only break ties when they agree: `backAnkle`↔`Ankle_L`). It works on
+`joint1…joint42` rigs and prints exactly what it paired — read it before trusting it. Optional keys:
+
+```json
+{ "root": "Hips",
+  "bones": { "Hips": "Root_M", "chest": "Chest_M", "backleg": "Hip_L", "backleg0": "Knee_L", "…": "…" },
+  "align": { "chest": "keep", "tail": "direction", "head": [ "headend" ] },   // per-bone reference policy (see below)
+  "legs": [ "backleg2", "R_backleg2", "frontleg2", "R_frontleg2" ],        // feet, when auto-detection picks wrong
+  "donorRef": "auto" | "bind" | { "clip": "wolf_idle", "time": 0 } }
+```
+
+**How it works.** Everything happens in WORLD space, where a rotation means the same thing in both
+rigs: `ΔR(t) = Rdonor(t)·Rdonor_ref⁻¹` is applied to the target's own reference orientation and
+converted back to local against the already-retargeted parent. That transfer is exact — the thing
+that decides quality is what the two REFERENCE poses are and what happens where proportions differ:
+
+- **Donor reference** (`donorRef`, default `auto`). An exporter's bind is often a posture the clips
+  never visit — the polyperfect wolf binds upright on vertical thighs and walks 10% lower with its
+  thighs 30° forward; measured from that bind every clip reads as "crouch and lean". When the two
+  binds put the legs differently (>12°: different conventions), the donor is referenced to the MEAN
+  pose of its walk (else idle, else the longest clip) — its actual neutral posture. When the binds
+  agree, bind-to-bind is the faithful transfer (an identity retarget reproduces the donor exactly).
+  `--donor-ref bind|auto|<clip>` overrides.
+- **Target reference**, per bone: `keep` its bind orientation, or `direction` — turn it so the bone
+  points the way the donor's does (an auto-T-pose step, measured to the nearest mapped descendant).
+  A target that binds in a STANCE (feet level, legs hanging) keeps everything: that is its natural
+  posture and the donor's deltas ride on it — the horse stays tall under wolf clips, the giraffe's
+  neck stays up under deer clips. A target that binds posed (T-pose, folded legs) keeps its core
+  (root, pelvis, chest, head — artists put those joints anywhere, so their joint lines are not
+  comparable) and direction-aligns its chains. `align` overrides per bone.
+- **Feet** (`--ik legs`, the default). Directions transfer, positions do not: with different
+  front/back leg ratios the feet float or sink, which the eye catches first. Legs are detected from
+  the map (lateral chains reaching the ground; a foot is what stands on the donor's ground, a horse's
+  wrist-ended front leg is not), the reference pose is planted (root lowered/raised, every foot bent
+  onto the ground), then every frame each foot gets a goal built as THE TARGET'S OWN STANCE plus the
+  donor's departure from ITS stance, scaled by that leg's length ratio, on all three axes — height
+  above each rig's own stance level, and the horizontal offset each rig plants its foot at under its
+  own hip — and a FABRIK pass from the FK pose bends the chain onto it. Both builds are therefore
+  preserved: a target that tucks its feet inboard of its hips keeps doing so against a donor that
+  stands on vertical legs. (Copying the donor's absolute foot-under-hip offset instead planted this
+  repo's fox — which tucks each foot ~8% of body height inboard, while every polyperfect animal
+  stands vertical — bow-legged in every clip.) When the legs are scaled copies the goal IS the FK
+  pose, so IK only ever spends the proportion residual; goals out of reach are reported per leg.
+- **Root motion** is scaled by the mean leg-length ratio (a stride is leg length, not body height),
+  so stance feet that were still on the donor stay still on the target.
+- **Chain lengths.** A longer donor chain collapses for free (the target's `chest` mapped to
+  `Chest_M` picks up Spine1+Spine2, because a world rotation already contains everything above it).
+  A longer target chain — unmapped bones between two mapped ones — interpolates the delta along the
+  chain (a 6-bone spine against a 2-bone one bends everywhere, not at one joint).
+- **Spaces.** The anchor is the BIND pose (inverse of the skin's inverse-bind matrices), never the TRS
+  on the nodes — the wolf's node pose is 0.37 m from its bind. A skin whose bind space is scaled
+  against node space (Maya "actor" exports, ×100) is rescaled; a donor facing the other way is turned
+  (facing is read from the skeleton shape, so `joint1…` rigs work too); non-uniform scales are refused.
+
+- **Second pass on proportions** (humanoid plan phase 3, 2026-08-27; the quadruped path shares the
+  planting and the root-motion switch):
+  - **A humanoid foot = contact + orientation** (2026-08-27). The leg's IK effector is the ankle,
+    but its goal comes from the BALL of the foot (the canonical `Toes` bone): the ball goes where
+    the donor's ball goes (leg and foot each scaled by their own ratio, stance-corrected), the foot
+    keeps the donor's rotation on the target's own flat bind, and the ankle follows from the two.
+    Rigs put the ankle at different places over the ball — a boot's foot bone dives 56° to the ball,
+    X-bot's 27°, both soles flat: driving the ball with the foot as an IK link let the solver pick
+    the foot's pitch (50° off the donor in the swing), transferring the ankle's position AND the
+    foot's rotation lifted the boot 10 cm off the ground at toe-off. Now the stance foot is flat,
+    toe-off has the heel up and the toes on the ground, and the report says `contact <ball>` when
+    it differs from the effector. What the two feet's shapes cost at full extension (a few cm) is
+    silent; `reach` reports what the LEG cannot do.
+  - **Foot planting** (default; `--no-plant`). While a donor foot stands still on its ground (under
+    15 % of a leg length per second, within 6 % of a leg length of its stance height, ≥ 3 frames),
+    the target's foot goal is held at ONE world point — the mean of where the FK would have put it
+    over the span, which splits the slide between landing and lift-off; a 4-frame ease at each end
+    hides both halves, a span across a cycle's seam is one plant held modulo the clip's travel. A
+    span whose mean sits more than 5 % of a leg length from some frame's FK goal is a shuffle, not a
+    plant, and is left alone. Per-leg ratios and the hips' own sway otherwise slide a planted foot a
+    few cm per step. The planted point is the contact (the ball rolls under a rising heel; the ankle
+    moves). Reported per leg (`planted N frames`) and per clip as spans.
+  - **Where the travel goes** (`--root-motion auto|hips|root|none`). A rig with a root ABOVE the hips
+    gets the donor's horizontal travel on the root and the vertical bob on the hips (`root`, the
+    default when such a root exists — a character controller reads the root's travel and must not
+    bob with it); `hips` puts everything on the hips as the donor had it; `none` strips the travel
+    for an in-place clip (feet still planted in the travelling frame, so they slide back under the
+    body like a treadmill). A donor whose hips bob relative to their own root (MoCap Central:
+    `root` travels, `pelvis` bobs) has that bob re-applied on the target's hips.
+  - **Hands as effectors** (`--ik hands`): the same ratio-scaled goal as a foot, measured from the
+    upper arm, chain capped at upper + lower arm, for clips where the hands meet or hold.
+  - **Twist helpers** (`--twist N`, default 0.5; `off` = ride rigidly). A helper at fraction `t`
+    along its limb bone takes `f·(t·twistOut − (1 − t)·twistIn)` about the bone's axis on top of
+    riding it — near the joint it counter-rotates the bone's own axial turn (the shoulder skin stays
+    with the clavicle), near the far end it follows the child's (the wrist follows the hand's
+    pronation). Helpers come from the avatar's `twist` map (shape classifier or `.avatar.json`).
+  - The stance correction inside a foot goal (where THIS rig rests its foot under its hip, against
+    where the donor does) is shrunk — never the donor's vector — when it would put the goal past the
+    leg's length (a running push-off on a rig whose hips sit higher above its feet); that removed
+    the "out of reach" residue on Humanoid_F.
+
+What it does not do yet: stride warping when a leg is far too short for the donor's reach (reported
+as "out of reach"), torso pitch to compensate for mismatched front/hind leg ratios; for humanoids
+the knee/elbow bend-plane roll of the UPPER arm and the legs —
+[docs/humanoid-retarget-plan.md](../../docs/humanoid-retarget-plan.md).
+
+### Humanoids — avatars
+
+A humanoid rig is described by its **avatar**: its bones named in the Unity/VRM humanoid canon
+(`Hips`, `Spine`/`Chest`/`UpperChest`, `Neck`, `Head`, `Jaw`, `LeftEye`…, `LeftShoulder`/`LeftUpperArm`/
+`LeftLowerArm`/`LeftHand`, `LeftUpperLeg`/`LeftLowerLeg`/`LeftFoot`/`LeftToes`, `Left Thumb Proximal`…
+— 55 bones). An avatar belongs to ONE rig; a humanoid map is two avatars joined on the canon, so
+each rig is mapped once and any pair retargets.
+
+```
+lecodes assets avatar girl.glb                                  # read the avatar off the skeleton's shape
+lecodes assets avatar girl.glb --meta SK_Girl.fbx.meta -o girl.avatar.json   # check vs Unity's map, write Unity's
+lecodes assets retarget girl.glb --from Swat.fbx --auto-map      # both rigs' avatars from shape → map.json
+lecodes assets retarget girl.glb --from Swat.fbx --avatar girl.avatar.json --map auto --clips Walking
+```
+
+`avatar` reads the structure off the bind pose (`src/retarget/humanoid.ts`): the hips are the joint
+two chains hang from that reach the ground on opposite sides; the hands are the lateral joints fanning
+out into short chains (fingers) — a weapon socket or IK target on the hand is shed; the spine is the
+centre path from the hips to where the arms meet; the head is the last branch above the arms (hair
+rigs branch below it, so a `head` name breaks that tie); the toes say which way is forward, and so
+which side is left. Spine bones: 1 → `Spine`, 2 → `+Chest`, 3 → `+UpperChest`, more → first /
+arc-middle / arm-attach with the rest **bridged**; a second neck bone and finger metacarpals bridge
+too. **Twist/roll helpers** (leaf children on their parent's axis — `upperarm_twist_01_l`,
+`calf_twist_02_r`) are recorded as `twist: { bone: canonical }`, never mapped. Names only break ties
+(thumb vs index when both are named; a `jaw` child) and the report says when they did. Everything
+else (hair, cloth, `ik_*`, bag, breasts) is listed as "not part of the body" and keeps its bind.
+
+**A person's word rides in the avatar** (`.avatar.json` `transfer`, written by the character studio,
+read by `retarget --avatar`): `align: { <canonical bone>: "keep" | "align" }` — this bone is BUILT
+that way (keep the bind, whatever the angle) or POSED (align to the donor, the 8° threshold
+notwithstanding; a standing leg too); `roll: { Left?, Right? }` — degrees added to the measured palm
+roll per arm, for a finger that lands almost right; and the transfer settings (`rootMotion`,
+`plant`, `hands`, `twist`) the CLI takes as defaults — flags still win. The report lists
+`under 8° kept` bones with their angle so the decision can be checked, and `avatar transfer: …`
+says what the file asked for.
+
+**The humanoid transfer** (`retarget` with both avatars — `--map auto`, `--avatar`, or a map.json
+that carries `avatars`) keeps the world-delta machinery above and decides the reference by canonical
+ROLE: hips, spine, neck, head, face and (standing) legs keep their bind; shoulder → upper arm →
+forearm → hand and every phalanx align to the donor's bind directions with explicit references (the
+hand to its finger bases), but only past an **8° threshold** — under it a mismatch is joint placement
+and stays, over it is posture (an A-pose against a T-pose, a bent elbow) and turns. Direction fixes
+two of three degrees of freedom; the **palm roll** — where the palm faces, the thing no direction can
+see — is read off the knuckle line (index base → little base) across the forearm, and the forearm
+chain turns until the target's line lies where the donor's does. Metacarpals ride the hand rigidly.
+The donor is referenced to its bind (its clips are authored on it); a target `root` above the pelvis
+that shares the donor's hips takes the hips' travel only. An identity retarget is exact
+(`tests/humanoidRetarget.test.ts`, key reduction off); Mixamo Walking on the zoo lands arm directions
+within 3° and palms within 10° on every frame.
+
+A Unity model importer's `.meta` carries Unity's own humanoid map: `--meta` diffs the shape result
+against it — the zoo in the plan agrees on every bone but the Chest/UpperChest picks on a 5-bone spine
+— and `-o` with `--meta` writes Unity's map as the `.avatar.json`. `retarget --avatar` / `--donor-avatar`
+accept either file; without them both rigs classify from shape (a biped↔quadruped pair is refused).
+
+Bind space: IBMs live in the MESH's geometry space. When an exporter parks the Z-up→Y-up turn on a
+geometry helper node (Female Runner's `Humanoid_F`) or ×100 on the mesh node (Maya "actor"), `rig.ts`
+folds that node's world transform in front of `inv(IBM)` — kept only when it brings the bind closer to
+the node rest pose.
+
+### Donors whose clips are not in the FBX
+
+Asset packs routinely ship the rig as FBX and the animations as Unity `.anim` assets — the
+polyperfect cat and all three dogs have EMPTY FBX files and eight `.anim` clips each. `--anim` reads
+those directly (`src/retarget/unityAnim.ts`, YAML only — a project saved with binary serialisation
+has to be re-exported with *Asset Serialization = Force Text*) and attaches them to the donor rig as
+clips, bound by the LAST segment of each curve's transform path:
+
+```
+lecodes assets retarget fox.glb --from Cat.fbx --map fox-from-cat.map.json   --anim Cat_Walk.anim Cat_Idle.anim Cat_Sleep.anim Cat_StandUp.anim   --clips Cat_Sleep Cat_StandUp --clip-names sleep stand_up -o fox-cat.glb
+```
+
+Pass the donor's locomotion clips even when you do not want them in the output: `--donor-ref auto`
+takes the donor's neutral posture from a walk/idle, and without one it falls back to the bind pose.
+
+**Skeleton-only clip files** — the other pack convention (Female Runner, MoCap Central, Mixamo
+"without skin"): each clip is an FBX of nodes + curves and NO mesh, so it has no skin to classify
+and no bind to measure from. `--donor-rig <model.fbx|.glb>` names the rig it was animated on; the
+clips bind to it by bone name (exact, then without the `namespace:` prefix — `rebindClips` in
+`rig.ts`) and the model's bind, skin and avatar carry the motion:
+
+```
+lecodes assets retarget vex.glb --from MCU_af_Loco_Walk_Fwd.FBX --donor-rig rig_MCUnity.fbx --map auto -o vex-mc-walk.glb
+```
+
+Whether a clip file IS the character's own rig (copy the tracks by name, the Mixamo flow) or only
+shares its naming convention (two Unreal-style rigs — retarget) is decided by `sameSkeleton`:
+≥ 80 % of the names must match AND every matched bone ≥ 5 cm must keep its local offset's
+DIRECTION (the child in its parent's frame — fixed by the rig, unlike the node rotations, which
+a clip file carries posed at its first frame). A Mixamo character against another's clip stays
+within ~20°; MoCap Central's rig against IdaFaber's turns the pelvis by 88° — a copied clip would
+lay the character down.
+
+### What a short spine cannot borrow
+
+Rotations transfer; positions follow from the TARGET's own bones. Leg IK covers that for feet, but
+nothing covers the spine, so a clip whose whole point is a spine CURL does not survive a target with
+fewer spine bones. The cat sits by curving a 7-bone spine to hold its chest up over a dropping
+pelvis; this fox has two spine bones and no way to curve, so its chest is simply carried down by the
+pelvis and the head ends up on the floor (4% of body height, against the cat's 79%). Hanging the
+pelvis on a mid-spine bone instead recovers part of it (27%) but then breaks lying-down clips, whose
+heads go through the floor. Clips that END lying (`Sleep`) or start there (`StandUp`) transfer fine —
+they need no upward curl.
+
+### Seeing the result
+
+A bone map is judged by eye. `tools/filmstrip.ts` skins a clip on the CPU and writes a PNG strip —
+no browser, no GPU, no engine, so it runs on every iteration:
+
+```
+bun tools/filmstrip.ts fox-anim.glb strip.png 6 wolf_walk threequarter
+BONES=1 CELL=360 bun tools/filmstrip.ts fox-anim.glb strip.png 5 wolf_walk side   # skeleton overlay
+BIND=1 BONES=1 bun tools/filmstrip.ts fox.glb bind.png 1 - side                     # the bind pose itself
+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, `runtime/web` → `node anim-check/model-check.mjs`.
+
+## Unreal packs — `.uasset` skeletons, clips, meshes
+
+An Unreal asset-store pack is a Content folder of **uncooked editor packages**: one `.uasset` per
+asset with everything inline. `convert`, `probe` and `retarget` read them directly — no Unreal
+install, no FBX export step:
+
+```
+lecodes assets unreal ls "Stairs Set/StairsSet"                       # triage: classes, rigs, what is unreadable and why
+lecodes assets probe .../A_Stairs_WalkFwd_Up_Loop.uasset              # engine, data model, skeleton, keys, root travel
+lecodes assets convert .../SKM_Manny.uasset --clips .../Animations/Mannequin/**/*.uasset -o manny.glb
+lecodes assets convert .../A_Stairs_WalkFwd_Up_Loop.uasset -o walk.glb            # clip-only GLB (its skeleton + the clip)
+lecodes assets convert hero.glb --clips .../A_Stairs_WalkFwd_Up_Loop.uasset       # merge one onto YOUR character by bone name
+lecodes assets retarget vex.glb --from .../SKM_Manny.uasset --anim .../Walk/*.uasset --map auto --root-motion hips -o vex-stairs.glb
+```
+
+**Both data models are read.** An `AnimSequence` keeps its raw motion in one of two places, and a
+pack's choice is not yours: `AnimDataModel` is bone tracks (what an FBX import writes), while a clip
+authored or edited in **Sequencer** (UE 5.2+, through a Control Rig) keeps the same motion as
+MovieScene channels — one FK control per bone, nine `FMovieSceneFloatChannel`s each (3 translation,
+3 rotation as an `FRotator` in degrees, 3 scale). `sequencer.ts` evaluates those onto the clip's own
+frame grid, so callers never learn which model a file used. The grid lands exactly on the authored
+keys (checked across a pack's 48 Sequencer clips: 0 ms offset, 0 value error), and the channels'
+constant values reproduce the skeleton's reference pose to 1e-4 cm and 0.001° — which is what pins
+the channel order and the `FRotator` convention.
+
+**What is read.** `SkeletalMesh` (LOD geometry, UVs, skin weights, bone list — from the editor
+import data the FBX importer left behind), `Skeleton` (bones + reference pose), `AnimSequence`
+(the raw uncompressed bone tracks of its `AnimDataModel`, plus fps, length, root-motion flag,
+additive type, sync markers / notifies), and `Texture2D` — the SOURCE image the artist imported,
+not the compressed mips a cooked build ships (see **Textures** below).
+
+**Where a clip's skeleton comes from.** An AnimSequence names it only as an object path
+(`/Game/StairsSet/Demo/Mannequins/Meshes/SK_Mannequin`), where `/Game/` is the pack's Content
+folder — which nothing on disk marks. The path is turned into a relative file name and looked for
+walking up from the clip; the first directory that answers IS the Content root. `--skeleton
+<SK_*.uasset>` names it outright, `--content-root <dir>` names the folder. A `SKM_*.uasset` works
+as a skeleton too (its own bone list is the bind reference).
+
+**Coordinates.** UE is centimetres, X-forward/Y-right/Z-up and left-handed; glTF is metres, Y-up
+and right-handed. A `.uasset` GLB has to be interchangeable with one made from the same pack's FBX
+(both feed `--clips` and the retargeter), so the conversion reproduces what UE's FBX exporter plus
+ufbx do: mirror Y on every local transform, and turn the ROOT bone −90° about X. Checked against
+the Stairs pack's own `SourceFiles.zip`: all 267 channels of a clip match by bone name to
+**1e-5 m / 0.02°** (`tests/unreal.test.ts`), and the recipe's composition is pinned by a unit test —
+the per-bone rules must add up to the global `(x, z, y)·0.01` map on world points.
+
+**Limits** (each one says so at the point it bites, rather than producing a broken GLB):
+
+| Not supported | What you get |
+|---|---|
+| UE 5.4+ / UE 5.5+ packages, UE4 packages, cooked assets | refused by version, with the engine that saved the file |
+| meshes whose LODs were generated in-engine (no import data — the Stairs pack's UE4 mannequin) | refused; only the skeleton of such a mesh can be read |
+| morph targets, curves, sockets, physics assets, Oodle-compressed MESH bulk | reported, not guessed at |
+
+Twelve bones per vertex become four (top by weight, renormalised) — the trim is reported as a
+percentage of redistributed weight. Triangle winding is decided from the data (the mirror reverses
+handedness) rather than hidden behind a double-sided material.
+
+**Textures.** A texture asset keeps its source image (usually the original PNG) inside an
+`FCompressedBuffer`, compressed with **Oodle** — proprietary, so nothing is shipped here. The
+decoder is loaded from a library the machine already has:
+
+```sh
+export LECODES_OODLE=".../Engine/Binaries/ThirdParty/Oodle/Win64/oo2core_9_win64.dll"   # any UE install
+# or drop the file into ~/.lecodes/oodle/ — Unreal installs are also found automatically
+lecodes assets unreal tex T_Manny_01_D.uasset -o manny_d.png   # one texture, out
+lecodes assets convert SKM_Manny.uasset -o manny.glb           # textures wired to the materials
+```
+
+Without it the conversion still runs and says so once; only the materials stay grey. With it, each
+slot's `MaterialInstanceConstant` is read and its `TextureParameterValues` are wired to glTF:
+base colour, normal, and ORM (UE packs occlusion/roughness/metallic into R/G/B, which is exactly
+what glTF reads). Two fixes are applied on the way, both required and both verified against the
+render: a `TSF_BGRA8` source has its red and blue channels the other way round (without the swap the
+mannequin comes out blue), and UE authors normal maps DirectX-style, so the green channel is flipped
+for glTF (`--no-normal-flip` keeps them as they were). Textures are capped at `--max-size` (2048)
+and re-encoded — JPEG unless the alpha channel is actually used.
+
+What is NOT wired: everything the material graph would have to be evaluated to understand. The UE5
+mannequin's material names seven textures — a bent normal, an aniso/AO/paint mask, a clear-coat
+mask, an MSR pack, a tangent map — and only the base colour and the normal map have an honest glTF
+slot. The rest are listed in the report (`not in glTF: …`) rather than guessed into one. Scalar and
+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
+weights — otherwise the humanoid classifier finds no legs and refuses the rig. Unskinned ends
+(`ik_foot_root`, `ik_hand_gun`, `weapon_l`, `interaction`, `center_of_mass`, `root`) stay out of the
+body, which is what they should be.
+
+Stair clips carry vertical root travel (0.40 m per loop on the Stairs pack's walk-up). `--root-motion
+hips` keeps the climb on the character; `auto`/`root` treat vertical motion as hips bob and would
+swallow it. Feet below the origin plane on a walk-DOWN clip are reported as "toe under the ground" —
+expected for stair content, where the ground is not flat.
+
+
+## Scale
+
+`probe` and `doctor` always **report** the model's rendered world size; nothing is changed without a
+flag. A skinned primitive ignores its node's transform (glTF spec), so the size is measured through
+the skin's bind space (`world(joint₀)·IBM₀`) — measuring via the mesh node reports garbage on exactly
+the assets that are mis-scaled.
+
+| flag | what it does |
+|---|---|
+| `--fix-scale` | guess the unit and bake it: cm / mm / feet / inches / the Blender-FBX `0.01` armature quirk. Picks the **smallest** correction that lands the largest dimension in 0.1–100 m |
+| `--scale N` | bake an explicit factor (works on clip-only files too) |
+| `--scale-to M` | bake whatever makes the largest dimension `M` metres |
+
+The factor is **baked into the data** — positions, node translations, IBM offsets and translation
+tracks all × s — not parked on a wrapper node. No node is added and no local scale is rewritten, so
+every node path an app addresses stays what it was. Rotation and scale tracks are untouched by
+construction: scaling only translations gives `world' = S·world·S⁻¹`, and the skinning identity then
+needs `IBM' = S·IBM·S⁻¹`, which is just the IBM's translation column × s.
+
+Quantized (`KHR_mesh_quantization`) positions are refused rather than silently corrupted.
+
+## Shading — why a downloaded model renders too bright
+
+`doctor` always reports two material quirks that make an asset look washed out, and neither one is
+the usual suspect (metallic, or the texture):
+
+- **self-lit** — the base colour texture is *also* wired into `emissiveTexture` with
+  `emissiveFactor = [1,1,1]`, so the shader draws `lit(albedo) + albedo`: roughly twice as bright as
+  intended, with the shading flattened out. Common from Sketchfab downloads and several FBX
+  exporters. `--fix-emissive` drops it and leaves the material otherwise PBR.
+- **specular boost** — `KHR_materials_specular` with a `specularColorFactor` above 1.
+
+`--unlit` goes further and converts the material to **`KHR_materials_unlit`**: flat
+`baseColorFactor × baseColorTexture`, no lights, no IBL, no exposure — the shading model hand-painted
+stylised assets are usually authored for. It also clears the emissive and drops specular/ior/normal/
+occlusion/MR inputs, because gltfio *refuses* to combine specular with unlit ("Cannot use specular
+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` +
+  `vendor/ufbx`, built by `build-wasm.sh` into `src/wasm/fbxReader.js` — a single-file module, no
+  native builds, runs in Bun/Node/browsers). Everything is converted to glTF conventions in C:
+  meters, right-handed Y-up (`space_conversion = MODIFY_GEOMETRY`), geometry transforms / inherit
+  modes as helper nodes, triangulated + welded primitives, top-4 skin weights renormalized, UV v
+  flipped, animations **baked** (30 fps, key-reduced, trimmed to start at 0). One JSON description +
+  one binary arena cross the wasm boundary; `src/fbx/toDocument.ts` builds the Document.
+- **Textures** embedded: PNG/JPEG pass through, TGA/BMP decoded here (→ PNG), everything else via
+  `sharp` when installed; duplicates de-duplicated by content hash; external references resolved
+  next to the FBX / `textures/`.
+- **Materials**: ufbx's PBR view of FBX Phong/Lambert → metallic-roughness (opacity map → MASK,
+  opacity factor < 1 → BLEND, double-sided honored). Separate metallic/roughness maps are not
+  packed (factors used).
+- **`--clips`**: each clip file's animations are re-targeted onto the model **by bone name** (exact,
+  then the part after the last `:`/`|` — the same rule the SDK `Animator` uses); clip meshes/skins
+  dropped; unbound tracks counted + warned. Naming: a single-clip file → its stack name unless generic
+  (`mixamo.com`, `Take 001`, `Unreal Take`) → the file's basename; `--clip-names` overrides.
+  **Parent-space correction**: a track is a LOCAL transform, and two exports of one rig need not
+  agree on what sits above a bone — Unreal/Unity clip exports put `root` straight under the scene
+  (rest −90°X, the Z-up→Y-up turn) while the skinned-mesh export parks that turn on an armature node
+  and leaves `root` at identity; copied verbatim the turn applies twice and the character plays lying
+  on the floor (KINEMATION's Tactical Shooter Pack, every UE5 Mannequin export). For each bound bone
+  the converter compares the world transform of its parent in both files — with the clip's first
+  frame written onto every bone it animates, so only the unanimated STRUCTURE above differs, never
+  the hair-width rest-pose drift between re-exports — and re-expresses the track in the model's
+  parent space (`local_model = inv(Pmodel)·Pclip·local_clip`). Reported as an ℹ line per clip file.
+- Output goes through the same validation as the doctor (`validateGlb`) and a `probe` summary.
+
+Skipped in v1: cameras/lights, morph targets, NURBS.
+
+## Verified with
+
+`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.
+
+The Unreal reader was verified against two real packs — *Stairs Set UE 5.0-5.4* (UE 5.0: 159
+packages, 84 AnimSequences on two mannequins, a 26 MB zlib-chunked mesh bulk) and a UE 5.3 modular
+character pack (796 packages, raw bulk, all 48 clips Sequencer-authored) — every package parsed or refused
+with a reason, and the clips compared channel-by-channel against the pack's own FBX sources.
+`tests/unreal.test.ts` runs those fixtures when `LECODES_UE_PACK` (or the default pack folder)
+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 `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
+space and −Z facing, unnamed `joint1…joint42`): wolf → Meshy fox, lion → cat, wolf → horse / golden
+retriever, deer → giraffe, lion → elephant, all through `--map auto`, judged on `BONES=1` filmstrips
+next to the donor's own walk. `tests/retarget.test.ts` pins the invariants on toy rigs (exact
+direction transfer, keep/direction policies, bridges, leg detection + IK goals, donor reference).
+
+## Layout
+
+```
+native/fbx_reader.c      ufbx → JSON + arena (compiled to wasm)
+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 · 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) · 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/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/`.