Papay-Shooter/docs/3D_ASSET_PIPELINE.md

# Character Pipeline: source model → rigged → animated → in-game

One command turns a model into a playable character skin:

```bash
python tools/pipeline.py --uid <sketchfab-uid> --name space_marine
```

That downloads the model, moves the shared animation library onto it, writes
`assets/characters/skins/space_marine.glb` plus a `.rig.json` sidecar, verifies
the result, and registers it in `skins.json`. Restart the game — the skin is in
the main menu dropdown, fully animated in first AND third person, synced in
multiplayer.

## The one rule: keep the model's own rig

**If a model arrives with a skeleton, that skeleton is what ships.** Its bones,
its artist-painted weights, its separate per-part meshes, and its dedicated
skirt/hair bone chains all survive; only the ANIMATION is moved onto it.

This is the whole point, and the pipeline used to do the opposite. The old route
(`strip_rig.py` → `autorig.py` → `merge_animations.py`) discarded any foreign
skeleton, joined every mesh into one, and rebound the result by weighting each
vertex to its nearest four bone segments. It did that to work around a *naming*
problem — the retarget matched bones by exact name — and the cost was the entire
asset. Measured on the shipped `taila.glb` against the source it was built from:

| | source model | old pipeline output |
|---|---|---|
| vertices pulled by BOTH legs | 17 (0.1%) | **2817 (16%)**, worst a dead 50/50 |
| vertices at the full 4 influences | 26% | **86%** |
| meshes (body / cloth / hair separable) | 18 | **1** |
| skirt bone chains | 21 bones | **0** |
| hair bone chains | ~50 bones | **0** |
| limb twist bones | 8 | **0** |

A vertex pulled equally by both legs sits between them and stays there while
they separate, stretching every triangle around it — that is the squashing and
the "elongated boot". `characters/skin_leg_repair.gd` exists solely to undo this
at load time, by snapping weights and deleting triangles on a mesh it has to
rebuild every spawn.

The naming problem is now solved properly, in `tools/rig_map.py`, so nothing has
to be thrown away.

## The pipeline, step by step

| Step | Tool | What it does |
|---|---|---|
| 1. Find | `python tools/sketchfab_import.py search "anime robot" --rigged` | Search downloadable models (license shown per result) |
| 2. Download | `python tools/sketchfab_import.py download <uid>` | GLB + license JSON into `assets/characters/incoming/` |
| 3. Retarget | `blender --background --python tools/retarget.py -- in.glb assets/characters/animations out.glb` | Keeps the rig; moves the clip library onto it |
| 3b. *(unrigged only)* | `blender --background --python tools/autorig.py -- in.glb rigged.glb` | Fits the library skeleton and solves weights — lossy, see below |
| 4. Verify | `blender --background --python tools/verify_character.py -- out.glb` | Gates the build on the defects listed below |
| 5. Register | (automatic in `pipeline.py`) | Copies to `skins/`, adds an entry to `skins.json` |

`pipeline.py` chains all of it and picks the path automatically — it reads the
glTF container to see whether a `skins` array is present. Useful flags:

- `--input file.glb` instead of `--uid` for local files.
- `--rigged` — force the keep-the-rig path (needed for FBX, which cannot be probed).
- `--rebind` — force the lossy path. Last resort.
- `--height 1.6` — target character height in metres.

### How the retarget works

`tools/rig_map.py` resolves both skeletons to ROLES and pairs them up, so bone
names never have to match. It works structurally wherever a name would lie:

- **Hips** is found as the base of the longest non-limb, non-cosmetic chain —
  not by looking for "hips". Rigify calls it `DEF-spine`.
- **The head** is wherever that chain ends. A stock Rigify rig has no bone with
  "head" in its name at all; the head is `DEF-spine.006`.
- **Chains of different lengths** are matched by normalised position, so a
  6-bone spine is driven by a 5-bone one.

