# TODO

Godot 4.3 prototype. Latest release **v0.6.0** (Blender character/gear/prop library, baked AO, environment lift).
Headless suite **222/222** plus **81** Python tooling tests; the session, PLAN-verb, crowd, emergency,
timeline, audio, scenario-content, props, NPC-budget, movement, and windowed focus/radial smokes
pass. Anonymous downloads are enabled on the host.

The scheduled presentation pass is complete (see `DONE.md`). The next scheduled pass is the
graphics-quality work in [`docs/plan-graphics-v0.6.md`](docs/plan-graphics-v0.6.md).

> **v0.6.0 shipped (2026-11-01):** the Blender character/gear/prop library is integrated, AO maps
> are baked and wired, and the environment textures were lifted to 1024² with normal maps. See
> `DONE.md` for the completed graphics plan.

## Visual alignment with rendered mockups

The AI-rendered references in `docs/screens/designs/` (start menu, pause, settings,
shift review, radial menu, HUD, scene views) describe the intended look of every
screen. This pass reorganizes how generated images are stored, makes the game load
the proposed interface/scene art from disk, and aligns the selection screens, HUD,
and scene visuals with those mockups — verified with
`tools/screen_designs.py compare` + `judge`.

### Storage restructure

- [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).
- [x] 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).
- [x] Document one convention for game vs reference vs development images across `assets/textures/`, `assets/images/`, `assets/models/generated/`, `docs/screenshots/`, and `docs/screens/designs/` (in `docs/architecture.md`, ADR-0014).
- [x] Re-run `godot --headless --path . --import` to regenerate `.import` sidecars after any move.
- [ ] Confirm `.gitignore` still excludes development-only outputs (concepts, Blender sources, raw AI fabrics) under the new layout.

### Documentation path updates

- [x] Update `README.md` paths (screen-designs section, confirmed-assets links, the `assets/images/scenes` resize example).
- [x] Update `docs/architecture.md`, `PLAN.md`, and ADR references: docs/screens/designs/ is now explicitly the reference-only snapshot; runtime art lives in assets/images/ (ADR-0014).
- [x] Update `tools/screen_designs.py` docstrings and mark the old paths in `DONE.md` as historical.

### Code path updates

- [x] Point `tools/screen_designs.py generate` at the new design output path and keep `compare`/`judge` reading the right locations.
- [x] Update GDScript `preload()` paths if game textures move (no runtime material/model textures moved; UI art added under assets/images/).
- [x] Update capture output directories if captures relocate (none did; QA captures stay in docs/screenshots/).

### Load proposed interfaces + scene art from disk

- [x] Add a central UI/scene art loader (e.g. `src/game/ui/art.gd`) that loads the mockup-derived images from the new runtime root, with a procedural fallback when a file is missing.
- [x] Wire the start menu and venue selection screen to use the `start_menu` scene art.
- [ ] Wire the pause overlay, settings, shift review, radial menu, and HUD chrome to their reference images.

### Align in-game visuals

- [ ] Make the venue selection screen match the `start_menu` mockup (layout, palette, background).
- [ ] Make the HUD match the `targeting_npc` / `escalation_hud` mockups (focus ring, escalation meter, log, hints).
- [ ] Align the remaining panels (pause, settings, shift review, radio, wand, timeline) to their mockups.
- [ ] Align scene lighting, fog, and post-processing for `venue_overview` and `late_night_avenue`.

### Verify against the mockups

- [ ] Regenerate the staged captures and run `screen_designs.py compare` (no gross drift).
- [ ] Run `screen_designs.py judge` and clear every `diff` verdict (target `match`/`review`).
- [ ] Add the capture + compare step to CI or a repeatable smoke so drift is caught early.

## Fix mouse movement bug

- [ ] Investigate why mouse input is not being captured or processed correctly in the game window.

## Improve in-game pop-ups

- [ ] Improve the visual appearance of in-game pop-ups (layout, button style, palette, icons, and text styling).

## Realistic backgrounds, textures and scene references

