Papay-Shooter/.claude/skills/character-pipeline/SKILL.md

---
name: character-pipeline
description: Import, rig, stylize and animate an anime-styled character into Papaya-Shooter as a selectable skin — keeping the model's own skeleton, artist weights and separate body/cloth/hair meshes, with cloth and hair driven by the spring solver. Use when adding a new playable character, re-importing an existing one, debugging skinning/cloth/hair/animation problems on a character, or changing the cel-shaded look. Triggers on "add a character", "import a skin", "new playable model", "skirt clipping", "hair flailing", "T-posing", "character looks squashed".
---

# Character pipeline

Turns a source model into a playable, cel-shaded, cloth-simulated character skin.

The whole design follows one principle, which is also what the Hoyoverse-class
anime pipelines (Genshin / Star Rail / Zenless Zone Zero) are built on:

> **The character is not one object. It is a body, a set of garments, and hair —
> authored separately, rigged separately, and moved by different systems.**
> The body is skinned and animated. The garments and hair are bone chains that
> the animation never touches; physics moves them. Keeping those separate is
> what makes the result read as an anime character instead of a mannequin in a
> painted-on costume.

Everything below exists to protect that separation.

## The one rule

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

The old route (`strip_rig.py` → `autorig.py` → `merge_animations.py`) solved a
bone-*naming* problem by destroying the asset — 18 meshes became 1, 21 skirt
bones and ~50 hair bones became 0, and 16% of vertices ended up pulled by both
legs. `tools/rig_map.py` solves naming properly now. **Never reach for
`strip_rig.py` or `--rebind`** unless the model genuinely has no skeleton at all.

## Doing it

```bash
# From an already-rigged local model (the normal case)
python tools/pipeline.py --input assets/characters/incoming/<name>.glb --name <name> --rigged

# From a Sketchfab UID (needs SKETCHFAB_API_TOKEN)
python tools/pipeline.py --uid <uid> --name <name>

# From an unrigged mesh — auto-rigs, and accepts the quality loss
python tools/pipeline.py --input <mesh.glb> --name <name>

# Rigged (or auto-rigged) but with NO skirt/hair bones — grow them, or the
# costume is welded solid and the spring solver has nothing to simulate
python tools/pipeline.py --input <model.glb> --name <name> --rigged --grow-cloth
```

Then, once, so Godot sees the new files:

```bash
godot --headless --path . --import
```

The result is `assets/characters/skins/<name>.glb` + `<name>.rig.json`, and a
registry entry in `skins.json` that `SkinManager` picks up with no code change.

Blender is required (`BLENDER_PATH`, or auto-found under
`C:\Program Files\Blender Foundation`). Godot lives at
`C:\Program Files\Godot\Godot_v4.7-stable_win64_console.exe`.

## The stages, and what each one protects

| Stage | Where | Protects |
|---|---|---|
| Fix unlit/emissive materials | `tools/gltf_fix.py` | Textures surviving import at all |
| Resolve bone ROLES, not names | `tools/rig_map.py` | The model's own skeleton |
| Rebuild parenting | `retarget.py::rebuild_hierarchy` | Limbs/cloth following the hips |
| Grow cloth chains (opt-in) | `tools/cloth_bones.py` | A costume that has no bones being able to move at all |
| Subdivide cloth panels | `retarget.py::subdivide_cloth_panels` | A skirt being able to bend at all |
| Retarget clips as rest-relative deltas | `retarget.py::retarget_clip` | Limbs not being twisted by foreign bone roll |
| Leave cosmetic bones unkeyed | `export_optimize_animation_keep_anim_armature=False` | Physics owning the cloth |
| Classify every SURFACE | `tools/surface_map.py` | The runtime never re-guessing what a surface is |
| Write the rig sidecar | `retarget.py::describe_rig` | The runtime never re-guessing anatomy |
| Cel look, per surface class | `LevelMaterials.apply_character_look` | Hair not reading as a solid dark cap |
| Cloth + hair | `characters/spring_bones.gd` | Clothes reading as clothes |
| Per-character judgement calls | `characters/tuning_store.gd` | Art direction not becoming another constant |

## The surface table

