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.
This commit is contained in:
1 parent
d307746351
commit
8f228b0c56
4 files changed
+90
-1
No files matched your search
@@ -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/<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.
|
||||
Reference in new issue
Block a user