Record NPC sourcing decision and crowd prototypes
This commit is contained in:
zwitschi committed
1 parent
bfe3c5a701
commit
fef3af44c0
10 files changed
+269
-90
No files matched your search
@@ -0,0 +1,72 @@
|
||||
# ADR-0015: NPC model variety sourcing
|
||||
|
||||
- **Status:** Accepted (post-0.10.0 planning)
|
||||
- **Date:** 2026-11-03
|
||||
|
||||
## Context
|
||||
|
||||
The library has eight skinned characters, and role/seed selection reuses them
|
||||
across the three venues. Crowds therefore repeat the same faces, builds and
|
||||
outfits. The existing contract is strict: `npc_base` mesh node, 13 named bones at
|
||||
fixed rest positions, five tint slots, front on Blender −Y and an 8,000
|
||||
triangle/vertex budget.
|
||||
|
||||
A review compared free/open-source sources against that contract. Quaternius
|
||||
Ultimate Modular (CC0), Kenney Blocky Characters (CC0), Khronos CesiumMan and
|
||||
RiggedFigure (CC BY 4.0) and the MakeHuman base mesh (CC0) were imported and
|
||||
measured. None was a drop-in; the full results are in
|
||||
[`docs/npc-model-sourcing.md`](../npc-model-sourcing.md).
|
||||
|
||||
## Decision
|
||||
|
||||
1. **Ship only CC0, or CC BY with recorded attribution.** No service asset whose
|
||||
terms restrict redistribution may be used.
|
||||
2. **Extend the project-owned procedural generator as the primary path** for
|
||||
shipped NPC variety. The first target is four crowd-variety looks, bringing
|
||||
the library to twelve characters.
|
||||
3. **Keep Quaternius as a reviewed reference/prototype, not a shipped base.** A
|
||||
contract retarget is a no-go because the source is a T-pose 62-bone realistic
|
||||
rig with substantially different proportions from the arm-down 13-bone
|
||||
contract. A future external-rig path would need its own ADR covering its
|
||||
skeleton, animation source and per-model gear offsets.
|
||||
4. **MakeHuman is deferred to a separate local development pipeline.** Its CC0
|
||||
base mesh can be decimated into budget, but it needs retopology, a custom rig
|
||||
and project-owned clothing before it is usable. It must not become a CI or
|
||||
build dependency.
|
||||
5. **Commit research previews with attribution.** CC-BY preview images are
|
||||
development-only and are not bundled with the game or its release packages.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- The shipped library keeps one art direction, one skeleton and one audit gate.
|
||||
- Crowd variety lands without a new runtime dependency or a second animation
|
||||
system.
|
||||
- The licence position is simple: project-owned assets plus explicit CC-BY
|
||||
attribution where a preview or future asset requires it.
|
||||
- The Quaternius evaluation removes a tempting but high-risk retarget from the
|
||||
critical path.
|
||||
|
||||
### Negative
|
||||
|
||||
- Procedural variation is still limited by the existing face and clothing
|
||||
vocabulary; four variants do not provide full age/body diversity.
|
||||
- Quaternius' animation set remains unused unless a second rig path is approved.
|
||||
- MakeHuman body-shape diversity is postponed.
|
||||
- External previews add a small documentation footprint that must stay out of
|
||||
release packages.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **Retarget Quaternius onto the `npc_base` contract.** Rejected for now:
|
||||
welding brings the geometry inside budget, but the rest pose and body
|
||||
proportions differ enough that a contract rebuild would either distort the
|
||||
model or require a full proportion warp.
|
||||
- **Use Quaternius' own rig and animations directly.** Deferred: attractive
|
||||
animation quality, but it adds a second skeleton/animation path and per-model
|
||||
gear offsets to `NpcAvatar`.
|
||||
- **Use MakeHuman as the primary body source.** Rejected for this milestone: high
|
||||
polygon count, no rig in the base mesh and a separate authoring dependency.
|
||||
- **Use Mixamo or Ready Player Me.** Rejected: service terms are not a simple
|
||||
free/open-source redistribution basis for shipped meshes.
|
||||
@@ -18,3 +18,4 @@ Each ADR records the context, decision, consequences and alternatives for a dura
|
||||
- [0012-surface-materials-and-generated-props](0012-surface-materials-and-generated-props.md)
|
||||
- [0013-blender-authored-npc-characters](0013-blender-authored-npc-characters.md)
|
||||
- [0014-runtime-image-root](0014-runtime-image-root.md)
|
||||
- [0015-npc-model-variety-sourcing](0015-npc-model-variety-sourcing.md)
|
||||
@@ -131,7 +131,8 @@ Contract and integration notes: [`blender-assets.md`](blender-assets.md).
|
||||
|
||||
Sourcing and expansion research (no external model is shipped yet):
|
||||
[`npc-model-sourcing.md`](npc-model-sourcing.md) compares Quaternius, Kenney, Khronos and
|
||||
MakeHuman sources against the character contract and records the pending 0.11.0 decision.
|
||||
MakeHuman sources against the character contract and records the 2026-11-03 direction
|
||||
(procedural generator first, Quaternius reference, MakeHuman deferred).
|
||||
|
||||
| Characters | Props |
|
||||
| --- | --- |
|
||||
|
||||
@@ -43,6 +43,8 @@ Committed contact sheets and local Blender renders for the character, gear and p
|
||||
| <img src="security_podium.png" width="280" alt="security_podium.png"> | [`security_podium.png`](security_podium.png) |
|
||||
| <img src="sedan.png" width="280" alt="sedan.png"> | [`sedan.png`](sedan.png) |
|
||||
| <img src="sheet_npc.jpg" width="280" alt="sheet_npc.jpg"> | [`sheet_npc.jpg`](sheet_npc.jpg) |
|
||||
| <img src="sheet_npc_sources_research.jpg" width="280" alt="sheet_npc_sources_research.jpg"> | [`sheet_npc_sources_research.jpg`](sheet_npc_sources_research.jpg) |
|
||||
| <img src="sheet_npc_crowd_prototypes.jpg" width="280" alt="sheet_npc_crowd_prototypes.jpg"> | [`sheet_npc_crowd_prototypes.jpg`](sheet_npc_crowd_prototypes.jpg) |
|
||||
| <img src="sheet_npc_baseline.jpg" width="280" alt="sheet_npc_baseline.jpg"> | [`sheet_npc_baseline.jpg`](sheet_npc_baseline.jpg) |
|
||||
| <img src="sheet_npc_baseline_compare-p1.jpg" width="280" alt="sheet_npc_baseline_compare-p1.jpg"> | [`sheet_npc_baseline_compare-p1.jpg`](sheet_npc_baseline_compare-p1.jpg) |
|
||||
| <img src="sheet_npc_baseline_compare-body.jpg" width="280" alt="sheet_npc_baseline_compare-body.jpg"> | [`sheet_npc_baseline_compare-body.jpg`](sheet_npc_baseline_compare-body.jpg) |
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 55 KiB |
+111
-59
@@ -1,8 +1,12 @@
|
||||
# NPC model sourcing and expansion plan
|
||||
|
||||
Status: **research complete, direction not chosen (2026-11-03).** No downloaded
|
||||
model is committed to the game or included in a release. The local evaluation
|
||||
files live under `tmp/npc-research/` (gitignored).
|
||||
Status: **direction chosen 2026-11-03.** The procedural generator is the primary
|
||||
path, the Quaternius CC0 pack is a reviewed reference/prototype, and MakeHuman is
|
||||
deferred to a separate local development pipeline. No downloaded source model is
|
||||
committed to the game or included in a release; the committed research preview
|
||||
sheets carry the required attribution. Local evaluation files live under
|
||||
`tmp/npc-research/` (gitignored). The decision is recorded in
|
||||
[ADR-0015](adr/0015-npc-model-variety-sourcing.md).
|
||||
|
||||
This page records the free/open-source character sources that were reviewed, how
|
||||
they behave when imported into the existing Blender tooling, and the options for
|
||||
@@ -123,21 +127,80 @@ This is the strongest answer to "everyone has the same body", but requires an
|
||||
offline authoring step, decimation/retopology and a custom rig/weight step. It
|
||||
should be treated as a later pipeline project, not a quick content drop.
|
||||
|
||||
## Recommended direction
|
||||
## Decision and prototype outcome
|
||||
|
||||
1. **Do not add raw external models.** Keep the current library and contract
|
||||
unchanged until a human has reviewed this page.
|
||||
2. **Prototype Option B once** (one Quaternius character) behind a new intake
|
||||
command. If the walk pose, face style and gear fit pass, use it for a small
|
||||
set of silhouette donors and keep the project's faces/hands where possible.
|
||||
3. **Fall back to Option A** for the remaining variants. Procedural variation
|
||||
(age, build, hair, outfit colour/layers, accessory mix) is cheaper and keeps
|
||||
the library coherent.
|
||||
4. **Defer Option C** until the release candidate is out and there is a concrete
|
||||
need for body-shape diversity that A/B cannot meet.
|
||||
The project owner reviewed this page on 2026-11-03. The decision is:
|
||||
|
||||
This is a proposal, not a decision. The review questions are at the end of the
|
||||
page.
|
||||
1. **CC0 is acceptable** for shipped character assets. CC-BY is acceptable only
|
||||
with attribution in `CREDITS.md`; service assets whose terms restrict
|
||||
redistribution remain excluded.
|
||||
2. **Extend the procedural generator** as the primary path, starting with
|
||||
crowd-variety looks.
|
||||
3. **Prototype Quaternius** as a secondary source. It is not approved for
|
||||
shipping yet; the contract-retarget result below is a no-go for the current
|
||||
skeleton.
|
||||
4. **Use crowd variety** as the first visual goal, not role-specific costumes.
|
||||
5. **Evaluate MakeHuman for a later, separate local development pipeline.** It
|
||||
is not part of the normal build, CI or release flow.
|
||||
6. **Commit the research previews with attribution.** The CC-BY entries are
|
||||
listed in `CREDITS.md` and remain development-only.
|
||||
|
||||
### Quaternius prototype
|
||||
|
||||
The prototype used `Casual_Hoodie.glb`:
|
||||
|
||||
- **Geometry budget is not the blocker.** Imported: 12,518 vertices / 6,206
|
||||
triangles. After welding seam splits: 3,199 vertices / 6,206 triangles. After
|
||||
a 0.75 decimate: 2,423 vertices / 4,654 triangles, comfortably inside the
|
||||
library budget.
|
||||
- **Animation quality is attractive.** The imported Idle and Walk clips read
|
||||
well at game distance, and the model brings 24 animations.
|
||||
- **The contract rest pose is the blocker.** The source is a T-pose 62-bone rig
|
||||
with realistic proportions: upper leg starts near 0.96 m, arm span is about
|
||||
1.68 m, and the shoulder joint sits near x = 0.153 m. The project contract is
|
||||
an arm-down 13-bone rig with a hip near 0.62 m, a shoulder near x = 0.27 m and
|
||||
a hand near z = 0.78 m. Rebuilding the contract armature around this mesh would
|
||||
either distort the body substantially or require a full proportion warp.
|
||||
- **Decision:** do not retarget Quaternius to the contract now. Keep it as a
|
||||
silhouette/style reference and, if a second rig path is ever wanted, prototype
|
||||
it as its own animation path (its own skeleton, AnimationPlayer clips and
|
||||
per-model gear offsets) rather than forcing it into `npc_base`. That is a
|
||||
separate architecture decision, not an asset conversion.
|
||||
|
||||
Preview: [`blender_previews/sheet_npc_sources_research.jpg`](blender_previews/sheet_npc_sources_research.jpg).
|
||||
|
||||
### Generator crowd prototype
|
||||
|
||||
Four proposed crowd specs were built with the existing generator in a temporary
|
||||
output directory. All four audit clean and stay inside the character budget:
|
||||
|
||||
| Prototype | Look | Tris / verts | Gear |
|
||||
| --- | --- | --- | --- |
|
||||
| `npc_crowd_a` | slim, bun, sunglasses | 4,644 / 4,356 | sunglasses |
|
||||
| `npc_crowd_b` | broad, bald, beard | 4,550 / 4,453 | shoulder bag |
|
||||
| `npc_crowd_c` | average, short hair, long coat | 5,118 / 5,086 | umbrella |
|
||||
| `npc_crowd_d` | slim, short hair, hood up | 5,258 / 4,907 | cup |
|
||||
|
||||
They vary build, head silhouette, hair/beard and outer layer while keeping the
|
||||
existing face language. They are **not in the shipped catalogue**; production
|
||||
integration belongs to milestone 0.11.4 after the 0.10.0 release candidate.
|
||||
|
||||
Preview: [`blender_previews/sheet_npc_crowd_prototypes.jpg`](blender_previews/sheet_npc_crowd_prototypes.jpg).
|
||||
|
||||
### MakeHuman local-pipeline evaluation
|
||||
|
||||
The CC0 base mesh is 19,158 vertices / 18,486 polygons (36,972 triangles after
|
||||
triangulation), with 21,334 UV coordinates but no normals, material groups or
|
||||
rig. Scaling it to 1.82 m and decimating to 0.35 produced 3,780 vertices / 6,468
|
||||
triangles, which fits the geometry budget but is a collapse-decimation result,
|
||||
not production topology.
|
||||
|
||||
MakeHuman is therefore **feasible only as a separate local body-shape pipeline**:
|
||||
generate a small set of bodies locally with MPFB/MakeHuman, export the CC0
|
||||
meshes, decimate or retopologise them, build the contract rig and add
|
||||
project-owned heads, hands, clothing and gear. It must not become a CI or build
|
||||
dependency, and only the final CC0-derived assets with recorded provenance may be
|
||||
committed. This is deferred; it is not part of the 0.11.0 crowd-variety work.
|
||||
|
||||
## Provisional NPC roster
|
||||
|
||||
@@ -147,37 +210,30 @@ across age, build and style, not costumes that telegraph the outcome.
|
||||
|
||||
| Look family | Current | Proposed additions | Variation axes |
|
||||
| --- | --- | --- | --- |
|
||||
| Everyday | `npc_casual`, `npc_jacket`, `npc_coat`, `npc_hoodie`, `npc_dress` | older casual, denim jacket, short coat, open hoodie, second dress | age, build, height, hair, facial hair, outfit colour |
|
||||
| Workwear | `npc_vest`, `npc_guard` | second hi-vis build, venue-security build, cleaner/vendor apron | build, height, headwear, badge/radio gear |
|
||||
| Responder | `npc_firefighter` | paramedic/medical responder (only if the design supports it) | turnout vs medical kit, build, helmet |
|
||||
| Crowd/LOD | none | Kenney blocky or a decimated library variant for distant crowds | silhouette and palette only |
|
||||
| Everyday | `npc_casual`, `npc_jacket`, `npc_coat`, `npc_hoodie`, `npc_dress` | `npc_crowd_a` (bun/slim), `npc_crowd_b` (bald/broad), `npc_crowd_c` (coat/umbrella), `npc_crowd_d` (hood/cup) | build, height, hair, facial hair, outer layer, accessory |
|
||||
| Workwear | `npc_vest`, `npc_guard` | later: second hi-vis build, venue-security build | build, height, headwear, badge/radio gear |
|
||||
| Responder | `npc_firefighter` | later: paramedic/medical responder only if the design supports it | turnout vs medical kit, build, helmet |
|
||||
| Crowd/LOD | none | optional Kenney blocky or a decimated library variant for distant crowds | silhouette and palette only |
|
||||
|
||||
A first target is **12 library characters** (the current eight plus four new
|
||||
looks), not twenty. That is enough to break the clone effect without doubling
|
||||
the portrait QA matrix. The existing `character_model_for()` mapping becomes a
|
||||
pool per role family with a deterministic seed choice; the current two-way
|
||||
alternation for guests, trespassers and threats is the template.
|
||||
A first target is **12 library characters** (the current eight plus the four
|
||||
crowd prototypes), not twenty. That is enough to break the clone effect without
|
||||
doubling the portrait QA matrix. `character_model_for()` becomes a pool per role
|
||||
family with a deterministic seed choice; the current two-way alternation for
|
||||
guests, trespassers and threats is the template.
|
||||
|
||||
## Implementation plan
|
||||
|
||||
The actionable tasks live in `TODO.md` under milestone 0.11.0. The workstreams
|
||||
are:
|
||||
|
||||
1. **Decision and licence gate.** Review this page, choose A/B/C, record the
|
||||
decision in an ADR, and add a source allow-list (CC0 preferred; CC-BY only
|
||||
with attribution in `CREDITS.md`; no service assets whose terms restrict
|
||||
redistribution).
|
||||
2. **Intake/validator.** Add an `inspect` report and an `adapt` path. The
|
||||
validator should check bones, rest positions, node name, slots, budgets,
|
||||
ground/height, UVs and skinning before and after adaptation. Keep the
|
||||
existing `audit` as the final gate rather than creating a second contract.
|
||||
3. **One-character prototype.** Adapt a single Quaternius CC0 variant; capture
|
||||
front/three-quarter/profile/full-body/crowd views and a walk cycle; compare
|
||||
against `npc_casual` and `sheet_npc_baseline.jpg`. Stop if the retarget does
|
||||
not pass.
|
||||
4. **Roster build.** Add four approved variants, update the manifest, and extend
|
||||
the runtime selection pools. Rebuild gear fit and check each new variant with
|
||||
the existing acceptance criteria.
|
||||
1. **Decision and licence gate.** Complete: ADR-0015, the CC0/CC-BY rule and the
|
||||
committed preview sheets.
|
||||
2. **Generator crowd variants.** Complete as a prototype (four specs, clean
|
||||
audit, review sheet). Production integration is pending the 0.10.0 release.
|
||||
3. **Quaternius intake.** The contract-retarget prototype is a no-go. Keep the
|
||||
source as a reference; a second-rig/animation path would need its own ADR.
|
||||
4. **Roster build and runtime.** Add the four approved specs to `CHARACTERS`,
|
||||
build and commit their GLBs, update the manifest, and extend the role pools.
|
||||
5. **QA and integration.** Run the 24-NPC budget, portrait baseline, gear fit,
|
||||
headless suite and release build. Record provenance and any accepted limits.
|
||||
Only then update `CHANGELOG.md` and `docs/development-status.md`.
|
||||
@@ -196,33 +252,29 @@ are:
|
||||
- Map materials by semantic role, not by source name. A source "Purple" or
|
||||
"Worker_Vest" needs an explicit mapping to `cloth`, `pants`, `skin`, `hair` or
|
||||
`accessory`; do not rely on colour heuristics.
|
||||
- Rebuild the armature at the contract rest positions and transfer weights, or
|
||||
prove that a renamed external rig produces the same rest and pose behaviour.
|
||||
Do not add a second skeleton format to `NpcAvatar`.
|
||||
- Keep the face direction unambiguous. The front is Blender −Y; verify it with
|
||||
a capture, not by guessing from the source file.
|
||||
- For any future external-rig path, do not silently add a second skeleton format
|
||||
to `NpcAvatar`. Record the per-model skeleton, animation source and gear
|
||||
offsets as an explicit contract.
|
||||
|
||||
## Review questions
|
||||
## Review outcome
|
||||
|
||||
The project owner should answer these before the 0.11.0 work starts:
|
||||
The project owner answered the review questions on 2026-11-03:
|
||||
|
||||
1. Are third-party CC0 characters acceptable in shipped game assets, or should
|
||||
the library stay entirely project-owned?
|
||||
2. If yes, is the Quaternius CC0 pack acceptable as a silhouette/outfit donor
|
||||
with a rebuilt project-style head and hands?
|
||||
3. Which four role families would benefit most from a new look: everyday
|
||||
guests, workwear, responders, or crowd variety?
|
||||
4. Is the MakeHuman/MPFB body-shape pipeline worth a later investment, or is
|
||||
procedural variation enough?
|
||||
5. Should the preview sheet be committed as a review artefact (with attribution
|
||||
for the CC-BY entries), or stay local under `tmp/`?
|
||||
|
||||
Until those answers exist, the safe default is **Option A: extend the owned
|
||||
procedural generator and keep external models as references only.**
|
||||
| Question | Answer |
|
||||
| --- | --- |
|
||||
| Are third-party CC0 characters acceptable? | Yes. |
|
||||
| Which direction? | Prototype Quaternius and extend the procedural generator. |
|
||||
| Which looks first? | Crowd variety. |
|
||||
| Should MakeHuman be pursued? | Evaluate it for a later, separate local development pipeline. |
|
||||
| Commit the previews? | Yes, with CC-BY attribution. |
|
||||
|
||||
## Downloaded example provenance
|
||||
|
||||
Files were downloaded on 2026-11-03 and kept out of version control:
|
||||
Source models were downloaded on 2026-11-03 and kept out of version control. The two
|
||||
research preview sheets are committed under `docs/blender_previews/`; the CC-BY
|
||||
attribution is recorded in `CREDITS.md`.
|
||||
|
||||
| File | Source | SHA-256 |
|
||||
| --- | --- | --- |
|
||||
|
||||
Reference in new issue
Block a user