security-game/docs/adr/0018-quaternius-stage2-runtime-rig.md

ADR-0018: Quaternius Stage 2 — adopt source proportions at runtime

• Status: Accepted (2026-11-05, owner chose option 2)
• Date: 2026-11-05
• Supersedes: ADR-0017 decision 2 (Stage 1 keeps the 13-core contract)

Context

ADR-0017 made Quaternius the NPC base and staged the migration: Stage 1 bakes a proportion-warped mesh onto the existing 13-core contract; Stage 2 adopts the 62-joint rig at runtime only if the warp fails.

The Stage 1 proportion warp was executed and measured (docs/assets/npc-model-sourcing.md §Rest-pose and proportion-warp measurement). The arm-down rest pose bakes cleanly, but the warp to the contract proportions does not:

Joint	Quaternius	Contract	Delta
Hips height	0.869	0.62	−0.249
Shoulder x	0.148	0.27	+0.122
Arm (shoulder→hand tip)	0.429	0.70	×1.63
Leg (hip→ankle)	0.835	0.62	×0.74
Torso (hip→head)	0.745	1.20	×1.61

The vision judge reads the warped mesh as distorted: paddle/claw hands, forearms lost into the torso, stretched shins, "long legs + short torso". The arm either stays short (a shortened arm against the contract hand) or stretches 1.63× (a distorted deltoid + hand). Both are the gate's rejection conditions.

Decision

Stop the Stage 1 rollout and adopt the Quaternius 62-joint rig at runtime (owner chose option 2). The mesh is not proportion-warped: it keeps its source LOD (3,199 welded verts / 6,206 tris) and only the arm-down rest pose is baked.

• NpcAvatar maps the Quaternius joint names instead of the 13-core names.
• Gear attach points are re-derived from the Quaternius skeleton (hip ≈0.87, shoulder ≈0.148/1.39, wrist ≈0.99, knee ≈0.52).
• The 24 upstream clips ship as authoring reference only and are not played at runtime. NpcAvatar._animate() drives the proxy pivots and _sync_skeleton() writes the bone poses, which is what the FSM already needed for sitting, raising a hand and turning the head. Playing the clips would replace that state machine rather than supplement it; revisiting this needs its own ADR.

Option 1 (keep the 13-core names with Quaternius rest positions) is rejected in favour of the full source rig.

Consequences

Positive

• The Quaternius silhouette, deltoid, hand and leg proportions are preserved — no paddle hands, no shortened arm, no torso/leg distortion.
• The mesh stays at source LOD (far under the 24,000 cap), so no decimation is needed.

Negative

• The runtime contract numbers (hip 0.62, shoulder 0.27, hand 0.78) change; every gear attach point, npc_proportions guide, fit measurement and pose-composition constant must be re-derived and re-tested.
• NpcAvatar's bone mapping and pose composition are rewritten for the 62-joint rig, a larger change than the mesh swap.
• The 12-variant rollout and the 12×6 baseline are still blocked until the new rest positions and gear fit are owner-approved.

Alternatives

• Ship the warped mesh. Rejected by the gate: the 1.63× arm / 0.74× leg warp visibly distorts and the owner directed keeping the Quaternius as close to source as possible.
• Keep the old contract and accept a short arm. Rejected for the same reason: the hand ends at ≈0.99 instead of 0.78, so handheld gear floats unless attach points move — which is option 1.
• Abandon Quaternius and keep the procedural generator. Rejected in ADR-0017.

Open question

Resolved: option 2 (62-joint runtime) is the owner's choice. The first implementation step is the NpcAvatar bone-map + gear-attach re-derivation, then the slot/AO bake and the 12-variant rollout.

Follow-up decision: full roster swap

• Date: 2026-11-05 (owner, at the 0.9.9 face/silhouette gate)

The owner chose option (a) full swap from the face/silhouette gate (its sheets were retired with the review pages): every roster character moves onto the Quaternius base, and the procedural generator plus the MakeHuman head retire to the tested fallback rather than staying in the shipped roster.

Scope consequences:

• The shipped roster keeps its twelve public character names and CHARACTER_POOLS mapping; the geometry behind them comes from the three CC0 full-body sources already researched (Casual, Casual_Hoodie, Worker), aliased per role.
• Variety now comes from the five tint slots, the gear library and the per-role outfit rules instead of twelve distinct meshes. Roster silhouettes are therefore less varied than the procedural library until the modular part library (hair, outfits) is added — tracked as a 0.9.10 task, not hidden.
• The procedural library, _build_body() and the MakeHuman head stay in the tree and tested as the instant fallback; no MPFB or Stage-1 proportion-warp work reopens.