From f5fa321a8fe9d1e5491fe22199c67ef605f723e2 Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Thu, 5 Nov 2026 21:38:26 +0100 Subject: [PATCH] Draft ADR-0018 (Stage 2 runtime rig) and mark the remaining contract-bake items blocked --- TODO.md | 5 ++ .../adr/0018-quaternius-stage2-runtime-rig.md | 80 +++++++++++++++++++ docs/adr/README.md | 1 + docs/npc-model-sourcing.md | 4 + 4 files changed, 90 insertions(+) create mode 100644 docs/adr/0018-quaternius-stage2-runtime-rig.md diff --git a/TODO.md b/TODO.md index b710b10..b44d0a7 100644 --- a/TODO.md +++ b/TODO.md @@ -82,10 +82,15 @@ baseline sheet. ADR) indicated; do not rebuild on the warped base.** - [ ] Skin the Quaternius mesh and verify Idle, Walk, seated and arm-down poses. The old MPFB/arm-retarget warps are not a reference; judge the Quaternius result directly. + **Blocked** on the ADR-0018 decision (option 1 vs 2 rest positions / rig); the arm-down + rest pose is already baked and verified, but Idle/Walk/seated verification needs the + chosen rest positions first. - [ ] Retarget Idle and Walk from the 24 Quaternius clips to the contract rig; discard combat, gun and sword clips. Verify looping, foot contact and frame rate in Godot. + **Blocked** on ADR-0018 (retarget target changes with option 1 vs 2). - [ ] Map the five slots, unwrap per slot, bake 256² AO/albedo/normal/ORM maps and check texel density before any roster build. + **Blocked** on ADR-0018 (the mesh is not finalised until the rest positions/rig are chosen). ### 3. Silhouette gate diff --git a/docs/adr/0018-quaternius-stage2-runtime-rig.md b/docs/adr/0018-quaternius-stage2-runtime-rig.md new file mode 100644 index 0000000..81ee9da --- /dev/null +++ b/docs/adr/0018-quaternius-stage2-runtime-rig.md @@ -0,0 +1,80 @@ +# ADR-0018: Quaternius Stage 2 — adopt source proportions at runtime + +- **Status:** Proposed +- **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/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. Adopt the **Quaternius source proportions** as the runtime character +scale, rather than warping them to the old contract numbers. Two sub-options are open and must +be chosen by the owner: + +1. **Keep the 13-core bone names, change their rest positions to the Quaternius joints.** + The contract armature keeps 14 bones, but the rest positions and gear attach points are + re-derived from the Quaternius skeleton (hip ≈0.87, shoulder ≈0.148/1.39, wrist ≈0.99, + knee ≈0.52). `NpcAvatar`'s bone count and pose composition stay; gear offsets and the + contract tests are re-baked. This is the smallest runtime change that keeps the Quaternius + silhouette. +2. **Adopt the 62-joint rig at runtime.** Ship the Quaternius skeleton (including the optional + 30 finger + 2 foot bones) and retarget Idle/Walk onto it. `NpcAvatar` bone mapping, gear + attach points and the pose composition change together. Largest change, closest to the + source. + +Whichever is chosen, 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. + +## 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. +- Option 2 additionally rewrites `NpcAvatar`'s bone mapping and animation retarget, which is a + larger, riskier 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 + +Choose option 1 (13-core names, Quaternius rest positions) or option 2 (62-joint runtime). +Recommendation: **option 1** first — it preserves the silhouette, keeps `NpcAvatar`'s bone count +and pose composition, and only re-derives gear offsets and contract tests. diff --git a/docs/adr/README.md b/docs/adr/README.md index 58a16c4..4107d8f 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -21,3 +21,4 @@ Each ADR records the context, decision, consequences and alternatives for a dura - [0015-npc-model-variety-sourcing](0015-npc-model-variety-sourcing.md) - [0016-npc-character-budget-24k](0016-npc-character-budget-24k.md) - [0017-quaternius-npc-base](0017-quaternius-npc-base.md) +- [0018-quaternius-stage2-runtime-rig](0018-quaternius-stage2-runtime-rig.md) diff --git a/docs/npc-model-sourcing.md b/docs/npc-model-sourcing.md index 65ed5ae..348e64a 100644 --- a/docs/npc-model-sourcing.md +++ b/docs/npc-model-sourcing.md @@ -198,6 +198,10 @@ deltoid + hand) — both are the gate's rejection conditions. contract proportions; the gate fails and Stage 2 (a 62-joint runtime ADR) is indicated. Do not start the 12-variant rebuild on the warped base. +[ADR-0018](adr/0018-quaternius-stage2-runtime-rig.md) records the Stage 2 decision: adopt the +Quaternius source proportions at runtime (option 1: keep the 13-core names with Quaternius rest +positions; option 2: ship the 62-joint rig), pending the owner's choice. + ## Contract mismatch The expensive part is the rig and proportions, not the mesh. The source has a