zwitschi/security-game
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Record NPC sourcing decision and crowd prototypes

Browse Source
This commit is contained in:
zwitschi committed 2026-11-03 07:59:58 +01:00
1 parent bfe3c5a701
commit fef3af44c0
10 files changed
+269 -90
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/npc-model-sourcing.md
+111 -59
View File
@@ -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 |
| --- | --- | --- |