security-game/docs/adr/0017-quaternius-npc-base.md

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