From 3e41cda5917e396fca6cc5f769ca75d9b7b159d9 Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Tue, 3 Nov 2026 10:19:46 +0100 Subject: [PATCH] Re-plan the Blender tracks around the local skills and a 3D model review --- AGENTS.md | 64 +++++++- MEMORY.md | 19 ++- PLAN.md | 2 +- TODO.md | 323 ++++++++++++++++++++++++++----------- docs/development-status.md | 14 +- 5 files changed, 312 insertions(+), 110 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b1a5bad..6c4a8bf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,7 +28,8 @@ The project should be developed in small, reviewable steps. Agents must keep pla `TODO.md` is the priority source. The active order is: -1. unversioned development tracks (currently character development and local map development); +1. unversioned development tracks (currently 3D model re-evaluation, character development and + local map development); 2. versioned release milestones, in version order; 3. future/unversioned candidates and deferred work. @@ -36,6 +37,65 @@ Do not assign a version number to an unversioned track until its scope is accept release. When a version is assigned, it must be the next semantic version that matches the scope (major/minor/patch), not a placeholder. +## Local Blender skills (development aid) + +The MIT `blender-skills` pack is installed locally at `.agents/skills/blender-skills/` +(94 skills plus a shared `references/` folder). It is **gitignored on purpose**: it is not +game content, not part of the build, tests, CI or release packages, and every contributor +may or may not have it. Pi gates project `.agents/skills` behind project trust, so the +trust prompt has to be accepted before the skills load; `/skill:blender-director` forces one. + +Use them when a task touches `tools/blender_assets.py`, `tools/npc_pipeline.py`, +`tools/bake_ao.py`, `assets/models/blender/**`, or Blender-authored venue/prop geometry. + +### Routing + +Start with `blender-director` for anything multi-discipline, then load only the +specialists the task needs: + +| Work | Skills | +| --- | --- | +| Plan/route a Blender task, reference photo match | `blender-director` | +| Character mesh, face, hands, proportions | `character-artist`, `character-archetypes`, `retopology` | +| Skeleton, weights, pose/contract rigging | `rigging` | +| UV layout, texel density, UDIM | `uv-workflow` | +| Bakery, atlas, normal/AO/ORM maps | `texture-workflow` | +| PBR materials and shading | `materials` | +| Screenshot-driven material/light iteration | `lookdev` | +| Triangle/vertex budgets, naming, scene hygiene | `asset-optimization` | +| LOD tiers and impostors | `lod-pipeline` | +| Collision shapes and proxies | `collision-proxy` | +| GLB export for Godot | `godot-export`, `export-pipeline` | +| Gear, props, street furniture | `prop-artist`, `hard-surface` | +| Trees, hedges, foliage cards | `vegetation-artist` | +| Facades, venues, modular kits, dressing | `environment-artist`, `archviz`, `set-dressing`, `geometry-nodes` | +| Lighting, framing, final render/composite | `lighting`, `camera-cinematography`, `rendering`, `compositing` | +| Style direction (stylized / low-poly / realistic) | `stylized-style`, `lowpoly-style`, `realistic-style` | +| Ship/no-ship review | `qa-review` | + +The same skills cover the local map track (procedural geometry, facade kits, OSM massing, +splat reference renders) and the NPC roster work. + +### Project rules that override a skill + +1. **The project contract wins.** `npc_base` mesh node, the 13 contract bones at their rest + positions, five tint slots, front on Blender −Y / Godot +Z, grounded feet, 8,000 + triangles / 8,000 glTF vertices per character, 1,500 per gear, 4,000 per prop. A skill + may recommend another topology, naming or budget scheme; do not adopt it unless the + change is explicitly planned and the contract, tests and docs are updated together. +2. **There is no Blender MCP here.** The skills assume MCP tools; this project runs Blender + as headless flatpak scripts (`tools/blender_assets.py`, `tools/npc_pipeline.py`). Translate + MCP steps into script changes or CLI runs. Never add an MCP dependency to the build, CI or + runtime. +3. **CI stays offline and skill-free.** Skills are local guidance only; every gate must still + work from a fresh checkout with committed `.glb`/`.png`/`.tres` files and Godot. +4. **No new asset source without the licence gate.** Skills may suggest reference packs or + generated meshes; ADR-0015 (CC0, or CC-BY with attribution in `CREDITS.md`) and the + provenance rules in `docs/npc-model-sourcing.md` still apply. +5. **Evidence, not vibes.** After a skill-informed change, run `blender_assets.py inspect`, + `audit` and `fit` plus the relevant capture/smoke gates, and say in the handoff which + skills informed the change and what the measurements were. + ## Required Workflow ### 1. Start by Inspecting the Repository @@ -268,6 +328,8 @@ Before handing off work, an agent must run every check below that applies to the - Run automated tests. - Run formatting, linting, or type checks. - Start the game or application and perform a basic smoke test. +- For 3D/Blender changes: `blender_assets.py inspect`, `audit` and `fit`, the relevant capture + gate, and a note of which local skills informed the change. - Check that documentation and task status reflect the actual state. - Review the final diff for accidental changes or unfinished markers. diff --git a/MEMORY.md b/MEMORY.md index 28ec2d8..08c8613 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -4,6 +4,14 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o ## Decisions +- **3D model re-evaluation first (2026-11-03):** `TODO.md` is re-planned around a new unversioned + `3D model re-evaluation` track, ahead of character and local-map work, because the crowd-variant + roster would otherwise multiply whatever the existing models get wrong. It scores all 8 + characters, 18 gear, 20+6 props and the three venues in `docs/3d-model-review.md`, fixes ranked + P0/P1 only, and must not change the `npc_base` contract, renderer or 0.10.0 candidate. The MIT + Blender skill pack is now routed through `AGENTS.md` §Local Blender skills; skill advice loses + to the project contract, and there is no Blender MCP here (headless flatpak scripts instead). + MEMORY is ~960 lines with dated historical entries; trimming it is a tracked maintenance task. - **GLB intake inspection (`blender_assets.py inspect`, 2026-11-03):** runs inside Blender, clears parents and applies object transforms, then reports tris/budget, raw and seam-split verts, Godot-space bounds (height/feet for characters), bones, materials, UVs, skinning and @@ -356,11 +364,11 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o **Mockup copies:** 21 design references live in `assets/images/ui/`; `docs/screens/designs/` remains the reference-only copy. `tools/screen_designs.py` reads/writes the runtime root. -## Handoff (read this first) +## Handoff — historical snapshot (2026-11-01; superseded by Current State / Plan vs code) -- **Status (2026-11-01, after the venue-geometry pass):** v0.7.0 is released. Post-v0.6.0 the +- **Status (2026-11-01, after the venue-geometry pass):** v0.7.0 was released at that point. Post-v0.6.0 the realism pass, the visual-alignment pass and the NPC face/hand pass all landed. Headless - **229/229**, Python tooling **87/87**, `tools/check_screenshots.sh` **11 good / 0 bad**, + **272/272**, Python tooling **108/108**, `tools/check_screenshots.sh` **21 good / 0 bad**, `screen_designs.py compare` 11 good / 0 bad, `scene_concepts.py audit` all GOOD, `blender_assets.py audit` exit 0, `smoke_npc_budget` OK (16 avatars, 6.94 ms of 50 ms). `PLAN.md` is compact; README/architecture track the current controls, asset pipeline, CI and @@ -914,13 +922,14 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o - Shift length: `GameManager` uses the scenario's `shift_duration_s` (900s ≈ 10-15 min); tests and the screenshot tool override elapsed time directly. - Headless (dummy renderer) logs "Parameter m is null" from `mesh_get_surface_count`; it does not occur with a real GL driver and does not affect logic. -- Steps are visual-only (no collider) so NPCs can path to the entrance; the guard spawns on the landing so it never needs to climb. +- Steps have per-tread colliders (`_build_steps()` adds a `StaticBody3D` with one `BoxShape3D` + per tread), so the guard and NPCs walk up the entrance; the guard spawns on the landing. - Persistence tests write into the real `user://shift_results.json` (harmless local pollution of the demo history). - macOS export required `rendering/textures/vram_compression/import_etc2_astc=true` in `project.godot` (universal build demands ETC2 ASTC enabled). - Venue `door_staff_lines` are logged through `GameManager` (inspect / wand / refuse). They are not a separate dialogue UI. - Access loadout is implemented; do not re-fix `override_access` as if it were still unread. - `Save.SETTINGS_FILE` is declared and unused; settings persistence goes through `Save.load_settings()` / `save_settings()`. -- Headless suite is **272/272**; Python tooling is **101/101**; screenshot compare is **21 good / 0 bad** and the automatic judge is **21/21 match, 0 diff**. Remaining visual follow-ups are in `TODO.md`. +- Headless suite is **272/272**; Python tooling is **108/108**; screenshot compare is **21 good / 0 bad** and the automatic judge is **21/21 match, 0 diff**. Remaining visual follow-ups are in `TODO.md`. - Typed spawn signal extra args: handlers must accept the 4th `event: Dictionary` or Godot will not call them (`test_shift_coordinator_runs_a_shift` failed until `_on_spawn` took four args). - GDScript inference trap that broke the main scene: a `var` typed as a base class (`radial: CanvasLayer`) exposes script members as `Variant`, so `var x := radial.is_open` is a diff --git a/PLAN.md b/PLAN.md index 7e41557..ab6cf9d 100644 --- a/PLAN.md +++ b/PLAN.md @@ -170,7 +170,7 @@ The action wheel prioritizes de-escalation: Stop, Look, Point, No, Ask, Inspect, The visual direction is readable stylized realism: - **Character direction:** 8 skinned NPC variants, 18 gear pieces and 20 street/venue props, with four crowd-variety variants prototyped. The generator-first expansion is the active character track ([ADR-0015](docs/adr/0015-npc-model-variety-sourcing.md)); Quaternius is a reference and MakeHuman is deferred to a local pipeline. -- **Realism pass:** AI-assisted per-phase skyline panoramas, v2 surface tiles with normal maps, wet asphalt at night, a warm day haze, phase-specific sun/exposure/fog, a visible flashlight beam, and denser foliage. +- **Realism pass:** AI-assisted per-phase skyline panoramas, v2 surface tiles with normal maps, wet asphalt at night, a warm day haze, phase-specific sun/exposure/fog, a tight flashlight spot (no beam geometry), and denser foliage. - **Local map direction:** the venues are currently stylized reconstructions. The local-map track evaluates licensed OpenStreetMap/3D building data, licensed reference photography, AI-assisted composition and Gaussian splatting as a development tool; online data and splat rendering are not runtime dependencies. - **References and QA:** runtime UI art lives in `assets/images/ui/`; reference/art-direction sets live in `docs/screens/designs/` and `docs/screens/concepts/`; captures live in `docs/screenshots/`; realism runs live in `docs/screens/realism/`. `screen_designs.py compare/judge` and `tools/check_screenshots.sh` guard drift. - **Storage convention:** see [ADR-0014](docs/adr/0014-runtime-image-root.md). Never overwrite an existing image; new outputs get a new path or `-vN` suffix. diff --git a/TODO.md b/TODO.md index b14919e..8d22132 100644 --- a/TODO.md +++ b/TODO.md @@ -3,16 +3,119 @@ Work is grouped by theme. Each item should be small enough to complete and verify on its own; see `AGENTS.md` for the workflow and `MEMORY.md` for the decisions behind these plans. -**Priority order:** Character development → Local map development → versioned release milestones → -future/deferred work. See `AGENTS.md` §Priority and Versioning. +**Priority order:** 3D model re-evaluation → character development → local map development → +versioned release milestones (0.10.0) → future/deferred work. See `AGENTS.md` §Priority and +Versioning and §Local Blender skills. + +The MIT Blender skill pack lives locally at `.agents/skills/blender-skills/` (gitignored). Every +3D workstream below names the skills to load; they are guidance only, and the project contract, +`blender_assets.py audit`/`fit`/`inspect` and the capture gates stay authoritative. + +## 3D model re-evaluation + +Goal: re-judge every shipped 3D asset against the newly available Blender skill guidance, rank +the real gaps, and fix only what the rankings justify. This is an unversioned development track: +it must not change the `npc_base` contract, the renderer or the 0.10.0 release candidate. + +Scope: 8 library characters (`npc_casual`, `npc_jacket`, `npc_coat`, `npc_vest`, `npc_dress`, +`npc_hoodie`, `npc_firefighter`, `npc_guard`), the frozen `npc_base` fallback, 18 gear pieces, +20 library props, 6 generated props, and the three venue families. + +**Exit:** `docs/3d-model-review.md` scores every catalogue asset; every P0/P1 is fixed or +explicitly accepted with a measurement; `inspect`/`audit`/`fit`/proportions, the 24-NPC budget +and the capture gates are green; no runtime contract, dependency or release artifact changed +except the rebuilt assets themselves. + +### A. Baseline, scorecard and routing + +- [ ] Load `blender-director` plus the per-family specialists before touching geometry, and + record the skill stack and the advice that changed a decision in `docs/3d-model-review.md`. +- [ ] Re-run the neutral NPC baseline (48 frames), the final-context review (96 frames), the + prop gallery and the 24-NPC budget on the current build; keep raw frames in `tmp/` and do + not replace committed sheets until a fix lands. +- [ ] Create `docs/3d-model-review.md` with a per-asset scorecard: silhouette, anatomy/proportion, + topology/edge flow, UV/texel density, textures/materials, rig/weights, LOD/impostor, + collision/grounding, export contract, provenance, skill route, verdict (P0/P1/P2/accept). +- [ ] Collect the baseline measurements in one table: `blender_assets.py inspect`, `audit`, `fit`, + `npc_proportions.py`, texel density, triangles/meshes, 24-NPC frame time. +- [ ] Review the scorecard with the project owner, rank the P0/P1 gaps and decide fix vs accept + per item; record the decision and the reason in the review document. + +### B. Character re-evaluation (8 variants + fallback) + +*Skill route: `character-artist`, `retopology`, `rigging`, `uv-workflow`, `texture-workflow`, +`materials`, `hair-groom`, `asset-optimization`, `lookdev`, `qa-review`.* + +- [ ] Face/head: review eye/mouth loops, cheek/brow/chin transitions and faceting at the 2 m + portrait distance against `character-artist` and `retopology`; write the concrete edits. +- [ ] Hands/grip: re-check palm, finger segments, thumb and gear contact; decide between a + finger-curl rig or the current open hand plus `HAND_ITEM_FORWARD`, and record the limit. +- [ ] Weights/pose: capture idle, walk, sit and wave; inspect shoulder, hip and neck collapse; + fix the worst offenders using `rigging` practice without changing the 13-bone contract. +- [ ] UV/texel density: measure the 256² slot maps; decide whether atlas, UDIM or a resolution + change is justified. Do not change `CHAR_MAX_TRIS`/`CHAR_MAX_VERTS` without re-running the + budget smoke and the Web/Compatibility path. +- [ ] Cloth and hair: re-check coat/dress hem clipping and the hair/beard/headgear meshes against + `hair-groom` guidance; decide explicitly whether cloth simulation stays out of scope. +- [ ] Fix only the ranked P0/P1s, one asset family per commit; refresh the comparison sheet and + re-run `inspect`, `audit`, `fit` and `npc_proportions.py` after each fix. +- [ ] `qa-review` sign-off: a ship/no-ship verdict per variant with accepted limits recorded. + +### C. Gear and prop re-evaluation + +*Skill route: `prop-artist`, `hard-surface`, `vegetation-artist`, `materials`, `collision-proxy`, +`lod-pipeline`, `qa-review`.* + +- [ ] Gear: review the 18 pieces for silhouette, straps/buckles, helmet and lanyard readability; + verify attach space and body clearance with `fit`; rebuild only what fails the scorecard. +- [ ] Props: review the 20 library props plus the 6 generated props for bevels, chamfers, + silhouette, ground contact and shared material language (`prop-artist`, `hard-surface`); + list the rebuilds that are actually worth the triangle budget. +- [ ] Foliage: replace the flat-shaded `_shrub()`/`_tree()` clumps with `vegetation-artist`-style + carded clusters; measure triangles and keep the 60k `LIBRARY_TRIANGLE_BUDGET`. +- [ ] Materials and emissives: `lookdev` pass on bulbs, signs, lanterns, the marquee and the + sedan at day and late; confirm the flashlight stays a tight spot with no beam geometry. +- [ ] Collision: verify every prop collider and navigation obstacle matches its silhouette and + add the missing `collision-proxy` shapes where walking is blocked. +- [ ] Exit: a prop/gear capture sheet, budgets and collision checks pass with no unreviewed asset. + +### D. Venue and camera re-evaluation + +*Skill route: `environment-artist`, `archviz`, `set-dressing`, `lighting`, `camera-cinematography`, +`lookdev`, `rendering`, `qa-review`.* + +- [ ] Facade/venue review: rank the top five shape-language fixes for Hollywood, the Joke Shop and + the TV Studio (`environment-artist`, `archviz`) and check them against the map-budget tests. +- [ ] Lighting: `lighting`/`lookdev` pass on sconces, canopy, marquee and street lamps with + day/late captures; verify local attenuation stays at 1.0 and no constant-falloff light returns. +- [ ] Set dressing: review entrance and sidewalk prop clusters (`set-dressing`) for occlusion, + navigation obstacles and readable storytelling clusters. +- [ ] Camera height: decide 1.7 m gameplay framing vs the ~1.55 m concept frames using + `camera-cinematography`, and record the decision instead of leaving the mismatch open. +- [ ] Hooded/winter portrait: close the deferred close-up by staging a types 5–7 capture + (`--portrait-type`) or adding a scenario spawn that provides one. + +### E. Gates and documentation + +- [ ] Add the measurable checks the review needs (texel density, weight/pose sanity, collider + coverage, LOD/impostor check) as stdlib or GDScript gates where possible; CI stays offline. +- [ ] Add a coverage test so every catalogue asset has a scorecard row and verdict. +- [ ] Update `docs/blender-assets.md`, `docs/npc-visual-review.md`, `docs/3d-model-review.md`, + `docs/architecture.md` and `AGENTS.md` with the skill routes and the new gates. +- [ ] Record accepted limits and deferred rebuilds in `docs/known-limitations.md` and `MEMORY.md`. ## Character development 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. This is the current development priority; keep it out of the frozen -0.10.0 release candidate and assign a release version only when its scope is accepted. +development pipeline. + +The roster build is deliberately sequenced **after** the 3D model re-evaluation: the new variants +must inherit the reviewed face/hand/gear baseline instead of multiplying whatever it finds. + +*Skill route: `character-artist`, `retopology`, `rigging`, `uv-workflow`, `materials`, +`asset-optimization`, `lowpoly-style`, `godot-export`, `qa-review`.* ### Source review and decision @@ -41,13 +144,13 @@ development pipeline. This is the current development priority; keep it out of t (`blender_assets.py inspect --file ...` applies parent/object transforms, converts to Godot Y-up, ignores the importer's bone-shape helper and prints budgets, bones, slots, UVs, skinning and animations with issues/warnings; `--json` and `--category` supported. - Seven synthetic contract tests added (Python 108/108); all 46 library GLBs inspect clean, - and a wrapped 2x fixture correctly reported a 0.975 m local/world delta. Blender-side only; - `audit` remains the final gate.) + Seven synthetic contract tests added; all 46 library GLBs inspect clean. `audit` remains + the final gate.) - [ ] 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 character-development critical path. + contract. Use `retopology`/`rigging`/`uv-workflow` guidance for the manual steps, but keep + the Quaternius no-go: a contract rebuild needs a proportion warp, so this is not on the + character 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`. @@ -71,13 +174,16 @@ development pipeline. This is the current development priority; keep it out of t 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.) +- [ ] Re-derive the four approved specs against the re-evaluated character baseline (face, hands, + proportions, gear offsets) so the new variants do not reintroduce the gaps the review found. - [ ] 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 current release candidate.) + update the manifest with roles and tint data. Build only the new assets, never a no-op full + rebuild, and remember that `export_filter="all_resources"` packs committed GLBs into the + next release build: keep this off `main` until after the 0.10.0 tag or accept the size. - [ ] Replace the fixed `character_model_for()` mapping with deterministic per-role pools and add - tests for repeatability and duplicate avoidance. + tests for repeatability and duplicate avoidance (`godot-export` contract check included). - [ ] Rebuild and verify gear fit for every new variant (`blender_assets.py fit` plus the runtime - gear checks). + gear checks) and re-run `inspect` on the four new GLBs. ### QA and release @@ -104,6 +210,10 @@ Goal: build a local, data-backed map pipeline that can replace or supplement the geometry with licensed OpenStreetMap footprints, 3D building massing, reference-derived photoreal facades and AI-assisted composition. This is an unversioned development track, not a release gate. +*Skill route: `environment-artist`, `archviz`, `hard-surface`, `geometry-nodes`, +`procedural-modeling`, `vegetation-artist`, `set-dressing`, `lighting`, `materials`, +`texture-workflow`, `lookdev`, `scene-assembly`, `qa-review`.* + ### Data, licensing and scope - [ ] Define the first target block and whether the result replaces, supplements or only informs @@ -128,16 +238,19 @@ facades and AI-assisted composition. This is an unversioned development track, n - [ ] Separate development-only references from shipped textures; commit only images with clear redistribution rights and keep the rest under `tmp/` or the ignored reference folders. - [ ] Define the photoreal target and a material-derivation workflow (albedo/normal/roughness, - AO, weathering) that matches the existing Compatibility renderer. + AO, weathering) that matches the existing Compatibility renderer (`texture-workflow`, + `materials`, `lookdev`). ### Geometry and AI-assisted composing - [ ] Prototype OSM footprint import into Blender at game scale and orientation, then compare it against the current venue footprint/collider layout. - [ ] Import 3D building massing for the target block, clean the topology and assign LOD bands; - do not import unbounded city-scale meshes into the runtime. + do not import unbounded city-scale meshes into the runtime (`scene-assembly`, + `asset-optimization`, `lod-pipeline`). - [ ] Build a reusable photoreal facade kit (window bays, cornices, storefronts, awnings, signage) - so buildings share materials and stay inside the venue triangle/material budgets. + with `environment-artist`/`hard-surface`/`geometry-nodes` so buildings share materials and + stay inside the venue triangle/material budgets. - [ ] Add an AI-assisted composition step for palette, facade rhythm and reference boards; record the model, prompt and output, and keep human review as the acceptance gate. AI output must not be treated as licensed map data or shipped without provenance. @@ -188,9 +301,10 @@ reference-image licence and privacy gates above rather than replacing them. erase facade edges, signage or window detail, and keep the redacted input variant. - [ ] Align the splat to game coordinates from the OSM footprint plus surveyed points (door width, column spacing, step rise, storefront height) and record alignment residuals in a - Blender scene containing both the splat and the current venue geometry. -- [ ] Judge quality from held-out views and a render from the game’s day/night camera poses, - not from training views alone; reject splats that only look correct from the capture path. + Blender scene containing both the splat and the current venue geometry (`scene-assembly`). +- [ ] Judge quality from held-out views and a render from the game's day/night camera poses + (`camera-cinematography`, `lookdev`, `qa-review`), not from training views alone; reject + splats that only look correct from the capture path. - [ ] Maintain a coverage map per block: which facades, corners and rooflines have usable views, and which areas must fall back to the facade kit or stylized geometry. @@ -200,11 +314,11 @@ reference-image licence and privacy gates above rather than replacing them. compare it with the realism captures; derive dimensions, signage placement, facade rhythm and material colours. No splat data reaches the runtime. - [ ] **Path B — Texture derivation:** project splat renders onto the facade kit to produce - albedo, normal, roughness and AO candidates; de-light and bake them, then verify UV scale, - tiling and readability under the Compatibility renderer. + albedo, normal, roughness and AO candidates; de-light and bake them (`texture-workflow`), + then verify UV scale, tiling and readability under the Compatibility renderer. - [ ] **Path C — Mesh proxy:** extract a mesh from the splat or dense reconstruction, retopo and - dress it in Blender, assign LODs, and keep it inside the venue triangle/material budgets - with mesh-based colliders and navigation. + dress it in Blender (`retopology`, `prop-artist`), assign LODs (`lod-pipeline`), and keep it + inside the venue triangle/material budgets with mesh-based colliders (`collision-proxy`). - [ ] **Path D — Distant backdrop:** test a baked panorama, impostor or billboard generated from the splat for skyline and opposite-street depth where the player cannot walk; measure file size, loading and visible pop at the venue boundary. @@ -244,11 +358,87 @@ reference-image licence and privacy gates above rather than replacing them. facades, passes performance/navigation/visual QA and has complete provenance; or the pipeline is rejected with the findings recorded. +## Maintenance and documentation hygiene + +Unversioned housekeeping that keeps the planning sources trustworthy. Do these when they block a +task, not on a schedule. + +### Memory and status accuracy + +- [ ] Trim `MEMORY.md` from ~970 lines to the durable set: drop the pre-0.8 host/disk/NSIS/release + anecdotes, superseded v0.2.x handoff status and duplicated release notes, keep the gotchas + that still bite (async/event wiring, import order, colliders, RNG, contracts), and keep the + easter-egg note. +- [ ] Re-check the remaining memory claims against code before deleting them; `MAX_LIVE_NPCS` is + still 16 for gameplay while the separate budget smoke spawns 24, so do not "fix" that. +- [ ] Fix stale status claims as they are found (the step-collider and flashlight-beam claims were + corrected on 2026-11-03); add a documentation check or grep note only if the same class of + drift returns. + +### Blender skills upkeep + +- [ ] Re-check the installed Blender pack (`version.json`) when updating it and record the version + in `AGENTS.md` if it changes; keep `.agents/` gitignored and `.agents/.gdignore` in place. +- [ ] Prune the skill routes in `AGENTS.md` if a skill stops matching the project (for example if + a future second-rig path makes `rigging`/`animation` guidance authoritative). + +## Gap Analysis and 0.x Roadmap + +Baseline: **v0.9.6** (2026-11-03). Three playable venues, tutorial/campaign/checkpoint resume, +difficulty/help, audio/accessibility settings, a 24-NPC budget baseline, a complete +escalation/access/radio loop, shift review, the Blender asset library, 272 headless + 108 Python +tests, a 21/21 clean screen-design judge and an optional Forward+ Desktop HQ build. This is the +baseline; 0.10.0-rc.1 is the current candidate source, with release approvals still open. + +### Documentation audit (completed 2026-11-01) + +- [x] Make `docs/architecture.md` the single architecture source: asset/content pipeline + contracts, runtime venue-switch/fallback flows, deployment/version constraints, quality + requirements, risk register and documentation ownership map. +- [x] Keep command-heavy operational pages separate but subordinate: `docs/asset-tooling.md`, + `docs/blender-assets.md`, `docs/getting-started.md`, `docs/RELEASING.md` and + `docs/smoke-checklist.md` link to architecture rather than acting as parallel sources. +- [x] Remove the obsolete `docs/plan-graphics-v0.6.md` and its links; completed graphics work is + represented by ADR-0013, the asset pipeline section and the changelog. +- [x] Resolve stale claims: README release version/download row, development status + "Forward+ not implemented", and Blender props "not AO-baked". +- [x] Record the documentation ownership rule in `docs/architecture.md` §12: design intent + (`PLAN.md`), mechanics (`gameplay.md`), system architecture/contracts (`architecture.md`), + decisions (ADRs), status (`development-status.md`), roadmap (`TODO.md`), operations + (tooling/release docs). + +### Gap register (remaining roadmap) + +| Area | Current baseline | Remaining gap | Risk | Milestone | +| --- | --- | --- | --- | --- | +| 3D model re-evaluation | 8 characters, 18 gear, 20+6 props audited against budgets/proportions; no skill-guided scorecard yet | Scorecard, ranked P0/P1 fixes, texel/weight/collider measurements and accept decisions | Unmeasured drift stays in the shipped library | Unversioned | +| Character development | 8-variant library; source/licence review and Quaternius/MakeHuman evaluation complete | Four crowd variants, role pools, gear fit and runtime integration | Repetition remains or external assets break the contract | Unversioned | +| Local map development | Stylized venue geometry and reference maps | OSM/3D data, photoreal references, AI-assisted composition and splat evaluation | Licensing/provenance or performance failure | Unversioned | +| Content and balance | 3 venues with validated 12+ event matrices, recovery events and contextual dialogue | External playtest evidence, balance/fairness pass, event-weight tuning and final content lock | Repetition or unfair outcomes survive into the release candidate | 0.10.0 | +| Dialog/UI | Audited terminology, copy, button states, focus/navigation, modal close, long strings and all 21 screen captures | Keep the capture/compare/judge gate current as content changes | Low; the remaining risk is drift after new UI is added | Complete (0.9.3) | +| Animation/presentation | Procedural pose layers, portrait captures, reduced hem clipping, 8,000/8,000 NPC cap | Thorough NPC silhouette/face/gear/pose/LOD optimization before visual QA | Close-up jank reduces perceived quality | Complete (0.9.4) | +| Audio/accessibility | Procedural ambience/SFX, volume controls, captions/reduce-motion settings, searchable Help | Full accessibility/localization acceptance review, audio caption coverage and P0/P1 fixes | Public release cannot claim accessible play | 0.10.0 | +| Localization | English JSON table, validation and input-generated Help | Pseudo-locale/layout audit and translator workflow sign-off | Text expansion/clipping at release | 0.10.0 | +| Performance/platform | 24-NPC headless budget (6.94 ms), Compatibility/Web/HQ paths | Target hardware matrix, Web/HQ manual profiling, frame-time/memory evidence | Platform-specific drops or startup failures | 0.9.6 / 0.10.0 | +| Save lifecycle | Settings/campaign/history/checkpoint files, atomic writes | Migration fixtures from 0.8/0.9, fresh-install/upgrade verification, rollback instructions | Player progress loss on upgrade | 0.10.0 | +| QA/CI | Headless suite, smokes, screenshot compare, 21/21 judge | Release-candidate smoke matrix, final gallery and release dry run | Regressions escape the release gate | 0.9.6 / 0.10.0 | +| Release/legal | Unsigned desktop/macOS builds, Web/HQ packages | Signing/notarization decision, checksums, AI-asset provenance, credits, privacy/body-camera and rating review | Public release blocked by trust/policy | 0.10.0 | +| Documentation | Architecture/ADR/status/roadmap ownership established | Final README/changelog/status/TODO/smoke-checklist sign-off and known-limitations page | Docs drift at launch | 0.9.6 / 0.10.0 | +| Future 0.x | Stable 0.x feature set | Live replay, more venues, VO/music, image-to-mesh props and seasonal content | Scope creep before release | Unscheduled | + +**Current priority:** the unversioned **3D model re-evaluation** runs first because its findings +gate the crowd-variant roster; **Character development** and **Local map development** follow. +The **0.10.0 release candidate** is the next versioned release; content lock, external playtest, +balance, save migration and release/legal sign-off remain tracked there. The source version is +0.10.0-rc.1; the v0.9.6 release is published. Earlier map/NPC/UI/texture/integration passes are +complete and in `DONE.md`. + ## Milestone 0.10.0 — Release candidate Goal: freeze the feature set, prove it with external players, clear release/legal blockers and verify every distribution path. This remains the next versioned release after the 0.9.x patch -line, but follows the unversioned character and local-map tracks in planning order. +line, but follows the unversioned 3D re-evaluation, character and local-map tracks in planning +order. Only a release-blocking defect from those tracks may enter this milestone before the tag. ### Content lock and external playtest @@ -394,64 +584,6 @@ line, but follows the unversioned character and local-map tracks in planning ord - [ ] Exit: the release candidate is content-locked, externally played, legally reviewed, documented, reproducibly built, and approved as the 0.10.0 release candidate. -## Gap Analysis and 0.x Roadmap - -Baseline: **v0.9.6** (2026-11-03). Three playable venues, tutorial/campaign/checkpoint resume, -difficulty/help, audio/accessibility settings, a 24-NPC budget baseline, a complete -escalation/access/radio loop, shift review, the Blender asset library, 272 headless + 101 Python -tests, a 21/21 clean screen-design judge and an optional Forward+ Desktop HQ build. This is the -baseline; 0.10.0-rc.1 is the current candidate source, with release approvals still open. - -### Documentation audit (completed 2026-11-01) - -- [x] Make `docs/architecture.md` the single architecture source: asset/content pipeline - contracts, runtime venue-switch/fallback flows, deployment/version constraints, quality - requirements, risk register and documentation ownership map. -- [x] Keep command-heavy operational pages separate but subordinate: `docs/asset-tooling.md`, - `docs/blender-assets.md`, `docs/getting-started.md`, `docs/RELEASING.md` and - `docs/smoke-checklist.md` link to architecture rather than acting as parallel sources. -- [x] Remove the obsolete `docs/plan-graphics-v0.6.md` and its links; completed graphics work is - represented by ADR-0013, the asset pipeline section and the changelog. -- [x] Resolve stale claims: README release version/download row, development status - "Forward+ not implemented", and Blender props "not AO-baked". -- [x] Record the documentation ownership rule in `docs/architecture.md` §12: design intent - (`PLAN.md`), mechanics (`gameplay.md`), system architecture/contracts (`architecture.md`), - decisions (ADRs), status (`development-status.md`), roadmap (`TODO.md`), operations - (tooling/release docs). - -### Gap register (remaining roadmap) - -| Area | Current baseline | Remaining gap | Risk | Milestone | -| --- | --- | --- | --- | --- | -| Character development | 8-variant library; source/licence review and Quaternius/MakeHuman evaluation complete | Four crowd variants, role pools, gear fit and runtime integration | Repetition remains or external assets break the contract | Unversioned | -| Local map development | Stylized venue geometry and reference maps | OSM/3D data, photoreal references, AI-assisted composition and splat evaluation | Licensing/provenance or performance failure | Unversioned | -| Content and balance | 3 venues with validated 12+ event matrices, recovery events and contextual dialogue | External playtest evidence, balance/fairness pass, event-weight tuning and final content lock | Repetition or unfair outcomes survive into the release candidate | 0.10.0 | -| Dialog/UI | Audited terminology, copy, button states, focus/navigation, modal close, long strings and all 21 screen captures | Keep the capture/compare/judge gate current as content changes | Low; the remaining risk is drift after new UI is added | Complete (0.9.3) | -| Animation/presentation | Procedural pose layers, portrait captures, reduced hem clipping, 8,000/8,000 NPC cap | Thorough NPC silhouette/face/gear/pose/LOD optimization before visual QA | Close-up jank reduces perceived quality | Complete (0.9.4) | -| Audio/accessibility | Procedural ambience/SFX, volume controls, captions/reduce-motion settings, searchable Help | Full accessibility/localization acceptance review, audio caption coverage and P0/P1 fixes | Public release cannot claim accessible play | 0.10.0 | -| Localization | English JSON table, validation and input-generated Help | Pseudo-locale/layout audit and translator workflow sign-off | Text expansion/clipping at release | 0.10.0 | -| Performance/platform | 24-NPC headless budget (6.94 ms), Compatibility/Web/HQ paths | Target hardware matrix, Web/HQ manual profiling, frame-time/memory evidence | Platform-specific drops or startup failures | 0.9.6 / 0.10.0 | -| Save lifecycle | Settings/campaign/history/checkpoint files, atomic writes | Migration fixtures from 0.8/0.9, fresh-install/upgrade verification, rollback instructions | Player progress loss on upgrade | 0.10.0 | -| QA/CI | Headless suite, smokes, screenshot compare, 21/21 judge | Release-candidate smoke matrix, final gallery and release dry run | Regressions escape the release gate | 0.9.6 / 0.10.0 | -| Release/legal | Unsigned desktop/macOS builds, Web/HQ packages | Signing/notarization decision, checksums, AI-asset provenance, credits, privacy/body-camera and rating review | Public release blocked by trust/policy | 0.10.0 | -| Documentation | Architecture/ADR/status/roadmap ownership established | Final README/changelog/status/TODO/smoke-checklist sign-off and known-limitations page | Docs drift at launch | 0.9.6 / 0.10.0 | -| Future 0.x | Stable 0.x feature set | Live replay, more venues, VO/music, image-to-mesh props and seasonal content | Scope creep before release | Unscheduled | - -**Current priority:** the unversioned **Character development** and **Local map development** -tracks are the active planning order. The **0.10.0 release candidate** follows them in this list -as the next versioned release; content lock, external playtest, balance, save migration and -release/legal sign-off remain tracked there. The source version is 0.10.0-rc.1; the v0.9.6 -release is published. Earlier map/NPC/UI/texture/integration passes are complete and in -`DONE.md`. - -## Future 0.x / non-blocking candidates - -- [ ] Live 3D body-camera replay. -- [ ] Additional venues or seasonal events. -- [ ] Real voice/dialogue audio. -- [ ] Image-to-mesh prop pipeline. -- [ ] Rare easter eggs/cameos (e.g. Bob Dobbs) only after core content and QA are stable. - ## Roadmap dependencies and risks - Content volume is the largest schedule risk; tutorial and campaign work must not outrun the @@ -468,23 +600,18 @@ release is published. Earlier map/NPC/UI/texture/integration passes are complete - Keep the de-escalation-first rules and rare-emergency design unchanged while adding progression, difficulty and feedback. -## Realism follow-ups (deferred) +- The Blender skill pack is local, unversioned guidance; it can drift from the project contract or + assume Blender MCP. Re-verify every adopted technique with `inspect`/`audit`/`fit` and never + make a skill, asset pack or tool version a build or CI dependency. +- The 3D re-evaluation can expand without bound (retopo every head, rig every finger). Cap it with + the scorecard ranking: P0/P1 only, one asset family per commit, and an explicit accept for + everything else. -- [x] Re-run the screen-design judge for `12-joke-shop`, `13-studio-arrival` and the - Forward+ A/B with the valid key: **13/13 match, 0 diff**; the HQ A/B is in the report. -- [ ] Capture a hooded/winter NPC close-up once a scenario spawns types 5-7 (the explicit - `--portrait-type` override is already in `capture_realism.gd`). -- [ ] Human-authored tree/hedge silhouettes: the whole scene now reads well except the foliage, - which is still flat-shaded clumps (`_shrub()`/`_tree()` in `tools/blender_assets.py`). - Only worth doing if a higher-poly organic builder is added to the library. -- [ ] Camera height: the concept frames are shot at ~1.55 m with a slightly wider lens; the game - camera sits at 1.7 m. Decide whether the first-person height should match the art direction - or stay at the current gameplay value. +## Future / deferred (not scheduled) -## Future ideas (optional, not scheduled) - -- [ ] Live 3D body-camera replay (the timeline is text-only today). -- [ ] Additional venues or seasonal events authored from the new `.tres` files. -- [ ] Real voice/dialogue audio (the crowd bed and radio crackle are procedural). +- [ ] Live 3D body-camera replay; the timeline is text-only today. +- [ ] Additional venues or seasonal events authored from the `content/venues/` resources. +- [ ] Real voice/dialogue audio; ambience, cues and radio crackle are procedural. - [ ] Swap the primitive prop builder for an image-to-mesh model API behind the same `assets/models/generated/.glb` contract. +- [ ] Rare easter eggs/cameos (e.g. Bob Dobbs) only after core content and QA are stable. diff --git a/docs/development-status.md b/docs/development-status.md index e715b70..c1697b8 100644 --- a/docs/development-status.md +++ b/docs/development-status.md @@ -1,8 +1,10 @@ # Development Status -Current planning priorities are the unversioned **Character development** and **Local map -development** tracks in [`TODO.md`](../TODO.md); neither is part of the implemented list below -yet. The 0.10.0 release candidate remains the next versioned release. +Current planning priorities are the unversioned **3D model re-evaluation**, **Character +development** and **Local map development** tracks in [`TODO.md`](../TODO.md); none is part of the +implemented list below yet. The re-evaluation scores the existing characters, gear, props and +venues against the locally installed Blender skill guidance before the roster expands. The 0.10.0 +release candidate remains the next versioned release. Implemented so far: @@ -48,7 +50,8 @@ Implemented so far: - NPC torso/hip transition (0.9.4 work): the pelvis and chest are slightly wider than the waist, giving shirts and jackets a readable taper into the hips without changing the build multipliers or the skeleton. The comparison is `sheet_npc_baseline_compare-torso.jpg`. - Release v0.9.6 (2026-11-03): the tagged commit `4bb2896` passed Gitea Actions run 1296 (checks + full build) and published seven artifacts (Linux, Windows, macOS, NSIS setup, AppImage, Web and Desktop HQ). Release page: . - Release candidate (0.10.0-rc.1, 2026-11-03): clean worktree `a9658ec` built Linux 161.5 MB, Windows 197.2 MB, macOS 148.0 MB, Web 97.8 MB and Desktop HQ 241.6 MB. The Web/HQ archives contain `CREDITS.md`, `PRIVACY.md`, `docs/accessibility.md` and `docs/known-limitations.md`; SHA-256 checksums were generated, the Linux and HQ binaries launched headless, and the Web index/wasm/pck/docs served with HTTP 200. The candidate is not published: external playtest, AI-provider/legal approval, macOS signing and the Windows/macOS target matrix remain open blockers. -- Save migration and reliability (0.10.0 work): committed 0.8-era settings/campaign/history fixtures and a 0.9.0 checkpoint. The loader default-fills old settings, keeps campaign progress and validates checkpoints for all three venues with an open incident, NPC rows, door, flashlight and body-camera state. Corrupt and partial files fall back to defaults; a blocked atomic replace leaves the prior valid file intact. `_load_json` uses the non-logging JSON parser; save locations and rollback are documented in `getting-started.md`. Suite is 272/272. +- Save migration and reliability (0.10.0 work): committed 0.8-era settings/campaign/history fixtures and a 0.9.0 checkpoint. The loader default-fills old settings, keeps campaign progress and validates checkpoints for all three venues with an open incident, NPC rows, door, flashlight and body-camera state. Corrupt and partial files fall back to defaults; a blocked atomic replace leaves the prior valid file intact. `_load_json` uses the non-logging JSON parser; save locations and rollback are documented in `getting-started.md`. Suite is 272/272; +Python tooling is 108/108 after the GLB `inspect` intake coverage. - Integration checkpoint (0.9.6 work): the clean worktree at `f5b8ef2` rebuilt all five release packages and the Desktop HQ zip without ignored `tmp/`/`build/` content (Linux 161.5 MB, Windows 197.1 MB, macOS 148.0 MB, Web 97.8 MB, HQ 241.5 MB). The Web zip contains `index.html`, `index.wasm` and `index.pck`; the HQ zip contains `override.cfg` and launches headless with the Forward+ override. Current verification: Godot 263/263, Python 101/101, 14 smokes green, 24-NPC budget 6.90 ms / 168 meshes / 131,616 triangles, gallery 21 good / 0 bad, screen judge 21/21 match with 0 review/diff, and a pinned realism judge (`z-ai/glm-5.3-flash`, one pass per shot) at mean overall 2.1 and Pillow gap 0.291. No new gameplay or content changes. - Release v0.9.5 (2026-11-02): the tagged commit `4bc6390` passed Gitea Actions run 922 (checks + full build) and published seven artifacts (Linux, Windows, macOS, NSIS setup, AppImage, Web and Desktop HQ). Release page: . - Release v0.9.4 (2026-11-02): the tagged commit `a57b86c` passed the Gitea checks and full build and published seven artifacts (Linux, Windows, macOS, NSIS setup, AppImage, Web and Desktop HQ). Release page: . @@ -66,7 +69,8 @@ Implemented so far: - NPC P1 portrait fixes (0.9.4 work): tourists now hide their photo-pose camera bag outside `photo`/`film` poses, removing the duplicate-backpack silhouette; the backpack gear was rebuilt with flattened, forward chest straps and a fresh AO map. The before/after sheet is [`blender_previews/sheet_npc_baseline_compare-p1.jpg`](blender_previews/sheet_npc_baseline_compare-p1.jpg); the remaining face/hand work was closed under the 0.9.4 acceptance limits. - NPC visual baseline (0.9.4 work): `src/test/capture_npc_baseline.gd` captures all eight library characters from front, three-quarter, profile, back, full-body and crowd views in a neutral studio (48 frames). The criteria, measurements and ranked gaps are in [`npc-visual-review.md`](npc-visual-review.md); the committed sheet is [`blender_previews/sheet_npc_baseline.jpg`](blender_previews/sheet_npc_baseline.jpg). No model changes were made in this baseline step. - UI-state capture pass (0.9.3 work): `src/test/capture_ui_states.gd` adds committed captures 14–21 for the start menu, pause, settings, shift review, emergency radio, action wheel, crowd panic and responder arrival. Every one of the 21 catalogue entries now has a current-build capture; `tools/check_screenshots.sh` reports 21 good / 0 bad and the automatic judge reports 21/21 match, 0 diff. Crowd panic and responder arrival are staged presentation frames, not gameplay changes. -- Realism adoption (post-v0.6.0): v2 per-phase skylines and surface tiles with normal maps, retuned sun/exposure/fog, wet asphalt, denser foliage, a visible additive flashlight beam, and refreshed staging captures. `tools/check_screenshots.sh` is the repeatable capture/compare gate; judge is clean of `diff` verdicts. +- Realism adoption (post-v0.6.0): v2 per-phase skylines and surface tiles with normal maps, retuned sun/exposure/fog, wet asphalt, denser foliage, a tight additive flashlight spot with no beam geometry, and refreshed +staging captures. `tools/check_screenshots.sh` is the repeatable capture/compare gate; judge is clean of `diff` verdicts. - Input/reliability fixes: selecting a venue releases the start-menu input lock and recaptures the mouse; the body-camera overlay no longer covers the shift status. Mouse look now reads at `_input`, restores capture on window focus/click-back, and the HUD is mouse-transparent. Normal radio reports submit on click; emergency calls still require the hold-to-confirm path. - Production-quality pass (v0.9.0): mixer/accessibility settings, audio volume clamping, 24-NPC budget smoke, shortened coat/dress stride, and a unified Godot 4.7.2 CI/local support baseline with documented upgrade/rollback requirements. - Campaign and first-hour pass (v0.8.0): campaign progression, checkpoint resume, difficulty presets, a searchable Help overlay, recovery events, contextual dialogue, policy/debrief lines and tutorial/replay/skip. Scripted QA bypasses the tutorial unless `--tutorial` is passed.