Reorder TODO and docs around character and map priorities
Full build / Import + headless tests (push) Successful in 37s
Full build / Full desktop build + optional release (push) Skipped

This commit is contained in:
zwitschi committed 2026-11-03 09:17:49 +01:00
1 parent 08e9044593
commit 51f537720f
8 files changed
+330 -220

No files matched your search

+39 -4
View File
@@ -117,6 +117,7 @@ The asset/content pipeline is part of the architecture, not an external build de
| 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 |
| Local map data (planned) | OSM/3D building extract + licensed reference photos + AI/splat evaluation | derived map assets with provenance sidecars | `WorldBuilder` venue specs | current stylized venue geometry |
| Release | Gitea workflow + build/publish scripts | platform binaries, Web zip, Desktop HQ zip | players | source build |
Contracts that keep the pipeline replaceable:
@@ -133,8 +134,10 @@ Characters have two authored sources and one procedural fallback. The eight-vari
Blender library (`assets/models/blender/npc/`) is the normal presentation path; the
older skinned `npc_base` (`assets/models/generated/npc_base.glb`) remains a frozen
contract and fallback; `NpcAvatar`'s procedural rig is the offline last resort.
Blender is a developer tool only — runtime, tests and CI consume committed GLBs and
maps.
Four crowd-variety prototypes have been built and audited locally but are not yet in
the shipped catalogue; generator-first expansion is the active character track
(ADR-0015). Blender is a developer tool only — runtime, tests and CI consume committed
GLBs and maps.
| Tool | Role | Committed artifact | Verification gate |
| --- | --- | --- | --- |
@@ -169,6 +172,36 @@ Evidence and detailed contracts live in [`blender-assets.md`](blender-assets.md)
[`npc-proportion-audit.md`](npc-proportion-audit.md); command-level usage is in
[`asset-tooling.md`](asset-tooling.md).
### Local map development tooling (planned)
The current venues are hand-authored procedural reconstructions in
`src/game/world_builder.gd`. The **Local map development** track in
[`TODO.md`](../TODO.md#local-map-development) is unversioned and planned: it will
test whether licensed data and reference photography can replace or supplement the
stylized geometry without moving map data, AI composition or splat rendering into
the runtime.
Planned stages and gates:
| Stage | Source | Output | Gate |
| --- | --- | --- | --- |
| Footprints and massing | Offline OpenStreetMap extract + licence-compatible 3D building data (OSM Buildings, Overture, CityGML/LOD1–2) | Local footprint/massing scenes, extract date and query pinned | ODbL attribution/share-alike review; scale/orientation and venue-footprint comparison |
| Reference imagery | Wikimedia Commons, own/team photos or other clearly licensed images | Reference boards and material candidates | Written author/licence/attribution, privacy redaction, no unlicensed Street View or scraped commercial imagery |
| AI-assisted composition | Project image tooling | Palette/facade-rhythm boards and material candidates | Model/prompt/output recorded; human review; never treated as licensed map data |
| Photoreal facade kit | Project-authored geometry and derived materials | Committed facade modules and PBR maps | WorldBuilder budget, collider/nav coverage, Compatibility-readability and screenshot review |
| Gaussian splatting | Licensed/permissioned photo sets + pinned offline toolchain | Development-only splat, texture or proxy experiments | Per-path ADR; runtime only if performance, collision/navigation and provenance are proven |
Contracts for any future map source:
- Runtime consumes committed, derived assets only; no online OSM, photo or splat
service is a build or play dependency.
- OSM ODbL, photo licences, capture permissions and privacy redaction are recorded
in a provenance sidecar before an asset enters the repository.
- Collision and navigation stay mesh-based; a splat may never become the playable
floor or the access/occlusion authority.
- The stylized venue geometry remains the fallback until a data-backed block passes
the venue budget, navigation, visual and provenance gates.
### Content authoring and runtime data flow
`ScenarioFactory` is the source of truth for the three authored venues. `tools/export_venues.gd`
@@ -315,6 +348,7 @@ Architecture decisions are recorded as ADRs:
- Unsigned macOS builds, AI asset provenance and any storefront/legal requirements are release blockers for a public release.
- Documentation drift has already occurred (release version, implemented status and obsolete plan docs); the ownership map and roadmap must be kept current in the same change as the implementation.
- Character quality is only partly automatable: proportions, budgets and gear fit are measured, but face realism and venue-lighting readability still need the baseline/review sheets and human sign-off after any mesh, map or material change.
- Local-map data and photo-derived assets add a second provenance and privacy risk: OSM share-alike, photo rights, faces/plates, property permission and rapidly churning splat tooling must be resolved before any derived asset ships.
## 12. Documentation Consolidation and Ownership
@@ -332,11 +366,12 @@ architecture document.
| [`docs/blender-assets.md`](blender-assets.md) | Blender character/gear/prop contracts and attach points | Detailed asset contract appendix |
| [`docs/npc-visual-review.md`](npc-visual-review.md) | NPC baseline views, acceptance criteria and ranked visual gaps | Visual-QA appendix to the character tooling section |
| [`docs/npc-proportion-audit.md`](npc-proportion-audit.md) | Measured proportions against the stylized guide | Measurement appendix to the character tooling section |
| [`docs/npc-model-sourcing.md`](npc-model-sourcing.md) | Character-source evaluation, licence rules and the character-development plan | Supports the character tooling section and ADR-0015 |
| [`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 0.x roadmap | Planning source; no architecture duplication |
| [`TODO.md`](../TODO.md) | Priority-ordered active tasks, unversioned development tracks and versioned roadmap | Planning source; no architecture duplication |
| [`CHANGELOG.md`](../CHANGELOG.md) | User-facing release history | Release/version companion |
Consolidation decisions:
@@ -344,7 +379,7 @@ 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.
- **Completed plans are removed, not kept as competing roadmaps.** Historical graphics work is summarized by ADR-0013, the asset pipeline section and the v0.6.0 changelog; new work belongs in TODO.
- **Status and roadmap are separate from architecture.** `docs/development-status.md` records what exists; `TODO.md` records what remains, including the 0.x gap analysis and milestone exit criteria.
- **Status and roadmap are separate from architecture.** `docs/development-status.md` records what exists; `TODO.md` records what remains, ordered as unversioned development tracks, versioned milestones and deferred work.
- **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