Rewrite NPC plans around the Quaternius base

docs/npc-model-sourcing.md

@@ -1,93 +1,114 @@
 # NPC Model Sourcing
 
-This page records the source evaluation behind [ADR-0015](adr/0015-npc-model-variety-sourcing.md).
-The shipped path is the project-owned Blender/procedural library; external sources
-remain references or local prototypes unless a later ADR accepts them.
+This page records the source evaluation and the active character plan. The
+decision is [ADR-0017](adr/0017-quaternius-npc-base.md), which supersedes the
+generator-first sourcing decision in [ADR-0015](adr/0015-npc-model-variety-sourcing.md).
 
-## Evaluation
+## Active direction
 
-The library needs variety beyond the original eight silhouettes while preserving
-the `npc_base` contract: mesh node, 13 required core bones (optional extras
-allowed), five tint slots, −Y/+Z front, grounded feet and the 24,000/24,000
-character budget.
+**Quaternius Ultimate Modular Characters (CC0) is the primary NPC mesh and
+animation source.** The project-owned procedural library remains the shipped
+fallback until the Quaternius migration passes the silhouette and gear gates.
 
-| Source | Licence | Result |
+The migration keeps the runtime contract that Godot, gear and tests already
+consume:
+
+- one `npc_base` skinned mesh under the 13 required core bones (optional extras
+  allowed);
+- five tint slots: `skin`, `cloth`, `pants`, `accessory`, `hair`;
+- front on Blender −Y / Godot +Z, feet grounded, height about 1.81 m;
+- 24,000 triangles / 24,000 glTF vertices per character;
+- gear stays at 1,500 triangles and props at 4,000;
+- committed GLBs and maps only; no Quaternius, Blender or network dependency in
+  CI, build or runtime.
+
+### Stage 1 (default)
+
+1. Import the researched Quaternius GLBs and choose a canonical base.
+2. Map the 62 source joints to the 13-core contract and bake a proportion warp.
+3. Skin the mesh, retarget Idle and Walk, and verify seated/arm-down poses.
+4. Map the five slots, unwrap and bake 256² maps.
+5. Fit the existing gear and render the silhouette gate.
+6. Build the 12 variants, audit, and capture the 12 × 6 baseline.
+
+The Quaternius 62-joint rig and its 24 animation clips are an **authoring
+source**. They are not loaded at runtime.
+
+### Stage 2 gate
+
+The 62-joint T-pose source does not share the project's arm-down rest pose or
+proportions. If the Stage 1 proportion warp cannot preserve the Quaternius
+silhouette and deformation, stop the rollout and write a new ADR for adopting
+the 62-joint rig at runtime. Do not ship a hybrid rig, a second gear offset
+system or a silent `NpcAvatar` change.
+
+## Research findings
+
+The researched files are the three converted Quaternius outfits used by the
+Ducz Character Creator: `Casual`, `Casual_Hoodie` and `Worker`. They are kept
+locally in `tmp/npc-research/quaternius/` with the licence and mirror notes.
+
+| File | SHA-256 | Structure |
 | --- | --- | --- |
-| Quaternius Ultimate Modular | CC0 | Good silhouette/decimation material, but a 62-bone T-pose realistic rig and different proportions; not a drop-in. Kept as a reference/prototype. |
-| Kenney Blocky Characters | CC0 | No matching rig; style is much blockier than the project look. |
-| Khronos CesiumMan / RiggedFigure | CC BY 4.0 | Different bone names/rest pose and no five-slot materials; not a drop-in. |
-| MakeHuman / MPFB base | CC0 | Useful body-shape base, but requires retopology, a custom rig, clothing and part integration. Active local pipeline, not the shipped path. |
+| `Casual.glb` | `bc2d84fba249ebaa0629cb9d133ad37234196e4b8004aa205a6397abed04e05c` | 4 meshes, 62 joints, 24 clips, 7 materials |
+| `Casual_Hoodie.glb` | `f5b722199f7628b24550989af4230f65d5230727df9c326fd2b3e360effe5249` | 4 meshes, 62 joints, 24 clips, 7 materials |
+| `Worker.glb` | `8d0f454336c2effc5c08f63a177af3a82d1a7af025ca9588b40e4c90c4703534` | 4 meshes, 62 joints, 24 clips, 11 materials |
 
