# 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.