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.

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:

npm install -g lecodes-assets

KTX2 (--ktx2) additionally needs KTX-Software: 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 PrefabInstances 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:

{ "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.

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 FMovieSceneFloatChannels 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:

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 -o

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 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/.