security-game/docs/npc-model-sourcing.md

# NPC Model Sourcing

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).

## Active direction

**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.

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 |
| --- | --- | --- |
| `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 |

Source: [Quaternius Ultimate Modular Characters](https://quaternius.com/packs/ultimatemodularcharacters.html)
and [Ultimate Modular Women](https://quaternius.com/packs/ultimatemodularwomen.html),
CC0 1.0. Download date: 2026-11-03 (via the Ducz Character Creator browser export).
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.

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.

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.

## Closed tracks

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.

## Related documents

- [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)