# ADR-0017: Quaternius NPC base

- **Status:** Accepted
- **Date:** 2026-11-05
- **Supersedes:** ADR-0015 (generator-first character sourcing)

## Context

The current NPC library is built by the project-owned procedural generator. It
keeps the contract and ships, but the body, neck, hands and shoes need a
bespoke part pipeline to read as human. The MakeHuman head and MPFB body
prototypes improved detail but added a second authoring path, a 19,747-triangle
prototype and unresolved neck/shoulder seams.

The CC0 **Quaternius Ultimate Modular Characters** pack already provides a
coherent low-poly human silhouette, 21 modular outfits and 24 animation clips.
The researched GLBs (`Casual`, `Casual_Hoodie`, `Worker`) measure 4 meshes, 62
joints and 24 clips each. The owner directed that Quaternius become the NPC
base. The full evaluation is in [`docs/assets/npc-model-sourcing.md`](../assets/npc-model-sourcing.md).

## Decision

1. **Quaternius is the primary NPC mesh and animation source.** Keep the
   licence and SHA-256 provenance for the three researched GLBs.
2. **Stage 1 keeps the runtime contract.** Bake a canonical Quaternius base onto
   the existing 13-core contract, five tint slots, 24,000/24,000 budget,
   grounded −Y front and one `npc_base` skinned mesh. Retarget Idle and Walk;
   discard the combat/gun/sword clips. `NpcAvatar`, gear attach points and the
   pose composition remain the runtime interface.
3. **The 62-joint rig is an authoring source, not a runtime dependency.** It is
   not shipped and Quaternius is not loaded by CI, build or runtime.
4. **Stage 2 needs its own ADR.** If the proportion warp fails the silhouette,
   deformation or gear gate, stop and decide whether to adopt the 62-joint rig
   at runtime. Do not ship a hybrid rig or a second gear offset system.
5. **Close the MakeHuman/MPFB body work.** The accepted MakeHuman head and the
   procedural `npc_base` stay as tested fallbacks until the Quaternius rollout
   ships. No new MPFB development.
6. **Commit baked assets only.** The release consumes committed GLBs, maps and
   the manifest; Quaternius and Blender remain development tools.

## Consequences

### Positive

- A human base, modular outfits and a coherent animation set are already
  authored and CC0.
- The bespoke neck, hand and shoe pipelines are no longer on the critical path.
- The runtime contract and gear stay stable during the mesh migration.

### Negative

- A 62-joint T-pose does not share the arm-down 13-core rest pose or
  proportions; the proportion warp is the main risk.
- Quaternius' animation quality is only available after retargeting, unless
  Stage 2 is accepted.
- The migration touches all 12 variants, their AO maps, manifest entries and
  baseline captures at once.

## Alternatives

- **Keep the procedural generator as the primary path.** Rejected by the owner:
  the human silhouette remains the weak point and the bespoke part pipeline is
  larger than the Quaternius bake.
- **Adopt the 62-joint rig immediately.** Deferred to Stage 2 because it changes
  `NpcAvatar`, pose composition and gear offsets at the same time as the mesh.
- **Continue the MPFB body.** Rejected: it needs a separate head/neck/hand
  pipeline and still has unresolved surface seams.
- **Use a service character generator (Mixamo, Ready Player Me).** Rejected:
  redistribution and runtime terms are not a CC0 basis.