`tools/retarget.py` then bakes each clip as a rest-relative delta —
`R_world = src_pose · src_rest⁻¹`, applied as `R_world · tgt_rest` — rather than
copying absolute world orientation, which would force the library's bone roll
onto a mesh bound with a different one and twist every limb by a constant offset.

It also **rebuilds parenting**. A Rigify DEF-rig exports its chain roots
parented straight to the armature root (Rigify drives them by constraint, not
hierarchy), so on import the thighs, skirt and hair all hang off the root and
would float in place while the body moves. Orphans are re-attached by anatomy
where it is known and by rest geometry otherwise. **Cloth may only ever attach
to the trunk, never to a limb** — anchor a skirt panel to the nearest bone and
16 of Taila's 21 land on a thigh, where the panel rides one leg like a trouser
leg.

### What is deliberately NOT driven

Skirt, hair, twist and face bones get **no animation tracks at all**. They rest
relative to their parents and belong to the runtime instead. That split — clips
animate the body, physics animates the cloth — is what makes clothes read as
clothes, and it is why the exported clips only carry the ~53 bones they need
(`taila.glb` went from 3.5 MB to 2.9 MB even after regaining its textures).

## Secondary motion (`characters/spring_bones.gd`)

Skin weights can only ever make a garment a rigid shell of whatever it is
weighted to: weight a skirt to the thighs and it becomes trousers, weight it to
the hips and it becomes a bell that never moves. Neither is cloth. A skirt is
cloth because it LAGS. That is inertia, and it has to be integrated, not skinned.

Each cloth bone is a damped spring holding its tip toward where rigidly
following its parent would have put it, then pinned to the bone's length and
pushed out of the leg capsules so a skirt swings AROUND a thigh rather than
through it. Bone tip directions and capsule radii are **measured from the
model's own geometry at build time** and stored in the sidecar — a glTF skeleton
carries no bone tails, and Taila's skirt bones have no children either, so
nothing in the skeleton says which way a panel hangs or how thick a thigh is.

Tuning per class (hair stiffer and lighter, skirt slacker and heavier) lives in
`SpringBones.TUNING`.

### `<model>.rig.json`

Written next to every built GLB, so the runtime never re-guesses anatomy:

- `roles` — resolved bone per role. `ShooterPoseModifier` reads this; without it
  its hips/neck/head lookups silently missed on any rig that names them
  differently, and every lean and aim-pitch did nothing.
- `chains` — cloth/hair chains, with a measured tip vector per bone.
- `colliders` — leg capsules with measured radii.
- `twist` — limb twist bones.
- `weights_authored` — **measured**, not inferred from which branch ran. This is
  what decides whether `SkinLegRepair` runs at load time. A model that arrives
  unrigged still gets a sidecar, and its solved weights still need the repair.

Raw `.glb` **and `.json`** must be in the export include filter, or the sidecar
is missing from a build and every character loses its cloth.

## When a model has no skeleton

Then there is no authored weighting to keep and `autorig.py` fits the library
skeleton with nearest-bone weights. This is genuinely lossy and the verifier
reports it as warnings rather than failures, because no better result is
available:

```
[WARN] cross-leg blending is limited to draping cloth — 590 verts (21.2%)
[WARN] influences look authored, not solved — 78% of verts carry 4 influences
[WARN] model keeps its per-part meshes — 1 meshes
```

`miku` is such a model. `SkinLegRepair` stays on for it at load time.

Prefer, in order: a model that ships rigged → **Mixamo web** (upload FBX/OBJ,
place 7 markers, download rigged "without animations") → **Reallusion AccuRig**
→ UniRig / Tripo / Meshy. All of them produce a rig this pipeline will keep.

## Materials

Anime models are very often exported "unlit": `KHR_materials_unlit`, a **black**
`baseColorFactor`, and the real texture wired to `emissiveTexture`. Renderers
honouring the unlit extension use base colour and ignore emission — so Blender
reads black, never references the images, and imports with `bpy.data.images`
*empty*. The character comes out a silhouette, and there is no node graph left
to patch afterwards.

