lecodes-assets 0.1.0 → 0.1.2

package/README.md

@@ -4,6 +4,16 @@ FBX → GLB converter + GLB doctor, one package on one glTF-Transform `Document`
 `lecodes assets …` (optional peer of the `lecodes` CLI) or `bun src/cli.ts …` in the monorepo.
 Plan/rationale: [docs/animation-plan.md §2.9](../../docs/animation-plan.md).
 
+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
@@ -12,9 +22,87 @@ lecodes assets convert hero.fbx --ktx2                           # + textures
 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 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
@@ -192,7 +280,16 @@ Both engines implement it: Filament through gltfio's `unlit_opaque` ubershader,
 - **`--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`) → the file's basename; `--clip-names` overrides.
+  (`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.
@@ -219,8 +316,11 @@ 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 · validateGlb (mirror of viewer's)
+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 (skeleton classification + chain pairing) · unityAnim.ts (Unity .anim YAML reader)
-tools/filmstrip.ts       CPU-skinned PNG filmstrip of a GLB clip (browser-free visual check)
+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
 ```