From 6a0bf70fdf37b67a8b5437abb603b5420266ed16 Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Sun, 1 Nov 2026 15:47:56 +0100 Subject: [PATCH] Document the asset storage convention Add the path table from ADR-0014 to the architecture documentation (runtime UI/scene art, tiled textures, models, reference art, QA captures, raw sources) and close the second storage-restructure TODO item. --- TODO.md | 2 +- docs/architecture.md | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/TODO.md b/TODO.md index 46d98d9..84cab42 100644 --- a/TODO.md +++ b/TODO.md @@ -26,7 +26,7 @@ and scene visuals with those mockups — verified with - [x] Decide the canonical runtime image root (`assets/images/` for UI/scene art): recorded in `MEMORY.md` and [ADR-0014](docs/adr/0014-runtime-image-root.md). - [x] Move the reference mockups from `docs/screens/designs/` into the runtime root (keep `docs/screens/designs/` as a docs-only copy or replace it with the new path). -- [ ] Document one convention for game vs reference vs development images across `assets/textures/`, `assets/images/`, `assets/models/generated/`, `docs/screenshots/`, and `docs/screens/designs/`. +- [x] Document one convention for game vs reference vs development images across `assets/textures/`, `assets/images/`, `assets/models/generated/`, `docs/screenshots/`, and `docs/screens/designs/` (in `docs/architecture.md`, ADR-0014). - [ ] Re-run `godot --headless --path . --import` to regenerate `.import` sidecars after any move. - [ ] Confirm `.gitignore` still excludes development-only outputs (concepts, Blender sources, raw AI fabrics) under the new layout. diff --git a/docs/architecture.md b/docs/architecture.md index 0baba09..685768d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -81,10 +81,29 @@ 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/`) without ever overwriting an image, and scores `src/test/capture_realism.gd` A/B captures 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. 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. +### Asset storage conventions + +The canonical rules live in [ADR-0014](adr/0014-runtime-image-root.md). In short: + +| Location | Contents | Loaded at runtime? | +| --- | --- | --- | +| `assets/images/ui/` | Composed screen/panel art (start menu, HUD chrome, mockup-derived backgrounds) | Yes | +| `assets/images/scenes/` | Composed full-frame scene/background art | Yes | +| `assets/textures/ai/game_ready/` (+ `v2/`) | Tiled/PBR surface textures, model maps, skyline strips | Yes, as materials | +| `assets/models/generated/`, `assets/models/blender/` | 3D props/characters and manifests | Yes | +| `docs/screens/designs/`, `docs/screens/concepts/` | Reference mockups and art-direction sets | No (reference only) | +| `docs/screenshots/`, `docs/screens/realism/` | README/catalogue captures and QA reports | No (generated QA) | +| `assets/textures/ai/v2/raw/`, Blender `.blend` sources | Raw AI output / editable sources | No (gitignored or `.gdignore`d) | + +When reference art becomes runtime art, copy or process it into `assets/images/` with a +new descriptive name (never overwrite an existing image) and keep a procedural fallback +in code. + ## 6. Runtime View ### Routine interaction