-The contract mismatch is the expensive part, not decimation: retargeting a
-different rig or rebuilding slots/weights can distort the body and invalidate
-gear placement. Any future second-rig path needs its own ADR and animation/gear
-offsets.
+Source: [Quaternius Ultimate Modular Characters](https://quaternius.com/packs/ultimatemodularcharacters.html)
+and [Ultimate Modular Women](https://quaternius.com/packs/ultimatemodularwomen.html),
+CC0 1.0. The Ducz mirror is a browser builder over the same packs; it adds 21
+outfits and a shared skeleton. The three full GLBs are the initial scope; the
+21-part builder is a fallback for role coverage, not the default.
 
-## Decision and outcome
+The first prototype measured 12,518 imported vertices, 3,199 after welding and
+2,423 vertices / 4,654 triangles after a 0.75 decimate. Idle and Walk read well.
+The source is a T-pose with a 62-joint realistic rig, roughly 0.96 m hip,
+1.68 m arm span and 0.153 m shoulder offset, so a contract bake is required.
 
-- Extend the project-owned procedural generator as the primary shipped path
-  (12-character library, crowd variants, role pools).
-- Keep Quaternius as a studied reference, not a shipped base.
-- MakeHuman is a local development pipeline for body-shape diversity; it must
-  consume the same head/hand parts as the procedural library and never become a
-  CI/build dependency.
-- Record CC0/CC-BY provenance; CC-BY previews require attribution in
+The 24,000 cap leaves room to stay much closer to the source LOD than the
+prototype's 4,654 triangles. Do not decimate to the old 7,000-triangle target
+before the silhouette gate.
+
+## Contract mismatch
+
+The expensive part is the rig and proportions, not the mesh. The source has a
+T-pose and a realistic skeleton; the runtime expects an arm-down 13-core rig,
+fixed gear attach points and the existing pose composition. The Stage 1 bake
+must therefore:
+
+- rotate the arms down and match the contract wrist positions;
+- warp the hips, knees, shoulders and head without collapsing the deltoid,
+  shortening the arms or changing the silhouette;
+- keep one skinned `npc_base` mesh and the five slots;
+- verify gear against the new shoulder, hip and head positions.
+
+If those constraints distort the model, Stage 2 is the correct next decision,
+not a local workaround.
+
+## Licence and provenance
+
+- CC0 preferred. CC-BY is allowed only with attribution in
   [`CREDITS.md`](../CREDITS.md).
+- No service asset whose terms restrict redistribution may be shipped.
+- Keep the source URL, author, licence, download date and SHA-256 in this page
+  and in `CREDITS.md`.
+- Research files and generated previews stay in `tmp/` (gitignored). Only final
+  audited assets and committed review sheets enter the repository.
+- Quaternius models and animations are CC0; the existing credits entry already
+  names Quaternius. Keep it accurate if the shipped source set changes.
 
-## MakeHuman prototype notes
+## Closed tracks
 
-The local prototype (`tmp/npc-research/`, never committed) scaled the base to
-1.82 m, grounded it, triangulated/decimated it and retargeted it to the 13-core
-armature. The first retarget measured **6,444 / 16,000 tris and**
-**7,726 / 16,000 verts**, 14 bones, skinned, arm-down, five slots. It exposed
-the expected issues: a 1.63× arm-scale warp at the deltoid/shoulder, blocky
-decimated hands, rough slot boundaries and a head/neck shadow gap. The later
-project head/hands swap reduced this to **6,407 / 16,000 tris and**
-**6,651 / 16,000 verts**, but manual shoulder/neck retopology and part cleanup
-remain before it can be considered shippable.
+The MakeHuman/MPFB body pipeline is closed for the NPC base. The accepted
+MakeHuman head and the procedural `npc_base` remain tested fallbacks until the
+Quaternius rollout is complete. Their research scripts and renders were removed
+from `tmp/` after the pivot; the measurements and decisions remain in
+[`DONE.md`](../DONE.md), [`MEMORY.md`](../MEMORY.md) and the review docs.
 
-A standalone MakeHuman head is recorded in
-[`makehuman-head-review.md`](makehuman-head-review.md). The owner accepted the basic
-human head on 2026-11-04; the assembled path (`build_character(head="mh")`) adds a
-skull-conforming hair cap and hides the scalp under it. The 12 shipped GLBs still use
-the procedural head until the hair/body review and rollout in [`TODO.md`](../TODO.md).
-The MakeHuman body should reuse the approved local head/hand parts rather than forking
-a second face implementation.
+## Related documents
 
-The current local MPFB full-body prototype (`tmp/npc-research/build_mpfb_npc.py`) assembles the
-accepted head on an MPFB 2.0.18 body at **19,747 / 24,000 tris**, 1.810 m, 14 bones and 10
-materials, with project hands, bevelled shoe shells with inset soles and tongues, pant cuffs,
-cloth sleeve cuffs and flat slot colours. The torso is radially inflated by 12% through z 0.72–1.40
-to loosen the shirt. It is a review candidate, not a shipped asset. The neck is a boolean-cut
-circular bore bridged by a smooth lathe; the accepted head is trimmed at the narrow neck (z 1.55)
-so its wide flat cut brim is discarded, and the lathe flares to cover the bore, then tucks inside
-the jaw. This removed the square collar, dark notches and wide brim; a thin jaw crease and a hard
-shirt-shoulder point in three-quarter view remain. The ankles are hidden by 0.11 m shoe shells and
-0.08 m pant cuffs, and a light smoothing pass softens the closed thigh/hip region. The neck skin
-test is guarded to z > 1.35 so it cannot paint the crotch. Remaining polish: the crotch hollow still reads as a V under
-the shirt hem, a partly loosened shirt and angular thigh facets; a separate loose shirt shell is
-the fix. Lowering the hem to z 0.80, tilting it up at the front and a 13% hem flare were rejected
-as a unitard, high-cut swimwear and a peplum respectively. A quick open, flared solidified tube
-(0.150→0.196 m, z 1.05→0.80, 24 segments) read as a hanging apron/tabard; the shell needs a shaped
-torso, armholes and a curved hem.
-A torus collar, cloth cylinder collar, skin neck-blend sphere, destructive vertex-smoothing pass
-and untucked shirt-hem band were tried and removed because they read as a brace, shelf, donut or
-hanging flap, or tore a hole at the collar. Protruding flat sole plates read as skates or bricks,
-so the shoe detail is an inset sole and tongue under a rounded shell; laces were dropped for
-triangle budget. The production integration decision (bake a committed source GLB or keep the
-procedural body) and the owner review are tracked in `TODO.md`; MPFB itself must not become a
-CI/build dependency.
-
-## Provenance rules
-
-- CC0 preferred; CC-BY only with attribution in `CREDITS.md`; no service asset
-  whose terms restrict redistribution.
-- Downloaded research and generated previews stay in `tmp/`/gitignored folders;
-  only final audited assets and committed review sheets enter the repository.
-- Record source URL, licence, author, date and what decision the reference
-  informed. Never treat a generated concept as licensed map/model data.
-
-Measurements, visual decisions and accepted limits are in
-[`3d-model-review.md`](3d-model-review.md) and
-[`npc-visual-review.md`](npc-visual-review.md). Commands are in
-[`asset-tooling.md`](asset-tooling.md).
+- [ADR-0017: Quaternius NPC base](adr/0017-quaternius-npc-base.md)
+- [ADR-0016: 24,000-triangle character budget](adr/0016-npc-character-budget-24k.md)
+- [Blender asset contract](architecture.md#character-and-gear-asset-contract)
+- [`3d-model-review.md`](3d-model-review.md), [`npc-visual-review.md`](npc-visual-review.md)
+- [`asset-tooling.md`](asset-tooling.md)