From 6c367e8c7e9eca4a32e7921b5f1f4b408a53bcef Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Sun, 1 Nov 2026 20:04:47 +0100 Subject: [PATCH] Consolidate architecture docs and add the v1.0.0 roadmap Make architecture the canonical system/data-flow source, add explicit documentation ownership and consolidation rules, and mark the old graphics plan historical. Fix stale README/status/Blender/release claims. Add a full gap register and milestone roadmap from v0.8 through v1.0.0, including onboarding, content depth, accessibility/localization, performance, release/legal blockers and non-blocking future ideas. --- MEMORY.md | 1 + PLAN.md | 4 +- README.md | 25 +++---- TODO.md | 130 +++++++++++++++++++++++++++++++++++++ docs/RELEASING.md | 7 +- docs/architecture.md | 93 ++++++++++++++++++++++++-- docs/asset-tooling.md | 6 +- docs/blender-assets.md | 11 ++-- docs/development-status.md | 2 +- docs/plan-graphics-v0.6.md | 13 ++-- 10 files changed, 261 insertions(+), 31 deletions(-) diff --git a/MEMORY.md b/MEMORY.md index cf95a3c..3e4391b 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -44,6 +44,7 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o - Shift length is the scenario's `shift_duration_s` (900 s in all three venues). Tests and the screenshot tool override elapsed time; they do not change the default. - RNG: NPC reactions and event scheduling are seedable for deterministic tests. +- **Documentation ownership (2026-11-01):** `docs/architecture.md` §12 now defines the source-of-truth map and consolidation rules. `docs/plan-graphics-v0.6.md` is historical; current work belongs in `TODO.md`. README/development-status/Blender AO/Forward+ stale claims were corrected. The v1.0.0 gap register and 0.8/0.9/0.9.5/1.0 roadmap live in `TODO.md`. - **Vision judge (v0.7.2):** `tools/openrouter_judge.py` reads `/api/v1/models`, filters image-input models with `response_format`, and ranks by advertised prompt/image/completion prices. `--model auto` (default) uses the cheapest (`z-ai/glm-5.3-flash` on 2026-11-01) with fallbacks; explicit `--model`/`GIG_LINE_JUDGE_MODEL` wins. Auth errors abort, provider/model errors fall through. Full screen judge 13/13 match, 0 diff; A/B judge ~$0.006. - **Desktop HQ preset (v0.7.1):** `packaging/desktop_hq/override.cfg` switches a copied executable to Forward+; `Materials.forward_plus_active()` gates diff --git a/PLAN.md b/PLAN.md index 77fcd5f..f850d22 100644 --- a/PLAN.md +++ b/PLAN.md @@ -153,13 +153,13 @@ The visual direction is readable stylized realism: - **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. -Remaining visual work is tracked in `TODO.md` (NPC fidelity and the two venue stages), not in this plan. +The path from the current vertical slice to v1.0.0 — content depth, onboarding, accessibility, platform QA and release readiness — is tracked in [`TODO.md`](TODO.md); this plan stays at the product/design level. Primary decisions: [ADR-0007](docs/adr/0007-locomotion-and-input-layers.md), [ADR-0008](docs/adr/0008-cone-focus-and-head-ring.md), [ADR-0009](docs/adr/0009-radial-action-menu.md), [ADR-0010](docs/adr/0010-procedural-npc-presentation.md), [ADR-0011](docs/adr/0011-aim-free-selection-and-precision-walk.md), [ADR-0012](docs/adr/0012-surface-materials-and-generated-props.md), [ADR-0013](docs/adr/0013-blender-authored-npc-characters.md). ## Tech Stack -- **Engine:** Godot 4.3, GL Compatibility renderer (Web parity). +- **Engine:** Godot 4.3 baseline (local dev verified with 4.7.2), GL Compatibility renderer (Web parity); optional Forward+ Desktop HQ build. - **Language:** GDScript. - **Architecture:** venue-driven simulation; shared systems plus `Resource`-based scenario data. - **Navigation:** `NavigationRegion3D` / `NavigationAgent3D`. diff --git a/README.md b/README.md index 55ee096..ceffd9f 100644 --- a/README.md +++ b/README.md @@ -31,15 +31,16 @@ precision walk, the Joke Shop alley, the TV Studio arrival, and the prop lineup. | **Linux — portable** | [`gig-line-linux-.x86_64`](https://git.allucanget.biz/zwitschi/security-game/releases) · 64-bit, `chmod +x` and run | | **macOS** | [`gig-line-macos-.zip`](https://git.allucanget.biz/zwitschi/security-game/releases) · unsigned build, quarantine note below | | **Web (browser)** | [`gig-line-web-.zip`](https://git.allucanget.biz/zwitschi/security-game/releases) · unzip and serve the folder from any static host (no special headers) | +| **Desktop HQ** | [`gig-line-desktop-hq-.zip`](https://git.allucanget.biz/zwitschi/security-game/releases) · optional Forward+ build with volumetric fog/SDFGI/flashlight; requires a Vulkan-capable GPU/driver | **All releases:** > Downloads are public (no sign-in required) since the host's instance-wide > `REQUIRE_SIGNIN_VIEW` was disabled on 2026-10-31. > -> **Latest: v0.7.0** — distinct Joke Shop and TV Studio geometry, fitted NPC gear, -> and the post-v0.6.0 realism/visual-alignment work (v2 skylines/textures, UI mockup -> art, flashlight beam, HUD fixes). +> **Latest: v0.7.2** — a cost-aware OpenRouter screenshot judge, an optional +> Forward+ Desktop HQ build with volumetric fog/SDFGI/flashlight, distinct Joke +> Shop and TV Studio geometry, and fitted NPC gear. > Releases are built automatically when a `vX.Y.Z` tag is pushed > (see [`docs/RELEASING.md`](docs/RELEASING.md)); manual builds use > `./tools/build_releases.sh`. Installer/AppImage packaging runs in the same pipeline @@ -74,7 +75,7 @@ decisions are recorded as ADRs in [`docs/adr/`](docs/adr/). ## Tech Stack -- **Engine:** Godot 4.x · **Language:** GDScript +- **Engine:** Godot 4.3 baseline (local dev verified with 4.7.2) · **Language:** GDScript - **NPCs:** Blender-authored skinned library (`assets/models/blender/`) with procedural fallbacks; lightweight FSMs on `NpcProfile` - **World:** procedural `WorldBuilder` + generated prop models - **Art:** v2 skyline/surface textures in `assets/textures/ai/game_ready/v2/picks/`; UI/scene art in `assets/images/` @@ -102,7 +103,6 @@ Full setup, every run/test/smoke command, and the controls table are in - [`PLAN.md`](PLAN.md) — Game design plan and scenario details. - [`AGENTS.md`](AGENTS.md) — Development and collaboration workflow. -- [`TODO.md`](TODO.md) — Active checkbox task list. - [`DONE.md`](DONE.md) — Completed task sections. - [`MEMORY.md`](MEMORY.md) — Persistent session notes. - [`CHANGELOG.md`](CHANGELOG.md) — User-facing changes by version. @@ -114,16 +114,17 @@ Full setup, every run/test/smoke command, and the controls table are in - [`docs/smoke-checklist.md`](docs/smoke-checklist.md) — Manual smoke-test checklist. - [`docs/blender-assets.md`](docs/blender-assets.md) — Blender asset library: characters, gear, props, attach points. - [`docs/adr/`](docs/adr/) — Architecture Decision Records. -- [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md) — Graphics-quality plan: Blender-authored NPC characters. +- [`TODO.md`](TODO.md) — Active tasks plus the v1.0.0 gap analysis and milestone roadmap. +- [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md) — Historical v0.6 graphics program (completed). ## Development Status -v0.7.0 shipped distinct venue geometry: the Joke Shop alley and TV Studio -entrance no longer share the Hollywood layout. It builds on v0.6.1's fitted NPC -gear and v0.6.0's Blender asset library, baked AO and environment lift. See -[`docs/development-status.md`](docs/development-status.md) for the full -implemented list and [`TODO.md`](TODO.md) for what's next. Manual verification -uses the [`docs/smoke-checklist.md`](docs/smoke-checklist.md). +v0.7.2 ships the cost-aware OpenRouter judge and the optional Desktop HQ build. +The three venues now have distinct geometry, fitted NPC gear, the Blender asset +library and the post-v0.6.0 realism pass. See +[`docs/development-status.md`](docs/development-status.md) for the implemented +list, and [`TODO.md`](TODO.md) for the v1.0.0 gap analysis and roadmap. Manual +verification uses the [`docs/smoke-checklist.md`](docs/smoke-checklist.md). ## Development Workflow diff --git a/TODO.md b/TODO.md index 12ef742..f283c4c 100644 --- a/TODO.md +++ b/TODO.md @@ -3,6 +3,136 @@ 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. +## Gap Analysis and v1.0.0 Roadmap + +Baseline: **v0.7.2** (2026-11-01). Three playable venues, a complete escalation/access/radio +loop, shift review, Blender character/gear/prop library, 231 headless + 94 Python tests, a +13/13 clean screen-design judge and an optional Forward+ Desktop HQ build. This baseline is a +strong vertical slice, not yet a 1.0 product. + +### Documentation audit (completed 2026-11-01) + +- [x] Make `docs/architecture.md` the single architecture source: added the asset/content + pipeline contracts, runtime venue-switch/fallback flows, deployment/version constraints, + quality requirements, risk register and a 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` now link to architecture rather than acting as parallel sources. +- [x] Mark `docs/plan-graphics-v0.6.md` as completed/historical; current graphics work belongs in + this roadmap. +- [x] Resolve stale claims: README release version/download row, development status + "Forward+ not implemented", Blender props "not AO-baked", and historical plan status. +- [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 + +| Area | Current baseline | Gap to 1.0 | Risk | Milestone | +| --- | --- | --- | --- | --- | +| First-hour experience | Venue menu and controls exist; no tutorial | No guided first shift, control coaching, objective recap or "what went wrong" debrief | New players bounce before the de-escalation loop lands | 0.8 | +| Campaign/progression | Venue selection and debug cycle | No career/venue order, unlocks, difficulty curve or persistent player progression | Shift loop feels like a tech demo rather than a game | 0.8 | +| Authored content | 3 venues, small event pools, one-line dialogue | Need a larger event matrix per venue, repeat/remix rules, failure/recovery events and more NPC dialogue | Repetition after a few shifts | 0.8 | +| NPC behavior | FSM intents, reactions, crowd/theater poses | Deeper negotiation, memory of earlier interactions, group dynamics, believable refusal/escalation edges | NPCs still feel deterministic/scripted | 0.8 | +| Access/evaluation | Recognition, wristbands/IDs/tickets/credentials, reputation/review | Fairness tuning, ambiguous cases, clearer evidence trail, richer grades and actionable feedback | Players cannot learn why a decision scored poorly | 0.8 | +| Shift lifecycle | Settings + completed-shift history persist | No mid-shift save/resume, pause-safe serialization, versioned save schema or replay | Interrupted sessions lose the run; future changes can break saves | 0.8 | +| Accessibility | Key remapping, gamepad, HUD font scale, shape escalation cue | Subtitles/captions, colour-independent cues, motion/audio sensitivity, text expansion, menu narration and full input alternatives need an audit | Public 1.0 cannot claim accessible play | 0.8–0.9 | +| Localization | English strings in `content/strings.en.json` | String extraction/coverage, pseudo-locale test, font fallback, text-length layout budgets and translator workflow | Text bugs and unsupported locales at release | 0.9 | +| Audio | Procedural crowd bed and radio crackle | Music/ambience direction, event SFX, voice/VO decision, caption hooks and mix budgets | Scene can feel silent/placeholder | 0.9 | +| Animation/presentation | Procedural poses, walk/idle theater, LOD impostor | More reaction/idle/negotiation poses, transitions, facial readability at portrait distance, camera-height decision | Cinematic close-ups expose the prototype layer | 0.9 | +| Performance/platform | 16-NPC budget measured headlessly; Compatibility default; optional Vulkan HQ | Target hardware matrix, 24-NPC profiling, draw-call/memory budgets, Web/HQ parity and frame-time regression gates | Crowded studio or Web drops frames | 0.9 | +| Content tooling | ScenarioFactory/.tres export, Blender manifest, asset audits | Schema validation, previews, event authoring workflow, reproducible asset rebuild notes and contributor onboarding | Content expansion becomes expensive/error-prone | 0.8–0.9 | +| QA/CI | Headless suite, smokes, screenshot compare, model-aware judge | End-to-end shift automation, full venue matrix, CI Godot-version strategy, manual judge budget and release checklist automation | Regressions escape or CI becomes non-reproducible | 0.9 | +| Release/legal | Tag-driven unsigned builds, Web zip, optional HQ | Signing/notarization, checksums, AI-asset provenance/licensing, credits, privacy/body-camera statement and storefront requirements | Public release blocked by trust/policy issues | 0.9.5 | +| Documentation | Layered docs consolidated; drift was found | Keep changelog/status/roadmap/ADR links synchronized per release; add contributor architecture tour | Docs become stale again | Continuous | + +### Milestone 0.8.0 — First hour and content depth + +- [ ] Add a skippable first-shift tutorial: movement/look, focus, action wheel, access check, + warning, body camera, radio and shift review; teach by doing, not a wall of text. +- [ ] Add a persistent campaign shell: venue order/unlocks, selected difficulty, shift summaries + and a clear "next shift" path. Keep debug venue cycling separate. +- [ ] Add an objective/recap layer: current venue policy, shift phase and a post-incident recap of + what evidence was checked and why the outcome was judged fair/unfair. +- [ ] Define a content matrix for each venue (routine, scripted, edge, recovery and rare-threat + events) and fill the largest holes; target meaningful variety across all four phases. +- [ ] Expand NPC dialogue beyond one-line intent replies: refusal reasons, de-escalation responses, + recognition callbacks and group reactions, all localized and deterministic under seed. +- [ ] Add mid-shift save/resume with a versioned schema and migration test; keep completed-shift + history and settings compatible. +- [ ] Add difficulty/pacing options (spawn rate, tolerance, report strictness) without changing the + de-escalation-first rules; expose them in Settings with defaults matching the current build. +- [ ] Add a new-player help overlay and a searchable controls reference distinct from the HUD legend. +- [ ] Exit: a new player can complete a first shift without the README; each venue has enough + content for repeated shifts; save/resume survives restart; 0.8 test matrix is green. + +### Milestone 0.9.0 — Production quality and platform readiness + +- [ ] Animation/presentation pass: negotiation/reaction poses and transitions, readable faces in + portrait, resolved camera height, and no coat/skirt leg clipping in normal movement. +- [ ] Audio pass: music/ambience direction, event SFX, radio/crowd mix, caption hooks and a VO + decision with production scope. +- [ ] Localization pass: all player-facing strings externalized, pseudo-locale layout test, font + fallback and a contributor translation workflow. +- [ ] Accessibility pass: subtitles/captions, colour-independent access/escalation cues, motion + and flash options, full keyboard/gamepad parity and documented assist options. +- [ ] Performance pass: profile 24 live NPCs, all venues, Web and Desktop HQ; record frame-time, + draw-call and memory budgets; add regression checks where automation is possible. +- [ ] QA pass: automated end-to-end shift for each venue, full smoke matrix, screenshot/judge + baselines, and a documented manual judge budget/model pin. +- [ ] Resolve the Godot baseline: choose one supported version (or an explicit 4.3-CI/4.7-local + matrix), align export templates and visual smoke results, and document the policy. +- [ ] Exit: production content is feature-complete, accessibility/localization acceptance criteria + pass, target hardware matrix is measured, and no P0/P1 defect remains open. + +### Milestone 0.9.5 — Release candidate + +- [ ] Content lock and external playtest round (at least five first-time players); triage findings + by severity and fix all P0/P1 issues. +- [ ] Balance and fairness pass across all venues: scoring, difficulty, event weights, NPC + compliance and emergency false-positive/negative rates. +- [ ] Save migration test from 0.8/0.9 saves; verify settings, shift history and resume paths. +- [ ] Release engineering: signed/notarized macOS where possible, checksums, Windows/Linux install + smoke tests, AppImage update, Web hosting verification and Desktop HQ Vulkan fallback. +- [ ] Legal/credits review: AI-assisted asset provenance, music/SFX licenses, privacy/body-camera + language, age/content rating and storefront requirements. +- [ ] Documentation sign-off: architecture/ADR/status/TODO/changelog/README/smoke checklist all + match the release candidate; capture final gallery and run compare + judge. +- [ ] Exit: release candidate passes the manual smoke checklist on every target; no release-blocking + legal or platform issue remains. + +### Milestone 1.0.0 — Launch + +- [ ] Freeze content and version, run full final QA on Windows/Linux/macOS/Web/Desktop HQ, and + verify fresh installs plus upgrade paths. +- [ ] Publish store/release notes, credits, known limitations, accessibility statement and + controls; verify every download link and artifact checksum. +- [ ] Tag `v1.0.0`, publish through CI, verify the release page and post-launch patch policy. +- [ ] Definition of 1.0: three complete venues with campaign/tutorial, stable save/resume, + accessibility/localization acceptance, measured performance on the target matrix, signed + release artifacts where platform rules require it, and documentation synchronized with the + build. + +### Explicit post-1.0 / 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 + event/dialogue matrix. +- The vision judge is a dev-time aid with an external key/budget; CI must never make it a hard gate. +- Godot version changes can alter lighting/imports; do not combine an engine baseline move with a + content/feature milestone. +- Signed macOS builds and legal/AI provenance are release blockers, not polish. +- Keep the de-escalation-first rules and rare-emergency design unchanged while adding progression, + difficulty and feedback. + ## Realism follow-ups (deferred) - [x] Re-run the screen-design judge for `12-joke-shop`, `13-studio-arrival` and the diff --git a/docs/RELEASING.md b/docs/RELEASING.md index f7c5003..543f58e 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -127,14 +127,15 @@ published the release, re-running the script only adds missing assets. > **Host note**: the release is fully built by CI, but anonymous users can only > browse and download when the instance sets `[service] REQUIRE_SIGNIN_VIEW=false` -> in `app.ini` (the repo itself is public). See the TODO for the exact steps. +> in `app.ini` (the repo itself is public). This is a host-admin setting, not a +> repository file. Manual alternative: ### Via the web UI 1. Create a **New Release** with tag `v`. -2. Attach all three `build/` artifacts. +2. Attach all artifacts from `build/` (portables, installer/AppImage, Web and optional Desktop HQ). 3. Write release notes (see checklist below). ### Via the API @@ -171,7 +172,7 @@ change, update `tools/build_releases.sh` first. - [ ] All headless tests pass (exit code 0). - [ ] Game boots cleanly in a smoke test. -- [ ] Controls documented in `README.md` match the build. +- [ ] Controls documented in `docs/getting-started.md` match the build. - [ ] Version in `project.godot` matches the tag. - [ ] Export templates used are the official ones for the pinned engine. - [ ] Artifacts uploaded; README downloads page shows them. diff --git a/docs/architecture.md b/docs/architecture.md index 478fc40..242fb35 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -25,7 +25,7 @@ This document follows the structure of the arc42 architecture documentation temp ## 2. Constraints - The first implementation should be small enough for a playable vertical slice. -- The engine is Godot 4 with GDScript; a playable prototype vertical slice is implemented. +- The engine is Godot 4 with GDScript; a playable prototype vertical slice is implemented. CI pins Godot 4.3 while local development is verified with 4.7.2; the default renderer stays GL Compatibility for Web parity, with an optional Forward+ Desktop HQ build. - Venue-specific policies must be configurable rather than hard-coded into individual NPCs. - The game must preserve the de-escalation-first design described in [`PLAN.md`](../PLAN.md). - The project uses the repository workflow described in [`AGENTS.md`](../AGENTS.md). @@ -83,7 +83,7 @@ The player interacts with NPCs, venue entrances, access artifacts, equipment, st - `tools/model_pipeline.py` builds and audits the street-prop `.glb` models and packs their colour atlases. - `tools/npc_pipeline.py` builds and audits the skinned NPC base model (`assets/models/generated/npc_base.glb`) and its per-slot material maps, with an optional AI fabric override (ADR-0013). - `tools/blender_assets.py` builds, renders and audits the Blender asset library (`assets/models/blender/{npc,npc_gear,props}/` + `manifest.json`): NPC character variants that are drop-in for `npc_base`, attach-point gear, and street/venue props. `NpcAvatar` selects variants/gear by role/seed and `WorldBuilder` loads the prop replacements and new street dressing, with procedural fallbacks (see `docs/blender-assets.md`). -- `tools/scene_concepts.py` generates realism-pass references (`docs/screens/concepts/`), skyline backdrops and surface tiles (raw `assets/textures/ai/v2/raw/` → candidates `assets/textures/ai/game_ready/v2/`), promotes the validated ones to the tracked `v2/picks/` that `SurfaceMaterials`/`WorldBuilder` preload, audits them, and scores `src/test/capture_realism.gd` A/B captures (five stages, runtime texture swaps) against the concepts (`docs/screens/realism//`). +- `tools/scene_concepts.py` generates realism-pass references (`docs/screens/concepts/`), skyline backdrops and surface tiles (raw `assets/textures/ai/v2/raw/` → candidates `assets/textures/ai/game_ready/v2/`), promotes the validated ones to the tracked `v2/picks/` that `SurfaceMaterials`/`WorldBuilder` preload, audits them, and scores `src/test/capture_realism.gd` A/B captures (six stages, runtime texture swaps) against the concepts (`docs/screens/realism//`). - `tools/asset_pipeline.py` generates and audits role-aware textures; `tools/screen_designs.py` generates screen references and judges captures; `tools/check_screenshots.sh` renders the staged gallery and runs the compare gate. Confirmed game assets live in `assets/textures/ai/game_ready/` (audited surface, UI, and card textures), `assets/models/generated/` (prop and NPC `.glb` models plus their texture atlases), and `assets/textures/npc/` (NPC material maps and `palette.json`). Development-only outputs — AI concept sheets, Blender sources, raw AI fabrics — are gitignored and regenerated by the tools. @@ -106,6 +106,36 @@ When reference art becomes runtime art, copy or process it into `assets/images/` new descriptive name (never overwrite an existing image) and keep a procedural fallback in code. +### Content and asset pipeline architecture + +The asset/content pipeline is part of the architecture, not an external build detail: + +| Stage | Producer | Committed artifact | Runtime consumer | Failure fallback | +| --- | --- | --- | --- | --- | +| Scenario data | `ScenarioFactory` / editor export | `content/venues/*.tres`, event/profile data | `VenueScenario` → `ShiftCoordinator` | built-in scenario defaults | +| NPC library | Blender flatpak + `tools/blender_assets.py` | `assets/models/blender/npc/*.glb`, manifest, baked AO | `NpcAvatar` | `npc_base.glb` → procedural rig | +| Gear/props | Blender flatpak + tool + bake | `npc_gear/*.glb`, `props/*.glb`, `*_ao.png` | `NpcAvatar`, `WorldBuilder` | primitive assets / generated props | +| Surface/UI art | Python pipelines / AI-assisted references | `assets/textures/ai/game_ready/`, `assets/images/` | `SurfaceMaterials`, `UiArt` | neutral material / procedural UI | +| Screenshots/QA | capture scripts + `scene_concepts`/`screen_designs` | `docs/screenshots/`, `docs/screens/realism/` | reviewers and CI gates | regenerate; never runtime input | +| Release | Gitea workflow + build/publish scripts | platform binaries, Web zip, Desktop HQ zip | players | source build | + +Contracts that keep the pipeline replaceable: + +- `npc_base` armature/bone names, five tint slots and front direction are frozen by tests; gear is authored in attach-point space and measured against the character silhouette. +- Library characters, gear and props are audited for grounding, UVs, triangle budgets, degenerate triangles and manifest coverage; Blender is a developer tool, never a CI runtime dependency. +- `WorldBuilder.VENUE_SPECS` drives geometry, navigation, features and prop placements; `GameManager` rebuilds only the world container on a venue change. +- 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. + +### Content authoring and runtime data flow + +`ScenarioFactory` is the source of truth for the three authored venues. `tools/export_venues.gd` +writes `content/venues/.tres` for editor inspection; the factory remains the canonical +scenario definition. At runtime `GameManager` selects a `VenueScenario`, `ShiftCoordinator` +schedules events and phases, and `NPCController`/`AccessVerifier`/`EscalationManager` produce +incidents. `IncidentRecorder` is the authoritative event history; body-camera review, +reputation, crowd reaction and shift review read it rather than resolving gameplay separately. + ## 6. Runtime View ### Routine interaction @@ -118,6 +148,19 @@ in code. 6. The incident recorder stores the interaction. 7. Reputation and crowd systems react to the outcome. +### Venue switch + +1. The player selects a venue from the start menu or cycles with the debug shortcut. +2. `GameManager` loads the matching `VenueScenario` and keeps the guard/UI state. +3. `WorldBuilder` rebuilds only `world_root` from `VENUE_SPECS`, including geometry, props and the navigation mesh. +4. Shift state, NPCs and incidents are reset for the new venue; phase lighting and the door state are reapplied. + +### Asset fallback + +1. A runtime loader asks for the library scene or texture. +2. If the imported asset is missing, the loader uses the generated/procedural fallback rather than failing the boot. +3. Contracts and audits ensure the fallback and library paths expose the same observable behaviour; CI runs headless against whichever path is available. + ### Access check 1. The player stops or receives an approaching person. @@ -137,7 +180,7 @@ in code. ## 7. Deployment View -The game is a single-player local client containing presentation, simulation, rules, content, and persistence for local settings and shift results. No online backend is required. A non-threaded Web export ships alongside the desktop builds and can be served from any static host without special headers. +The game is a single-player local client containing presentation, simulation, rules, content, and persistence for local settings and shift results. No online backend is required. A non-threaded Web export ships alongside the desktop builds and can be served from any static host without special headers. The default renderer is GL Compatibility; an optional Desktop HQ zip uses Forward+ with volumetric fog/SDFGI on Vulkan-capable desktops. CI pins Godot 4.3 while local development is verified with 4.7.2, so the light falloff path is version-adaptive until the baseline is unified. Future options include external analytics, cloud saves, or replay sharing, but they are not part of the current architecture. @@ -173,6 +216,8 @@ The release process is: bump the version, run the full test suite and `tools/che - **Localization:** Dialogue and prompts should be externalized from logic. - **Observability:** Debug overlays show NPC intent, access status, escalation level, active incidents, and response timers during development. - **Visual regression:** Staged captures are compared against the runtime reference art (`screen_designs.py compare`) and optionally judged by a vision model; `tools/check_screenshots.sh` makes the pass repeatable. +- **Asset provenance and AI usage:** AI-assisted images/concepts are development inputs only; validated outputs are committed, audited and loaded through the same runtime asset contracts. Generated content must not become an offline/CI dependency. +- **Documentation ownership:** `PLAN.md` owns design intent; `docs/gameplay.md` owns playable mechanics; `docs/architecture.md` owns system boundaries, data flow, constraints and cross-cutting decisions; ADRs own decision history; `docs/development-status.md` owns the implemented/gap list; `TODO.md` owns the roadmap; `MEMORY.md` owns gotchas and open questions. Specialized docs link to these rather than becoming competing sources of truth. ## 9. Architecture Decisions @@ -203,6 +248,9 @@ Architecture decisions are recorded as ADRs: | Performance | The target venue should support a believable crowd without harming input or simulation responsiveness. | | Testability | Access and escalation rules can be tested independently of presentation. | | Accessibility | Core actions are available through clear input alternatives and readable feedback. | +| Reliability | A fresh checkout, missing optional asset, invalid AI key, or unavailable Forward+ renderer must not prevent a normal Compatibility/Web/headless boot. | +| Performance | A busy venue should hold its budget at the target NPC cap on desktop and Web; the current 16-NPC check is a baseline, not a 1.0 guarantee. | +| Documentation integrity | Every released version has a changelog entry, current status/roadmap, and architecture/ADR references that match the build. | ## 11. Risks and Technical Debt @@ -213,8 +261,45 @@ Architecture decisions are recorded as ADRs: - Mental-health-crisis scenarios require careful writing, playtesting, and respectful presentation. - The choice of engine may affect navigation, crowd scale, tooling, and content authoring. - Reference mockups can outpace the runtime art style; compare/judge catch gross drift but not composition errors, so the staged gallery needs human review after large visual changes. +- Godot version skew (CI 4.3 vs local 4.7.2) can change lighting, import sidecars and generated UIDs; a single supported version and a visual smoke matrix are required before 1.0. +- Content volume and authoring tools are still thin; adding venues/events by editing the factory can become error-prone without schema validation and preview tooling. +- Save data currently covers settings and shift history, not mid-shift resume; adding saves/replays requires a versioned schema and migration policy. +- The optional judge and image-generation paths depend on an external key, model availability and budget; CI cannot make them a release gate, and keys must never be committed. +- Accessibility and localization coverage is partial; a 1.0 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 1.0. +- Documentation drift has already occurred (release version, implemented status, historical graphics plan); the ownership map and roadmap must be kept current in the same change as the implementation. -## 12. Glossary +## 12. Documentation Consolidation and Ownership + +The documentation set is intentionally layered. Architecture-level material is consolidated here; +specialized operational detail remains in focused pages so commands do not rot inside the +architecture document. + +| Document | Canonical role | Relationship to this architecture | +| --- | --- | --- | +| [`PLAN.md`](../PLAN.md) | Product/design intent, pillars, venues and success criteria | Design source; architecture realizes it | +| [`docs/gameplay.md`](gameplay.md) | Playable loop, escalation, venue mechanics | Runtime/behavioral view | +| [`docs/architecture.md`](architecture.md) | System boundaries, data flow, constraints, deployment, cross-cutting decisions, quality risks | Single architecture source | +| [`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/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 | +| [`docs/development-status.md`](development-status.md) | Implemented features and current gaps | Status companion to the roadmap | +| [`TODO.md`](../TODO.md) | Active tasks and v1.0.0 roadmap | Planning source; no architecture duplication | +| [`docs/plan-graphics-v0.6.md`](plan-graphics-v0.6.md) | Historical v0.6 graphics program (completed) | Historical context; superseded by ADR-0013 and this document | +| [`CHANGELOG.md`](../CHANGELOG.md) | User-facing release history | Release/version companion | + +Consolidation decisions: + +- **Architecture owns the "how"** (components, contracts, data flow, constraints, quality gates); **PLAN/gameplay own the "what"**; **ADRs own the "why"**. Links replace duplicated prose. +- **Asset and release documents remain separate** because they are command-heavy operational procedures; their architecture-relevant contracts and failure modes are summarized in §5 and §7. +- **`plan-graphics-v0.6.md` is historical, not a current plan.** The completed work is represented by ADR-0013, the asset pipeline section and the v0.6.0 changelog; new graphics work belongs in TODO, not a revived phase plan. +- **Status and roadmap are separate from architecture.** `docs/development-status.md` records what exists; `TODO.md` records what remains, including the v1.0.0 gap analysis and milestone exit criteria. +- **Documentation drift is a tracked risk:** release/version, test counts, renderer status, and stale plans must be corrected in the same commit as the change that invalidates them. + +## 13. Glossary - **Access artifact:** A wristband, ID, ticket, credential, or other item used to verify entry. - **Authorized person:** Someone permitted to enter under the current venue policy. diff --git a/docs/asset-tooling.md b/docs/asset-tooling.md index 237f187..f9c5688 100644 --- a/docs/asset-tooling.md +++ b/docs/asset-tooling.md @@ -1,6 +1,10 @@ # Asset Pipeline and Tooling -Everything the game renders is produced or gated by the scripts below. Development-only outputs (AI concept sheets, Blender sources, raw AI fabrics) are gitignored; the audited game assets are committed. +Everything the game renders is produced or gated by the scripts below. Architecture-level contracts, +data flow and failure fallbacks are summarized in +[`architecture.md`](architecture.md#content-and-asset-pipeline-architecture); this page is the +operational reference. Development-only outputs (AI concept sheets, Blender sources, raw AI fabrics) +are gitignored; the audited game assets are committed. ## Image Asset Tools diff --git a/docs/blender-assets.md b/docs/blender-assets.md index 41bdf02..4787e08 100644 --- a/docs/blender-assets.md +++ b/docs/blender-assets.md @@ -1,5 +1,8 @@ # Blender asset library +Architecture context: the asset contracts and fallback path are summarized in +[`architecture.md`](architecture.md#content-and-asset-pipeline-architecture). + Status: built, audited, and integrated (2026-11-01). `NpcAvatar` selects the character variants and attaches the gear; `WorldBuilder` loads the prop library with colliders and phase-driven emissives. See the Phase 3.5 integration in @@ -159,10 +162,10 @@ exactly these points, which gives a quick visual check of the convention. | `marquee` | the procedural marquee | 6 m canopy and sign box; emissive `bulb` + `sign_face`. Overlay the text with the existing `Label3D` | | `sedan` | new (studio arrival) | 4.6 m; emissive `headlight`, red tail lamps | -Props use plain PBR factors (base colour, roughness, metallic, emission) and -have no textures. They are not yet AO-baked; that is still a Phase 4 task. -Emissive materials are always on in the GLB. The integration should tie them to -`WorldBuilder.set_night_mode()`. +Props use plain PBR factors (base colour, roughness, metallic, emission) plus +the committed 256² baked AO maps (`_ao.png`) wired by `WorldBuilder`; +emissive materials are tied to `WorldBuilder.set_night_mode()`. Characters +carry baked AO and the shared neutral material maps described above. ## Checks diff --git a/docs/development-status.md b/docs/development-status.md index aecf4ef..2405c85 100644 --- a/docs/development-status.md +++ b/docs/development-status.md @@ -46,4 +46,4 @@ Implemented so far: - Venue geometry (v0.7.0): the Joke Shop now builds as a narrow brick alley with a warm wall lantern, shutters, dumpster/AC clutter and no skyline; the TV Studio builds a stone facade, bulb canopy, glossy black car and barrier line. `WorldBuilder.VENUE_SPECS` drives facade/street/nav dimensions, and `GameManager` rebuilds only the world container when the venue changes. - Gear fit (post-v0.6.0): Blender gear is measured against the avatar head/skirt silhouette and the checks run in both the Python tooling and the headless suite. Sunglasses, the shoulder bag and the firefighter helmet were fitted to the new faces; the Influencer portrait and gallery were recaptured with a before/after report. -Not yet implemented: a desktop-only Forward+ preset (the renderer stays GL Compatibility for Web parity), live 3D body-camera replay, editor-based GUT integration, and crowd performance profiling/LOD (see [`TODO.md`](../TODO.md)). +Current gaps for v1.0.0: onboarding/campaign progression, deeper authored content and NPC dialogue, mid-shift save/resume and replay, localization/accessibility expansion, voice/audio production, wider performance profiling, signed/notarized release packaging, and a unified Godot baseline. The full gap analysis and milestone plan live in [`TODO.md`](../TODO.md); the current architecture and documentation ownership map are in [`docs/architecture.md`](architecture.md). diff --git a/docs/plan-graphics-v0.6.md b/docs/plan-graphics-v0.6.md index fdc4368..c3d9555 100644 --- a/docs/plan-graphics-v0.6.md +++ b/docs/plan-graphics-v0.6.md @@ -1,7 +1,12 @@ # Development Plan — Graphics Quality v0.6.0 (Blender-authored NPCs) -> Status: Proposed · Target version: **v0.6.0** (MINOR) +> Status: **Completed / historical** · Target version: **v0.6.0** (MINOR), followed by +> v0.7.1's optional Forward+ Desktop HQ build > Companion decision: [ADR-0013](adr/0013-blender-authored-npc-characters.md) +> +> This is an implementation-history document. The current architecture is in +> [`architecture.md`](architecture.md); remaining graphics work is tracked in +> [`TODO.md`](../TODO.md), not as a revived phase plan. ## Why this exists @@ -242,9 +247,9 @@ Props are grounded except `wall_lantern` and `marquee`; both may be emissive. 2. **Higher-resolution environment textures:** regenerate brick/concrete/asphalt through `asset_pipeline.py` with normal maps, keeping the current UV scales; use the same sRGB/albedo + packed ORM discipline as the library assets. -3. **Evaluate a desktop-only Forward+ preset** — done: it boots on the desktop Vulkan -driver, but the renderer is project-wide and the Web preset must stay GL -Compatibility. v0.6.0 keeps Compatibility; a desktop-only override is deferred. +3. **Evaluate a desktop-only Forward+ preset** — completed in v0.7.1 as the optional +Desktop HQ zip. The default renderer stays GL Compatibility for Web parity; the +override is applied only to the copied HQ binaries. 4. Regenerate `docs/screenshots/` with `capture_screenshots.gd`, then run `screen_designs.py compare` and `judge` as the regression gate, plus `blender_assets.py sheet` for the character/gear/prop library.