zwitschi
8f228b0c56
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.
82 lines
4.1 KiB
Markdown
82 lines
4.1 KiB
Markdown
# 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/<run>/` holds trial captures/reports.
|
||
These are not runtime resources and may be regenerated.
|
||
5. **Naming.** Files under `assets/images/` are lowercase `snake_case` PNGs,
|
||
`<screen>_<variant>.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.
|