diff --git a/CREDITS.md b/CREDITS.md index dcd53f6..1916f2a 100644 --- a/CREDITS.md +++ b/CREDITS.md @@ -21,6 +21,25 @@ using Blender. The `.blend` working sources are developer artifacts and are not shipped. The exported `.glb` files and baked AO maps are project assets; they do not embed third-party models or purchased asset packs. +### Development-only research previews + +Two review sheets under `docs/blender_previews/` compare source candidates for +the post-0.10.0 NPC variety work. They are development documentation and are not +bundled with the game or its release packages. The underlying source models are +kept outside version control. + +- [`sheet_npc_sources_research.jpg`](docs/blender_previews/sheet_npc_sources_research.jpg) + includes renders of **Quaternius Ultimate Modular Characters** (CC0 1.0, + ), **Kenney Blocky Characters 2.0** (CC0 1.0, + ), and **CesiumMan** and + **RiggedFigure** (CC BY 4.0, © 2017 Cesium, + ). +- [`sheet_npc_crowd_prototypes.jpg`](docs/blender_previews/sheet_npc_crowd_prototypes.jpg) + contains renders of project-owned generator prototypes. + +The CC-BY preview images are included only as development evidence. Any future +shipped derivative of CesiumMan or RiggedFigure must keep the attribution above. + The venue geometry is authored procedurally in `src/game/world_builder.gd` as a stylized reconstruction. The Joke Shop is a fictional stand-in for the real Sunset Strip block; the game does not claim endorsement by, or an exact replica diff --git a/MEMORY.md b/MEMORY.md index fdf8e47..ff5b0ac 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -4,16 +4,22 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o ## Decisions -- **NPC model sourcing research (2026-11-03):** `docs/npc-model-sourcing.md` evaluates - Quaternius Ultimate Modular (CC0), Kenney Blocky Characters (CC0), Khronos - CesiumMan/RiggedFigure (CC-BY 4.0) and the MakeHuman base mesh (CC0). No download is a - drop-in: every source lacks the `npc_base` node, the 13 contract bones and the five tint - slots; Quaternius additionally exceeds the vertex budget (10.5k–13k imported) and uses a - 62-bone T-pose rig, CesiumMan/RiggedFigure are short technical references, and the - MakeHuman base is ~19k verts with no rig. Downloaded files stay under - `tmp/npc-research/` (gitignored), with SHA-256 provenance in the doc. The direction is - pending owner review; default if unreviewed is procedural expansion. Do not commit or - ship an external model before the licence/ADR decision. +- **NPC model variety decision (2026-11-03, ADR-0015):** CC0 is acceptable for shipped + assets; CC-BY only with attribution in `CREDITS.md`; no service assets with redistribution + restrictions. The **procedural generator is the primary path**. Four crowd-variety specs were + prototyped with the existing builder (`npc_crowd_a` bun/slim/sunglasses, `npc_crowd_b` + bald/broad/beard/shoulder bag, `npc_crowd_c` coat/umbrella, `npc_crowd_d` hood/cup); all audit + clean at 4,550–5,258 tris / 4,356–5,086 verts. Prototype assets stay in + `tmp/npc-research/generator_proto/`; do not add them to the 0.10.0 release candidate. + **Quaternius is a reference, not a shipped base:** welding brings `Casual_Hoodie` from 12,518 + to 3,199 verts and a 0.75 decimate to 2,423 verts / 4,654 tris, and its Idle/Walk clips read + well, but the T-pose 62-bone realistic rig/proportions do not match the arm-down 13-bone + contract. A contract rebuild is a no-go without a body proportion warp; a second + rig/animation path needs its own ADR. **MakeHuman is deferred** to a separate local pipeline: + the CC0 base is 19,158 verts / 36,972 tris and decimates to 3,780 / 6,468 at 0.35, but needs + retopology, a custom rig and project clothing. Research previews are committed under + `docs/blender_previews/sheet_npc_{sources_research,crowd_prototypes}.jpg`; the CC-BY entries + (CesiumMan/RiggedFigure, © Cesium) are attributed in `CREDITS.md` and are development-only. - **0.10.0 balance protocol:** `docs/balance-acceptance.md` defines targets and denominator/cohort rules for the 36 venue/difficulty/phase cells, seeds 1–100, diff --git a/TODO.md b/TODO.md index 54037ae..fe74105 100644 --- a/TODO.md +++ b/TODO.md @@ -198,9 +198,11 @@ verify every distribution path. This is the next minor release after the 0.9.x p ## Milestone 0.11.0 — NPC model variety -Goal: break the eight-character clone effect with a reviewed, licence-cleared set of new NPC -looks while keeping the frozen `npc_base` bone, tint-slot and gear-attach contract. Start only -after the 0.10.0 release candidate is published; this milestone must not delay the release. +Goal: break the eight-character clone effect with four licence-cleared crowd-variety looks while +keeping the frozen `npc_base` bone, tint-slot and gear-attach contract. The procedural generator is +the primary path; Quaternius is a reviewed reference and MakeHuman is deferred to a separate local +development pipeline. Start only after the 0.10.0 release candidate is published; this milestone +must not delay the release. ### 0.11.1 Source review and decision @@ -209,39 +211,53 @@ after the 0.10.0 release candidate is published; this milestone must not delay t CesiumMan/RiggedFigure CC-BY and the MakeHuman CC0 base mesh; none is a drop-in. Results, local preview sheet and SHA-256 provenance are in `docs/npc-model-sourcing.md`.) -- [ ] Review the sourcing research with the project owner and choose Option A (procedural), +- [x] Review the sourcing research with the project owner and choose Option A (procedural), Option B (Quaternius CC0 intake) or Option C (MakeHuman/MPFB body pipeline); record the - decision in an ADR and in `MEMORY.md`. -- [ ] Add a source licence allow-list and provenance rule: CC0 preferred, CC-BY only with + decision in an ADR and in `MEMORY.md`. (2026-11-03: extend the procedural generator as the + primary path, keep Quaternius as a reviewed prototype/reference, defer MakeHuman to a + separate local pipeline. Recorded in ADR-0015 and `MEMORY.md`.) +- [x] Add a source licence allow-list and provenance rule: CC0 preferred, CC-BY only with attribution in `CREDITS.md`, and no service assets whose terms restrict redistribution. -- [ ] Decide whether the external preview sheet stays local under `tmp/` or is committed with - the required CC-BY attribution. + (ADR-0015; the CC-BY research previews are attributed in `CREDITS.md`.) +- [x] Decide whether the external preview sheet stays local under `tmp/` or is committed with + the required CC-BY attribution. (Committed as + `docs/blender_previews/sheet_npc_sources_research.jpg` with Cesium CC-BY attribution; + the project-owned crowd prototype sheet is also committed.) ### 0.11.2 Intake and validation - [ ] Add a Blender `inspect` path that imports a GLB, applies node transforms, reports tris/verts, bounds, bones, materials, UVs and skinning, and lists contract failures. -- [ ] Add an `adapt` path that scales/grounds the mesh, welds seams, decimates to the - triangle/vertex budget, maps materials into the five tint slots, rebuilds the contract - armature, transfers weights and writes the `npc_base` node name. +- [ ] Add an `adapt` path for future external assets: scale/ground, weld seams, decimate, map the + five tint slots, and either rebuild the contract armature or record an explicit second-rig + contract. The Quaternius prototype showed that a contract rebuild needs a proportion warp, + so this is not on the 0.11.0 critical path. - [ ] Keep `tools/blender_assets.py audit` as the single final gate; add a regression test for the intake report/adaptation using a deterministic synthetic or licence-cleared fixture. - [ ] Document the adapter commands and the go/no-go checks in `docs/asset-tooling.md`. ### 0.11.3 One-character prototype -- [ ] Adapt one Quaternius CC0 variant and capture front, three-quarter, profile, back, - full-body and crowd views plus a walk cycle. -- [ ] Measure the prototype against the `npc_casual` controls: silhouette, face style, hands, - gear fit, rest pose and walk pose. -- [ ] Make a go/no-go decision on Option B; if no-go, remove the prototype from the pipeline and - continue with Option A. +- [x] Prototype one Quaternius CC0 variant: weld/decimate to budget and capture Idle/Walk + renders. (12,518 imported verts -> 3,199 after weld -> 2,423 / 4,654 tris after a 0.75 + decimate; Idle/Walk quality is good. Preview in + `docs/blender_previews/sheet_npc_sources_research.jpg`.) +- [x] Measure the prototype against the `npc_casual` controls: silhouette, rest pose, body + proportions and gear fit. (No-go for a contract rebuild: T-pose 62-bone realistic rig, + ~0.96 m hip, ~1.68 m arm span and ~0.153 m shoulder joint do not match the arm-down + 13-bone contract. Keep as reference; a second rig/animation path needs its own ADR.) +- [x] Make a go/no-go decision on Option B. (No-go for 0.11.0; proceed with the procedural + generator and keep Quaternius as a visual/style reference.) ### 0.11.4 Roster and runtime -- [ ] Approve four new looks (age/build/hair/outfit variation across everyday, workwear and - responder families; no clothing that labels the NPC's behaviour). -- [ ] Build or adapt the approved variants and add them to the manifest with roles and tint data. +- [x] Approve four crowd-variety looks (build, head silhouette, hair/beard, outer layer and + accessory; no clothing that labels the NPC's behaviour). (`npc_crowd_a` bun/slim/sunglasses, + `npc_crowd_b` bald/broad/beard/shoulder bag, `npc_crowd_c` coat/umbrella, `npc_crowd_d` + hood/cup; prototype sheet committed.) +- [ ] Add the four approved specs to `CHARACTERS`, build and commit their GLBs/AO maps, and + update the manifest with roles and tint data. (Prototype assets are local under `tmp/`; + do not add them to the 0.10.0 release candidate.) - [ ] Replace the fixed `character_model_for()` mapping with deterministic per-role pools and add tests for repeatability and duplicate avoidance. - [ ] Rebuild and verify gear fit for every new variant (`blender_assets.py fit` plus the runtime @@ -256,6 +272,16 @@ after the 0.10.0 release candidate is published; this milestone must not delay t - [ ] Exit: a reviewed 12-character library passes contract audit, portrait/gear acceptance, the 24-NPC budget and licence/provenance review without changing the runtime contract. +### 0.11.6 Deferred MakeHuman local pipeline + +- [x] Evaluate the MakeHuman CC0 base mesh for a later separate local development pipeline. + (19,158 verts / 36,972 tris; scaled to 1.82 m; decimate 0.35 -> 3,780 verts / 6,468 tris; + UVs present, no normals/material groups/rig. Feasible only with retopology, a custom rig and + project-owned clothing; keep out of CI/build.) +- [ ] Decide whether body-shape diversity still matters after the 12-character library lands; if + yes, prototype the local MPFB/MakeHuman pipeline outside the repo and commit only the final + CC0-derived assets with provenance. + ## Future 0.x / non-blocking candidates - [ ] Live 3D body-camera replay. diff --git a/docs/adr/0015-npc-model-variety-sourcing.md b/docs/adr/0015-npc-model-variety-sourcing.md new file mode 100644 index 0000000..986b0ff --- /dev/null +++ b/docs/adr/0015-npc-model-variety-sourcing.md @@ -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. diff --git a/docs/adr/README.md b/docs/adr/README.md index 04f198e..bc0e385 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -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) diff --git a/docs/asset-tooling.md b/docs/asset-tooling.md index e311973..ad0ac11 100644 --- a/docs/asset-tooling.md +++ b/docs/asset-tooling.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 | | --- | --- | diff --git a/docs/blender_previews/README.md b/docs/blender_previews/README.md index ce283b4..fa0b321 100644 --- a/docs/blender_previews/README.md +++ b/docs/blender_previews/README.md @@ -43,6 +43,8 @@ Committed contact sheets and local Blender renders for the character, gear and p | security_podium.png | [`security_podium.png`](security_podium.png) | | sedan.png | [`sedan.png`](sedan.png) | | sheet_npc.jpg | [`sheet_npc.jpg`](sheet_npc.jpg) | +| sheet_npc_sources_research.jpg | [`sheet_npc_sources_research.jpg`](sheet_npc_sources_research.jpg) | +| sheet_npc_crowd_prototypes.jpg | [`sheet_npc_crowd_prototypes.jpg`](sheet_npc_crowd_prototypes.jpg) | | sheet_npc_baseline.jpg | [`sheet_npc_baseline.jpg`](sheet_npc_baseline.jpg) | | sheet_npc_baseline_compare-p1.jpg | [`sheet_npc_baseline_compare-p1.jpg`](sheet_npc_baseline_compare-p1.jpg) | | sheet_npc_baseline_compare-body.jpg | [`sheet_npc_baseline_compare-body.jpg`](sheet_npc_baseline_compare-body.jpg) | diff --git a/docs/blender_previews/sheet_npc_crowd_prototypes.jpg b/docs/blender_previews/sheet_npc_crowd_prototypes.jpg new file mode 100644 index 0000000..46fbc11 Binary files /dev/null and b/docs/blender_previews/sheet_npc_crowd_prototypes.jpg differ diff --git a/docs/blender_previews/sheet_npc_sources_research.jpg b/docs/blender_previews/sheet_npc_sources_research.jpg new file mode 100644 index 0000000..7779177 Binary files /dev/null and b/docs/blender_previews/sheet_npc_sources_research.jpg differ diff --git a/docs/npc-model-sourcing.md b/docs/npc-model-sourcing.md index 7808eba..7c07c55 100644 --- a/docs/npc-model-sourcing.md +++ b/docs/npc-model-sourcing.md @@ -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 | | --- | --- | --- |