From 8f228b0c56b48a4ac6e19f90341463d742c4bf37 Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Sun, 1 Nov 2026 15:16:24 +0100 Subject: [PATCH] Decide the canonical runtime image root (ADR-0014) assets/images/ is now the runtime root for composed interface/scene art: ui/ for screen and panel art, scenes/ for full-frame scene art. Tiled PBR textures remain under assets/textures/; docs/screens/designs and concepts stay reference-only; QA captures stay under docs/screenshots. Mockups that become runtime art are copied/processed with a new name (no overwrites) and always have a code fallback. Records the convention in MEMORY, adds ADR-0014 to the architecture index, and closes the first storage-restructure TODO item. --- MEMORY.md | 6 +++ TODO.md | 3 +- docs/adr/0014-runtime-image-root.md | 81 +++++++++++++++++++++++++++++ docs/architecture.md | 1 + 4 files changed, 90 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0014-runtime-image-root.md diff --git a/MEMORY.md b/MEMORY.md index 3c7a985..cc3b645 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -38,6 +38,12 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o avatars. Head-turn offsets use `+basis.z` for the same reason. Covered by `test_yaw_faces_the_movement_direction`. +- **Image root (ADR-0014, 2026-11-01):** `assets/images/` is the runtime root for composed + interface/scene art (`ui/`, `scenes/`); tiled PBR textures stay under `assets/textures/`; + `docs/screens/designs/` and `docs/screens/concepts/` stay reference-only; QA captures stay in + `docs/screenshots/`. When a mockup becomes runtime art, copy/process it into `assets/images/` + with a new name (no overwrites) and keep a fallback in code. + ## Handoff (read this first) - **Visual-alignment pass planned (2026-11-01):** `TODO.md` gains a "Visual diff --git a/TODO.md b/TODO.md index 1b99e48..b217458 100644 --- a/TODO.md +++ b/TODO.md @@ -23,7 +23,8 @@ and scene visuals with those mockups — verified with ### Storage restructure -- [ ] Decide the canonical runtime image root (e.g. `assets/images/` for UI/scene art) and record it in `MEMORY.md` and an ADR. +- [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). - [ ] 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/`. - [ ] Re-run `godot --headless --path . --import` to regenerate `.import` sidecars after any move. diff --git a/docs/adr/0014-runtime-image-root.md b/docs/adr/0014-runtime-image-root.md new file mode 100644 index 0000000..248914f --- /dev/null +++ b/docs/adr/0014-runtime-image-root.md @@ -0,0 +1,81 @@ +# ADR-0014: Canonical runtime image root and image conventions + +- **Status:** Accepted (2026-11-01) +- **Date:** 2026-11-01 + +## Context + +The project now contains several kinds of images, and their locations overlap: + +- hand-authored and AI-generated **surface textures** under `assets/textures/` + (`ai/game_ready/`, `ai/game_ready/v2/`, `npc/`), +- **screen mockups** under `docs/screens/designs/`, +- **scene references** under `docs/screens/concepts/`, +- **QA captures** under `docs/screenshots/` and `docs/screens/realism/`, +- **raw AI output** under gitignored `assets/textures/ai/*/raw/`. + +The visual-alignment pass needs the game to load proposed interface and scene +art at runtime. That art is currently only in the docs tree, which is not the +right place for resources the build must ship and which contributors expect to +be documentation-only. Without a convention, UI art, tiled materials, reference +mockups, and screenshots will keep being confused for one another. + +## Decision + +1. **`assets/images/` is the canonical runtime root for composed image art** — + interface art, backgrounds, and full-frame scene art that the game loads as + an image, not as a tiled material. + - `assets/images/ui/` — screen and panel art used by the UI layer (start + menu/venue selection background, pause/settings chrome, HUD plates). + - `assets/images/scenes/` — composed scene/background art loaded directly as + an image (not repeated as a surface texture). +2. **Tiled material textures stay under `assets/textures/`.** Brick, concrete, + asphalt, fabric, skyline strips used with UV repetition, and model maps are + materials, not composed screen art. Raw AI output stays in gitignored + `assets/textures/ai/*/raw/`; validated environment candidates stay under + `assets/textures/ai/game_ready/v2/`. +3. **`docs/screens/` remains reference-only.** `designs/` holds mockups and + `concepts/` holds larger art-direction sets; neither is shipped or loaded by + the game. When a reference becomes runtime art, it is copied/processed into + `assets/images/` with a new descriptive name, following the no-overwrite + rule (`-vN` suffixes from the asset tooling). +4. **QA output stays in `docs/`.** `docs/screenshots/` holds the README/catalogue + captures and `docs/screens/realism//` holds trial captures/reports. + These are not runtime resources and may be regenerated. +5. **Naming.** Files under `assets/images/` are lowercase `snake_case` PNGs, + `_.png`, at the native UI size (1280×720 for 16:9 screens) + or the size the scene actually uses. Every runtime image needs a procedural + or neutral fallback in code so a missing file never breaks a screen. +6. **Imports.** Runtime images are normal Godot textures: commit the PNG, let + `godot --headless --path . --import` regenerate `.import` sidecars, and keep + development-only images out of `assets/images/`. + +## Consequences + +### Positive + +- One obvious place for art the game actually loads, separate from references + and QA captures. +- Builds/exports can include `assets/images/**` without also shipping mockups, + screenshots, or raw AI output. +- The no-overwrite rule and variant naming make visual experiments reversible + and keep the docs references stable. + +### Negative + +- A reference image that becomes runtime art exists in two places (docs copy + + processed runtime copy); contributors must keep the processed copy current. +- Moving existing mockups later is a path migration that touches docs, tools, + and `preload()` paths — tracked as the remaining visual-alignment storage + tasks. + +## Alternatives considered + +- **Use `docs/screens/designs/` as the runtime root.** Rejected: docs are not + ship-ready gameplay resources, and mixing references with runtime art makes + exports and cleanup brittle. +- **Put everything in `assets/textures/`.** Rejected: composed UI/scene art is + not a tiled material; mixing it with PBR tiles hides the distinction and + invites incorrect import settings. +- **Keep images only in code / procedural UI.** Rejected: the visual-alignment + pass is explicitly about using the rendered mockups as the target look. diff --git a/docs/architecture.md b/docs/architecture.md index c792698..0baba09 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -167,6 +167,7 @@ Architecture decisions are recorded as ADRs: - [ADR-0011: Aim-free selection and precision walk](adr/0011-aim-free-selection-and-precision-walk.md) - [ADR-0012: Surface materials and generated props](adr/0012-surface-materials-and-generated-props.md) - [ADR-0013: Blender-authored NPC characters and baked materials](adr/0013-blender-authored-npc-characters.md) +- [ADR-0014: Canonical runtime image root and image conventions](adr/0014-runtime-image-root.md) ## 10. Quality Requirements