Goal: replace the outdated flat skyline backdrop (`assets/textures/skyline.png`, black boxes
with dot windows) and the flat-looking surface tiles with AI-generated, more realistic
backgrounds and textures. Add a larger set of example 3D scene images as art direction, and
measure the in-game result against that target with the screenshot tools. Plan:
[`PLAN.md` → Visual Quality Direction → Realism pass](PLAN.md#realism-pass).

**Rule for every step: never overwrite an existing image.** New outputs get new paths. When a
path is taken, the tools pick the next free `-vN` suffix. Raw AI output stays on disk under
`assets/textures/ai/v2/raw/` (gitignored like the other raw AI folders). Processed game-ready
candidates go to `assets/textures/ai/game_ready/v2/`, a local pool where only the validated picks
are tracked (ADR-0014). Scene references go to `docs/screens/concepts/`, and trial captures and
reports to `docs/screens/realism/<run>/`.

### Step 1 — Tooling (`tools/scene_concepts.py`)

- [x] Add a catalogue of prompts in three groups: `scene` (16:9 example 3D game frames),
      `backdrop` (4:1 skyline panoramas with transparent sky), and `texture` (seamless PBR
      surface tiles). Each entry has a name, prompt, role and target path.
- [x] `generate [--group] [--only] [--variants N]`: call the OpenRouter image API through
      `generate_textures.generate_image` (key from the repo `.env`), save raw output, and never
      overwrite (`next_free_path`). Print every file written.
- [x] `process`: turn raw backdrops into 2048×512 RGBA strips that tile horizontally (edge
      crossfade, sky made fully transparent, hard alpha for the alpha-scissor material). Turn raw
      textures into seamless 1024² tiles (`asset_pipeline.make_seamless`) plus a normal map
      (`make_normal_maps.normal_map`). Skip outputs that already exist.
- [x] `audit`: run `asset_pipeline.audit_image` on the processed candidates (`backdrop` /
      `tile` roles) and fail on any bad result.
- [x] `realism`: for each trial capture, report the Pillow detail metrics (edge density,
      contrast, colour spread, saturation) next to the matching concept image. Optionally ask a
      vision model (`google/gemini-2.5-flash-lite`) for 0–10 realism scores (lighting,
      materials, texture detail, backdrop, overall) with concrete fixes. Write a new JSON +
      Markdown report per run.
- [x] Unit tests (`tools/test_scene_concepts.py`): catalogue shape, the no-overwrite path
      picker, backdrop/tile processing on synthetic images, metrics, and the judge payload/parse
      (offline, no network).

### Step 2 — Example 3D scene images

- [x] Generate 3D-game-style example frames for every venue and time of day: Hollywood entrance
      (morning, golden hour, rainy night), boulevard skyline view (day, dusk), Joke Shop alley
      (evening, close-up of the door), studio stage door (night arrival), sidewalk material
      close-up, entrance steps and podium, crowd-control barrier line, and a responder arrival
      wide shot.
- [x] Review the set and record the visual targets each frame sets (sky, haze, material detail,
      backdrop depth) in the report.

### Step 3 — Backgrounds (replace the outdated skyline)

- [x] Generate skyline panoramas for day, dusk and night (lit windows): Hollywood/Los Angeles
      mid-rise blocks, palm silhouettes, the hills on the horizon, a transparent sky, and a
      straight-on view, in several variants each.
- [x] Process them into `assets/textures/ai/game_ready/v2/skyline_{day,dusk,night}*.png`,
      seamless horizontally for the 3× UV repeat around the backdrop ring. Strips are 2048×1024
      (2:1, one UV repeat of the 400×60 m ring is about 133×60 m). 12 candidates, 11 audit
      clean; `skyline_day-v3` misses the seam limit by 0.6. Variants 1–2 contain garbled
      "Hollywood" lettering, so the prompt now forbids signs. Picks: `skyline_day-v4`,
      `skyline_dusk-v3`, `skyline_night-v4`.

### Step 4 — Textures

- [x] Generate higher-detail seamless tiles: red brick facade, granite/limestone facade
      (studio), sidewalk concrete pavers with joints, asphalt with aggregate, wet night asphalt,
      stone steps, striped awning canvas, and stucco wall.
- [x] Process them into 1024² game-ready tiles plus normal maps in
      `assets/textures/ai/game_ready/v2/` and audit them (16 tiles + 16 normals, all good). The
      `awning_canvas` seam crossfade smears the stripes at the tile edge; it needs a
      stripe-aligned crop.

### Step 5 — In-game trial captures (no game-code change)

- [x] Add `src/test/capture_realism.gd`. It boots the Hollywood venue, captures a fixed shot
      list (entrance day, boulevard/skyline day, boulevard night), and can swap textures at
      runtime from `--skyline=` / `--brick=` / `--concrete=` / `--asphalt=` user arguments. The
      swap finds materials by their current texture, so baseline and candidate frames use the
      same camera. Writes to `user://screenshots/realism/<tag>/`.
- [x] Capture the baseline (current assets) and the candidate set (v2 skyline + textures), and
      copy them into `docs/screens/realism/<run>/{baseline,candidate}/`.

### Step 6 — Compare against the realistic target

- [x] Run `scene_concepts.py realism` on baseline and candidate. Record the metric deltas and the
      vision scores, and note which candidate textures/backdrops win. Run
      `docs/screens/realism/2026-11-01-v2/` (`report-v2.md`, `sheet.jpg`) gives these mean
      judge scores: backdrop 2.6 → 3.6 (v2 day + night skyline) → **4.0** (v2 day + dusk
      skyline for the Evening phase), texture detail 1.2 → 1.6–1.75, overall 1.6 → 2.0. Single
      scores swing by ±1–2 between runs, so read them as trends. The `characters` score
      moved from 3.0 to 1.0 with identical NPCs, which shows the noise.
- [x] Note the remaining realism gaps (sky/fog, lighting, building geometry, NPC fidelity) as
      follow-up tasks below.

### Step 6b — Follow-ups from the 2026-11-01 realism report

- [ ] Fix sidewalk overexposure: the concrete reads near-white in every day shot, while the
      concepts keep the ground mid-grey. Lower the albedo tint or the sun energy, or add tonemap
      exposure in `Materials.configure_environment`.
- [ ] Make the Evening/Late phases darker and lit by practical lights (marquee, lamps,
      windows), and add wet-asphalt roughness at night, as in the rain-night concept.
- [ ] Choose the skyline per phase (day → `skyline_day`, Evening → `skyline_dusk`, Late →
      `skyline_night`) and lower the fog density on the backdrop so the night windows show.
- [ ] Raise the backdrop plane (60 m → ~90 m) or use 2 UV repeats so the skyline is not a
      thin strip at the horizon.
- [ ] Add facade depth (plinth, cornice, window reveals) and replace the blob trees and shrubs
      with denser foliage meshes (Blender library follow-up).
- [ ] Re-cut `awning_canvas` so its stripes align at the tile edge.
- [ ] Capture shots from the Joke Shop and the studio too (add them to `capture_realism.gd` /
      `SHOTS`).

### Step 7 — Adopt the winners (after the in-flight normal-map/AO work is committed)

- [x] Track the validated picks in place (ADR-0014). `game_ready/v2/*` is a gitignored local
      pool; `.gitignore` un-ignores the skyline picks and the brick/pavers/asphalt (+ wet) tiles
      and their normals. Never replace the existing `game_ready/` files.
- [ ] Point `WorldBuilder.T_SKYLINE` at the chosen v2 skyline (separate day/night textures through
      `set_night_mode`), and retune `albedo_color` for the realistic strip.
- [ ] Switch `materials.gd` / `world_builder.gd` surface preloads to the chosen v2 tiles + normal
      maps, keeping the current UV scales. Update `test_materials.gd` / `test_world.gd`.
- [ ] Regenerate `docs/screenshots/` with `capture_screenshots.gd`, then run
      `screen_designs.py compare` + `judge` and `scene_concepts.py realism`. There must be no
      `diff` verdict regressions, and realism scores must not drop.
- [ ] Update `README.md` (tool usage + gallery), `MEMORY.md` and `docs/architecture.md`.

## Future ideas (optional, not scheduled)

- [ ] Live 3D body-camera replay (the timeline is text-only today).
- [ ] Additional venues or seasonal events authored from the new `.tres` files.
- [ ] Real voice/dialogue audio (the crowd bed and radio crackle are procedural).
- [ ] Swap the primitive prop builder for an image-to-mesh model API behind the same
      `assets/models/generated/<prop>.glb` contract.