security-game/docs/adr/0014-runtime-image-root.md

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.