From 1921bfae91d409c21acdc5ddcbaf4b1009213174 Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Tue, 3 Nov 2026 08:22:09 +0100 Subject: [PATCH] Document the character development toolchain in the architecture --- TODO.md | 6 +++++- docs/architecture.md | 45 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 1 deletion(-) diff --git a/TODO.md b/TODO.md index fe74105..fd1138d 100644 --- a/TODO.md +++ b/TODO.md @@ -181,7 +181,11 @@ verify every distribution path. This is the next minor release after the 0.9.x p `check_screenshots.sh` and the pinned vision judge, recording model/spend/verdicts. - [ ] Run the manual smoke checklist on every target and attach/link the release-candidate evidence. - [ ] Verify the tutorial/campaign/help text at maximum font scale and with the longest strings. -- [ ] Remove or archive stale plans/notes and confirm no contradictory version/status claims remain. +- [x] Remove or archive stale plans/notes and confirm no contradictory version/status claims remain. +- [x] Document the character development toolchain in `docs/architecture.md`: base vs library + sources, tool/artifact/gate table, runtime attach/animation contracts and rebuild discipline. + (Added §5 "Character development tooling" plus risk and ownership-map updates; + documentation check passed.) ### Release-candidate QA and exit diff --git a/docs/architecture.md b/docs/architecture.md index f00e613..b8e5d7a 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -127,6 +127,48 @@ Contracts that keep the pipeline replaceable: - UI/scene art is loaded through `UiArt` with a null/neutral fallback; composed images live in `assets/images/`, not in the docs reference tree (ADR-0014). - CI stays offline: only committed `.glb`/`.png`/`.tres` and Godot are needed; optional AI/Blender steps are reproducible development tools. +### Character development tooling + +Characters have two authored sources and one procedural fallback. The eight-variant +Blender library (`assets/models/blender/npc/`) is the normal presentation path; the +older skinned `npc_base` (`assets/models/generated/npc_base.glb`) remains a frozen +contract and fallback; `NpcAvatar`'s procedural rig is the offline last resort. +Blender is a developer tool only — runtime, tests and CI consume committed GLBs and +maps. + +| Tool | Role | Committed artifact | Verification gate | +| --- | --- | --- | --- | +| `tools/npc_pipeline.py` | Builds the skinned base avatar, five-slot material maps, palette and AI-fabric preparation (`prepare`/`palette`) | `npc_base.glb`, `assets/textures/npc/*_{albedo,normal,orm}.png`, `palette.json` | `audit_glb` against the frozen 6,000-triangle / 4,000-vertex base contract | +| `tools/blender_assets.py` | Builds/renders the library: 8 characters, 18 gear pieces, 20 props, plus `manifest.json`; stdlib `audit`/`fit`/`sheet`/`list` | `assets/models/blender/{npc,npc_gear,props}/*.glb` | Library cap 8,000 tris / 8,000 verts per character, 1,500 per gear, 4,000 per prop; grounding, UV, degenerate-triangle, attach-fit and manifest coverage checks | +| `tools/bake_ao.py` | Bakes per-asset AO maps | `_ao.png` (256²) | Wired through `Materials.apply_ao()`/`SurfaceMaterials`; cloth/pants opt out (see below) | +| `tools/npc_proportions.py` | Measures exported GLB rest pose (height, head, shoulders, hips, torso, limbs, feet) against the stylized guide | report / JSON in `docs/npc-proportion-audit.md` | All eight variants must stay inside the guide after a body change | +| `tools/npc_baseline.py` | Assembles neutral-baseline sheets and before/after comparisons | `docs/blender_previews/sheet_npc_baseline*.jpg` | Human review against `docs/npc-visual-review.md` | +| `src/test/capture_npc_baseline.gd` | Fixed-camera studio baseline, 8 variants × 6 views | local `tmp/` frames | Neutral silhouette/face/gear review | +| `src/test/capture_npc_review.gd` | Final-context gate: 8 variants × 2 venues × day/night × 3 distances = 96 frames, crowd hidden, review-only `character_override` for the guard | local `tmp/` frames | Pre-build acceptance gate for gear fit and venue lighting | +| `src/test/capture_realism.gd` | Venue realism stages plus a frozen portrait and surface close-ups | `docs/screens/realism//` | Optional vision judge; portrait is the only avatar-detail capture | + +Runtime contracts that must survive any character change: + +- `NpcAvatar.character_model_for(role, seed)` selects the library variant; `character_override` + exists only to stage roles without a spawned model (for example the guard). +- The armature node names, `Rig/Head`, the Hip/Knee/Shoulder/Elbow/Hand proxies and the + **+Z visual front** are frozen; animation and `yaw_towards()` depend on them. +- Only the five contract slots are tinted. Fixed detail materials (eyes, reflective bands, + rubber) stay untouched, gear is placed by `GEAR_ATTACH`, and `GEAR_OFFSETS` plus + `HAND_ITEM_FORWARD` are runtime attach-space corrections, not authoring changes. +- Cloth/pants use `Materials.NPC_FABRIC_UV_SCALE` (4×) and skip the baked per-character AO; + skin/hair/gear keep AO. Do not reintroduce the blotchy cloth AO. +- `apply_lod()` swaps to an impostor at 26 m; the 24-NPC budget smoke (6.94 ms, 168 meshes, + 131,616 triangles) is the performance gate. Changing either triangle cap requires + re-measuring that smoke and the Web/Compatibility path. +- Rebuild only the assets whose geometry changed (Blender GLB export is byte-nondeterministic), + then run `godot --headless --path . --import`; never commit a no-op full rebuild. + +Evidence and detailed contracts live in [`blender-assets.md`](blender-assets.md), +[`npc-visual-review.md`](npc-visual-review.md) and +[`npc-proportion-audit.md`](npc-proportion-audit.md); command-level usage is in +[`asset-tooling.md`](asset-tooling.md). + ### Content authoring and runtime data flow `ScenarioFactory` is the source of truth for the three authored venues. `tools/export_venues.gd` @@ -272,6 +314,7 @@ Architecture decisions are recorded as ADRs: - Accessibility and localization coverage is partial; a public release needs subtitles/captions, colour-independent cues, remapping, text expansion tests and at least a documented localization workflow. - Unsigned macOS builds, AI asset provenance and any storefront/legal requirements are release blockers for a public release. - Documentation drift has already occurred (release version, implemented status and obsolete plan docs); the ownership map and roadmap must be kept current in the same change as the implementation. +- Character quality is only partly automatable: proportions, budgets and gear fit are measured, but face realism and venue-lighting readability still need the baseline/review sheets and human sign-off after any mesh, map or material change. ## 12. Documentation Consolidation and Ownership @@ -287,6 +330,8 @@ architecture document. | [`docs/adr/`](adr/) | Immutable decision records with context and consequences | Decision history linked from §9 | | [`docs/asset-tooling.md`](asset-tooling.md) | Build/audit/capture commands and pipeline usage | Operational appendix to the pipeline section | | [`docs/blender-assets.md`](blender-assets.md) | Blender character/gear/prop contracts and attach points | Detailed asset contract appendix | +| [`docs/npc-visual-review.md`](npc-visual-review.md) | NPC baseline views, acceptance criteria and ranked visual gaps | Visual-QA appendix to the character tooling section | +| [`docs/npc-proportion-audit.md`](npc-proportion-audit.md) | Measured proportions against the stylized guide | Measurement appendix to the character tooling section | | [`docs/getting-started.md`](getting-started.md) | Setup, commands, controls | Developer onboarding | | [`docs/RELEASING.md`](RELEASING.md) | Release checklist and CI/publishing steps | Deployment appendix to §7 | | [`docs/smoke-checklist.md`](smoke-checklist.md) | Manual verification script | QA appendix to §10 |