The sidecar carries a `surfaces` list saying what each mesh surface IS — `body`,
`cloth`, `hair`, `accessory`, or `linework` (the model's own ink shell, which is
not a surface of the character at all). It is keyed on the MATERIAL name, because
every character in this game arrives with its meshes called `Object_7` through
`Object_32` while material names survive the glTF round trip intact.

`SkinSurfaces` reads it and `apply_character_look` acts on it: hair takes a much
thinner outline than the body, cloth a heavier one and a crisper terminator,
accessories the heaviest. `SkinnedPlayerModel.surfaces_of(cls)` answers the
question for anything else that needs it.

Backfill a character that predates it, without re-importing:

```bash
blender --background --python tools/surface_map.py -- \
    assets/characters/skins/<name>.glb
```

New imports get it from `describe_rig`, built from the same chains the solver
uses, so the surface table and the cloth solver can never disagree about which
bones are a skirt.

## Per-character judgement

Anything derivable from the skeleton is derived. What is left is genuinely an
artist's call, and it lives in layered JSON rather than in a constant:

| File | Scope | Class |
|---|---|---|
| `assets/characters/weapon_holds.json` | character + weapon | `WeaponHoldTuning` |
| `assets/characters/rig_anchors.json` | character | `RigAnchors` |

Both layer `defaults` → `skins.<skin>._all` → `skins.<skin>.<subject>` through
`TuningStore`. An absent file means "use what the code derives", so nothing here
is required for the game to run. Adding a knob is adding a row to a `KNOBS` spec
table — the lab builds its whole UI from those.

`RigAnchors` is where "the grip sits here in the palm" lives. A hand bone's
origin is the WRIST; how far down the palm a grip belongs depends on the
character's hand and cannot be derived. It defaults to identity, and identity is
exactly the derived mount. Do **not** put a fixed rotation on the weapon mount
instead — a bone attachment is expressed in the BONE's axes, no two rigs agree on
those, and that constant is why the hand mount points were once wrong on every
character.

## The rig lab

```bash
godot --path . res://debug/rig_lab.tscn
```

Pick a character, a weapon, a pose or a single clip. Drag sliders for the HOLD
(character + weapon) and the ANCHORS (character), and save.

**The HOLD is per pose.** The runtime blends between exactly two holds, on
`ads`, so the lab offers two: low ready and aiming. Selecting a pose rebuilds
the hold sliders to that pose's — you never see a control belonging to the pose
you are not adjusting. Running and Crouched use the low-ready hold, and the
heading says so rather than letting someone tune "Running" and wonder why
standing still changed. `pitch` exists at low ready only: down the sights the
muzzle follows the camera, so there is nothing there to tune, and a slider that
does nothing is worse than a missing one.

**The wrists turn the HAND, not the gun.** The weapon is a child of a
BoneAttachment3D on the trigger hand, so the two are welded by construction: a
wrist rotation swings the barrel off the aim line and takes every control that
could correct it along with it, which made the knob useless for aligning a hand
to a gun. `ShooterPoseModifier.wrist_comp_r` is the exact counter-rotation in
the hand's local frame, and `SkinnedPlayerModel._hold_weapon_still` applies it.
To rotate the GUN inside the hand instead, use the grip rotation in ANCHORS.

Knobs that describe the WEAPON and the hands on it — where each hand sits along
it and off its barrel line, the finger curls, the weapon size — are shared,
because shouldering a gun does not move the hand along it. Both wrists take
pitch, yaw and roll in the gun's own frame, per pose. Click a surface class
to isolate it — that is how the classifier gets checked: click `hair` and
anything else still standing was misclassified.

**Drag the coloured markers.** They ARE the anchor points the hands are solved
onto — red the trigger grip, green the support hand, blue the buttstock — and
the one under the mouse swells and draws through the body so it can be grabbed
where the hands would otherwise hide it.

Dragging an anchor is not the same as any slider:

| | moves |
|---|---|
| `grip_offset` (ANCHORS) | the GUN, inside the fist |
| `gun_fore` / `gun_stock` (HOLD) | the hands ALONG the weapon's own axis |
| dragging a marker | the anchor itself, in three dimensions |