`tools/gltf_fix.py` rewrites the container **before** import: emissive becomes
base colour, the unlit flag is dropped. The game shades characters with its own
toon material off ALBEDO anyway.

## Swapping the animation library

`assets/characters/animations/_library.glb` is the CC0 Quaternius Universal
Animation Library. Clips map through `LIBRARY_CLIP_MAP` in `tools/retarget.py`
(18 mapped: Idle, Walk, Run, Sprint, Jump, Fall, Land, CrouchIdle, CrouchWalk,
Dash, Death, Hit, Dance, Grapple, PistolIdle/Shoot/Reload, Throw).

Characters no longer have to be rigged to the library's skeleton, so **replacing
`_library.glb` does not require re-rigging anything** — just rebuild the skins.
Missing clips are fine: the game falls back along sensible chains
(`Slide → CrouchIdle → Idle`, `WallRun → Run` — see `CLIP_FALLBACKS` in
`characters/skinned_player_model.gd`).

## Measuring, not eyeballing

- `blender --background --python tools/verify_character.py -- <glb>` — the build
  gate. Every check corresponds to a defect this project actually shipped.
- `godot --headless --path . -s res://debug/limb_deform_check.gd -- <glb>` —
  skins the mesh itself and reports lengthwise stretch and cross-section loss
  against the skeleton's REST pose, so an unposed model reads exactly 1.00 and a
  wrong metric is visible immediately. Read its header before trusting a number
  you add: three earlier versions of this measurement were themselves wrong and
  nearly caused bad "fixes".
- `godot --path . --windowed --resolution 1280x720 -s res://debug/anim_capture.gd -- <out_dir> <skin_id>`
  — renders every movement state front and side.

Current Taila, worst over a run/walk/jump/fall/slide/dash sweep: knee
cross-section 0.85–0.86, everything else 0.89–1.00, worst stretch 1.16.

## How it works in-game

- **`SkinManager`** (autoload) reads `skins.json` at boot; the selection persists
  per user and syncs via `synced_skin_id`.
- **`SkinnedPlayerModel`** loads the GLB, reads the sidecar, installs
  `ShooterPoseModifier` (lean / ADS / slide / wall-run / weapon hold) then
  `SpringBones` — in that order, so the springs react to the FINAL body pose.
- **`SkinJointHelper`** runs for every model regardless of rig. It is not a
  weight repair: linear-blend skinning collapses any joint by cos(θ/2) however
  good the weights are. It subdivides the knee through helper bones. It resolves
  the joint's parent from the SKELETON — hardcoding `DEF-thigh.L` meant it
  silently did nothing on a rig with twist bones, and the knee measured 0.76
  instead of 0.85.
- **First person (owner):** the model renders shadows-only (the camera sits
  inside the head). Press **V** to swap to the over-the-shoulder camera.
- **Licensing:** every Sketchfab download writes `<name>.license.json`. CC-BY
  models require crediting the author — surface these in a credits screen.

## Troubleshooting

- *Character is a black silhouette* — unlit materials; see **Materials**. Check
  the built GLB actually has images.
- *Model T-poses* — the GLB has no animations, or the retarget produced a frozen
  rest pose. `verify_character.py` catches both.
- *Skirt rides one leg* — a cloth bone got parented to a limb. Cloth must anchor
  to the trunk only.
- *Cloth is rigid* — the sidecar is missing (check the export filter) or the
  clips are keying cloth bones (`verify_character.py` checks this).
- *Cloth flies off the model* — a spring instability. `SpringBones` substeps and
  clamps for exactly this; do not remove those guards.
- *Limbs squash at a stride* — measure with `limb_deform_check.gd` before
  changing anything. Renders are repeatedly misleading; a slim anime leg at full
  stride genuinely looks stretched.