animation/.agents/plans/rig-graft-lane-2026-08-04.md

Rig-graft lane — AccuRig skeleton onto pristine Tripo GLBs (PLAN, not executed)

Repo home: this plan and its tools moved from ariki-game into the animation repo 2026-08-06 — the lane authors characters, so characters/REGISTRY.md governs it (see .agents/wiki/ARCHITECTURE.md "Which repo does a non-gameplay tool belong to"). Paths below are animation-repo-relative unless prefixed ariki-game/.

Status 2026-08-04: PLAN ONLY. Jeremy has explicitly held execution — no model files are to be created or modified until the naming convention is decided.

Goal

Rig Ozlem's two unrigged Tripo bodies without the FBX→GLB quality loss the male lane hit in July (mangled textures, bad hand skinning). The move: FBX is only a disposable rig carrier through AccuRig; the GLB is the sole source of truth for mesh + materials and only ever gains bones and weights.

Source files (curated 2026-08-04)

Byte-identical copies live in both repos: characters/originals/ here (checksummed in characters/REGISTRY.md) and ariki-game/assets/models/characters/race-sources/. Read from this repo's copies.

file	verts	tris	height	feet @ Z0	axis	textures
female_lena_tripo.glb	974,478	1,907,931	0.979 m	yes (0.0)	upright, rot 0, scale 1	3 packed 4K (basecolor/normal/rm)
female_lena_tripo.fbx	953,968	1,907,931	0.979 m	—	upright	5 external JPEGs (.fbm removed; git-recoverable)
male_base_bald_tripo_v1.glb	969,881	1,901,449	0.980 m	yes (0.0)	upright, rot 0, scale 1	3 packed 4K, clean
male_base_bald_tripo_v1.fbx	950,729	1,901,449	0.980 m	—	lying down (bad axis)	6 packed, all mislabeled "Diffuse Texture.NNN", duplicated basecolor

Census facts that shape the plan:

• No bones anywhere — all four files are truly unrigged, so no rig standard is imposed by the sources. The 65-bone Quaternius game standard is unaffected.
• Identical surfaces per pair (tri counts match exactly); vertex counts differ ~2% from format-specific UV-seam splitting → index-exact weight copy is off the table, nearest-surface transfer is the mechanism (surfaces coincide, so it is near-exact everywhere except close-packed fingers — see step 4).
• The male FBX's axis + texture mangling is the July failure mode reproduced in data — never source visual data from FBX.

Decisions (Jeremy, 2026-08-04)

1. NO scaling to standard height. Bodies stay at Tripo's native ~0.98 m. (Any scale handling happens later, downstream, not in this lane.)
2. Axis check + ground the feet — wanted, and the probe shows both GLBs already pass (rot 0 / scale 1 / min-Z exactly 0.0). These become verify-only gates, mutating nothing unless a future source fails them.
3. HOLD before decimation until the naming convention for derived files is agreed. Nothing below the line runs until then.

The lane (each step gated on the one before)

1. Verify (read-only, DONE for the two current GLBs): upright axis, unit scale, feet at Z=0, centered X, packed textures present.
2. Rig bait (HELD — naming): from the GLB, decimate a disposable copy and export FBX for AccuRig. Confirmed 2026-08-04: AccuRig refuses the raw 1.9 M-tri FBX outright (Jeremy tried; July hit the same wall). Use the ariki-game/tools/male_mesh_decimate.py precedent: region budgets body 24k / head 14k / hands 10k as their own protected region (global-ratio decimation webs the fingers — half of the historic hand-mangling happened here, pre-AccuRig). Apply the July male-lane traps: Dummy-export quirk, the 4 cm offset. No scale change on the GLB — but if AccuRig misplaces joints on a 0.98 m body, scale the DISPOSABLE BAIT up 2× and scale the returned skeleton back down in the graft; the GLB never changes size.
3. AccuRig (manual, Jeremy/Ozlem): rig the bait FBX. Export rigged FBX.
4. Graft (headless Blender): import rigged bait FBX + pristine GLB; snap rest poses; transfer skeleton + skin weights decimated→full-res by nearest-surface with tight max-distance; hands get special handling (per-finger masked transfer or reduced distance + limit-totals + normalize) — this is where the old hand mangling gets fixed. Export GLB: original mesh + original packed textures + new rig. FBX artifacts are discarded.
5. QC: pose sweep incl. finger curls; then (if/when destined for game) the existing AccuRig→Quaternius conversion (ariki-game/tools/make_male_ib_quatskin_accurig.py lineage) picks it up.

Naming + step 2 status (RESOLVED 2026-08-04, later same day)

Jeremy raised the hands budget and released the bait step. Built with tools/rigbait_decimate.py (parameterized successor to male_mesh_decimate.py — no scale/recenter, bbox-relative region cuts, budgets body 24k / head 14k / hands 40k):

• characters/rig-work/lena_tripo_rigbait.fbx — 77,999 tris, QA'd
• characters/rig-work/mako_tripo_rigbait.fbx — 78,000 tris, QA'd
• characters/rig-work/ is exempt from the naming grammar (REGISTRY.md rule 11) — disposable carriers, no registry rows. In the game repo it had needed a .gdignore to stop Godot importing it, which was the tell that it lived in the wrong repo.
• QA renders alongside (*_qa_front.png, *_qa_hand.png) — fingers fully distinct at 40k, no webbing.
• Baits are geometry-only (~3.5 MB; the GLB's packed textures don't survive FBX embed) — AccuRig shows a grey model, which is fine for rigging. It does mean the July "Dummy001 export" check can't use textures: verify AccuRig's output by mesh name + ~78k tri count instead.

AccuRig exports must be saved as (same folder):

• characters/rig-work/lena_tripo_accurig.fbx
• characters/rig-work/mako_tripo_accurig.fbx

Open before execution

• Step 3 (AccuRig) — manual, waiting on Jeremy/Ozlem.
• Step 4 graft script — build once a rigged FBX exists to test against.
• Whether to restore the female FBX's .fbm texture folder from git (only needed if the FBX is ever used for more than rigging; the lane says it shouldn't be).