That distinction was the gap. `gun_fore` and `gun_stock` are distances along the
barrel, so the two hand anchors could slide up and down the gun and nowhere
else — no use for a handguard below the bore, an angled foregrip, or a pistol
whose grip is nowhere near its barrel line. A drag writes `grip_shift` or
`fore_shift` in the gun's own across/up/along frame, so a sideways nudge stays
sideways as the weapon pitches; the buttstock marker writes the shoulder pocket
for whichever pose is showing.

The anchors sit on the shoulder, and the arm chasing them moves the shoulder, so
a drag settles at 0.77x-1.13x of the mouse. Small enough to ignore — you stop
when it looks right — and measured, not assumed.

## Read before you touch anything

Load the reference that matches what you are doing. They are short and each one
is a list of things that cost a debugging cycle to learn.

- **`references/failure-modes.md`** — **read this first.** Seven characters
  shipped "All checks passed" and four were visibly broken. What each failure
  was, why the suite missed it, and the rule that generalises it to any model.
- **`references/separation.md`** — body vs. garments vs. hair: what must stay
  separate, how cloth chains are detected and classed, why cloth is never
  skinned to a leg, and the ZZZ-convention mapping.
- **`references/growing-cloth-bones.md`** — what to do when the source has no
  skirt or hair bones: how the chains are fitted to the geometry and re-weighted.
- **`references/rigging.md`** — role resolution, hierarchy rebuild, cloth panel
  subdivision, twist bones, joint helpers, the retarget maths.
- **`references/cloth-and-hair.md`** — the position-based spring solver, its
  colliders, per-class tuning, collision hulls, LOD and cost.
- **`references/stylization.md`** — cel shading, outlines, the imported
  line-work trap, eyes, materials.
- **`references/verification.md`** — every measuring tool, what each one
  actually measures, and the pose-reading trap that invalidated all of them
  once. **Read this before trusting any measurement.**

## Non-negotiables

1. **Never join meshes.** Per-part meshes are how body, cloth and hair stay
   separable — for materials, for the outline pass, and for the cloth solver's
   hull extraction.
2. **Never key cosmetic bones.** If a clip has tracks on skirt/hair bones, the
   AnimationPlayer overwrites the solver every frame and the cloth goes rigid.
3. **Never skin cloth to a leg.** A vertex weighted 0.9 to a thigh cannot be
   moved by its own cloth bone, so the solver loses the authority to push it out
   of that thigh — and the leg still overtakes it. There was a
   `bind_cloth_to_legs()`; it is deleted, and the note above its grave in
   `retarget.py` says why.
4. **Never run `SkinLegRepair` on authored weights.** It snaps weights and
   deletes triangles. It exists only to undo auto-rigging. It is gated on
   `weights_authored`, which is MEASURED, not assumed.
5. **Measure from inside the modifier pass.** See `references/verification.md`.
6. **Never assume an axis.** Up, forward and scale are all measurable from the
   skeleton. Assuming +Z is up scaled three characters 7x and left them on their
   backs — and the height check passed on every one of them, because the number
   being normalised always comes out right whether or not it was the right
   number. See `references/failure-modes.md`.
7. **Never look a bone up by name.** `tools/rig_map.py` resolves roles and writes
   them to the sidecar so nothing downstream has to guess. Any hardcoded spelling
   — `_find_bone(["RightHand", ...])`, a `thigh`/`shin` substring test — is a rig
   this project has not met yet. Four characters could not hold a gun because of
   exactly one such lookup.

## After importing

```bash
godot --headless --path . -s res://debug/spawn_smoke_test.gd      # 29 checks
godot --headless --path . -s res://debug/surface_class_check.gd   # every surface classified
godot --headless --path . -s res://debug/character_picker_check.gd # the escape-menu roster
godot --headless --path . -s res://debug/rig_anchor_check.gd      # anchors move the weapon
godot --headless --path . -s res://debug/cloth_clip_check.gd      # leg-through-cloth
godot --headless --path . -s res://debug/cloth_settle_check.gd    # idle stability
godot --headless --path . -s res://debug/cloth_perf_check.gd      # ms per character
godot --headless --path . -s res://debug/travel_dir_check.gd      # legs face travel
```

And LOOK at it, which is where four of the last five real defects were found:

```bash
godot --path . -s res://debug/roster_capture.gd -- <dir>   # every character, one shot each
godot --path . -s res://debug/ui_capture.gd -- <dir>       # every menu screen
godot --path . res://debug/rig_lab.tscn -- shot <png> <skin>
```

`surface_class_check` fails on any surface that falls through to the heuristic
rather than resolving from the table. That is deliberate: a model whose names
stopped matching still RENDERS, because the fallback catches it — it just
quietly loses its per-class art direction, which is exactly the kind of
regression nothing else would report.

What "good" looks like on Taila, for calibration:

| Measure | Good | Bad |
|---|---|---|
| Idle skirt movement | < 0.1 deg/frame | 0.5+, or never decaying |
| Leg inside cloth, idle/walk | < 25 mm | 100 mm |
| Leg inside cloth, run/slide/dash | ~95 mm *(current, unsolved)* | — |
| Solver cost | ~2.6 ms/character | 10 ms |
| Stride vs. travel direction | < 10° (except a capped sidestep) | 90° |
| Bind-pose AABB | tall on the hips→head axis, others < 2.5 m | tallest axis is depth |

## Characters currently shipping

The six in `skins.json`, with what `surface_class_check` reports:

| Skin | Source | Cloth chains | Surfaces |
|---|---|---|---|
| taila | rigged, Sketchfab CC-BY | 35 | 18 — body 6, cloth 7, hair 1, linework 4 |
| kiyoko | VRoid, CC-BY | 20 | 13 — body 8, cloth 3, hair 2 |
| aria | VRoid, CC-BY | 15 | 15 — body 9, cloth 4, hair 2 |
| momo | VRoid, CC-BY | 9 | 5 — body 2, cloth 1, hair 2 |
| miku | unrigged source, auto-rigged | 0 | 4 — body 3, hair 1 *(one mesh, four surfaces)* |
| mannequin | Quaternius CC0, from the animation library | 0 | 2 — body 2 |

## Known-unsolved

- **Peak cloth clipping** in a run, slide and dash sits at ~95 mm of thigh
  inside the skirt. Idle, walk and fall are clean. The solver sees the contact
  and pushes on it every iteration; the remaining gap is a standing fight
  between the collision and the garment's own shape constraints.
- **No foot IK.** Feet do not plant on ground height, so stairs and uneven
  ground read as sliding.
- **No strafe or backpedal clips.** Direction is conveyed by yawing the hips
  (`SkinnedPlayerModel._update_travel`), which is capped, so a pure sidestep
  still runs its legs ~40° off the direction of travel.
- **momo's idle pose is wrong** — arms overhead and a pinched waist. Every
  assertion passes on her: she loads, animates, classifies and mounts a weapon.
  It shows up only in `roster_capture`.

  **Diagnosed, not fixed.** Her `driven_bones` contains `Root_001` through
  `Root_007` — and those are her HAIR roots. The Godot surface dump shows
  `Hair_A` dominated by `Root_001_001:3203`, `Root_007:3203`, `Root_005:2642`.
  So the animation is keying bones that physics is supposed to own, which is
  non-negotiable #2 being violated by the role resolver rather than by a clip.
  The corroboration is in the surface table: her hair surfaces report only 1.8%
  and 9.4% chain share, because most of their vertices belong to `Root_00N`,
  which is in no chain at all.

  `Root_00N` matches no COSMETIC stem, so `is_cosmetic` does not catch it and
  nothing keeps it out of the driven set. Fixing it by adding "root" to the
  stems would be wrong — a rig whose actual root is called `Root` would lose its
  hips. The fix is structural: a bone whose geometry is dominated by a mesh
  classified `hair` is a hair bone, whatever it is called. The surface table
  now makes that answerable at build time, which it was not when this rig was
  imported. Not attempted here — it needs a Blender re-run and re-verification
  of all six characters.

  Her `head` role is also wrong (`Unused_Noname_010`, when a real `Head` bone
  exists and is in her spine chain), and her spine chain runs two junk bones
  PAST the head. Probably the same import; worth fixing in the same pass.
- **A stray `Icosphere` ships inside every skin GLB** — 42 vertices, no parent,
  no vertex groups. It rides in from the animation library. Harmless, and now
  skipped by construction rather than by name in `surface_map`, but the export
  should not be producing it.