diff --git a/AGENTS.md b/AGENTS.md index f1c4a60..3b63924 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,6 +39,10 @@ All planned implementation work must be represented in `TODO.md`. - Use checkbox items for each concrete task. - Keep tasks small enough to complete and review independently. - Add new tasks when discoveries expand the scope. +- When starting a task, claim it for the agent workflow by changing `[ ]` to `[-]`. Keep it `[-]` + while implementation or verification is in progress; only change it to `[x]` after the work and + relevant checks are finished. If work is abandoned or blocked, leave a clear note and return the + item to `[ ]` (or add a follow-up task). - Mark a task complete only after the implementation and relevant verification are finished. - If any verification check fails, do not mark the task complete. Fix the failure, or if it cannot be fixed, add a follow-up task to `TODO.md`, record the failure in `MEMORY.md`, and report it in the handoff summary. - Do not use prose status updates as a substitute for checkboxes. @@ -52,7 +56,7 @@ Recommended format: ## Core Gameplay - [ ] Add player movement controls. -- [ ] Implement NPC approach behavior. +- [-] Implement NPC approach behavior. (claimed; implementation/verification in progress) - [x] Define escalation levels. ## Documentation diff --git a/MEMORY.md b/MEMORY.md index cc3b645..a199c70 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -43,6 +43,9 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o `docs/screens/designs/` and `docs/screens/concepts/` stay reference-only; QA captures stay in `docs/screenshots/`. When a mockup becomes runtime art, copy/process it into `assets/images/` with a new name (no overwrites) and keep a fallback in code. + **Mockup copies:** 21 design references were copied to `assets/images/ui/` (byte-identical + filenames); `docs/screens/designs/` remains the reference-only copy. `tools/screen_designs.py` + still reads the docs tree until the code-path task moves it; keep the two in sync meanwhile. ## Handoff (read this first) @@ -135,6 +138,22 @@ Session memory for durable decisions, state, and gotchas. Keep concise, remove o flat plane, so avoidance (not a baked mesh) routes guests around props. Placements live in `PROP_PLACEMENTS` with `placement_problems()` validation; variants come from `variant_for(index)`. `smoke_props.gd` must be windowed because the guard reads captured-mouse input. +- **Realism pass tooling (2026-11-01):** `tools/scene_concepts.py` (`list`/`generate`/`process`/ + `audit`/`realism`) never overwrites an image (`next_free_path` adds `-vN`; `process` skips + existing targets). Raw AI output: `assets/textures/ai/v2/raw/` (gitignored). Candidate pool: + `assets/textures/ai/game_ready/v2/` (gitignored except the validated picks un-ignored in + `.gitignore`: skyline day-v4/dusk-v3/night-v4 plus brick/pavers/asphalt/asphalt_wet + normals). + Concepts: `docs/screens/concepts/` (committed, `.gdignore`, targets in its README). Runs: + `docs/screens/realism//` (PNG captures gitignored; `report*.{json,md}` + `sheet.jpg` + committed). `src/test/capture_realism.gd` swaps textures at runtime by the material's + *original* albedo path (`--swap/--night-swap/--tint/--normal=OLD=NEW`) and writes to + `--out=res://...`. Changing game code is not needed for an A/B test. Gotchas: + gpt-5-image-mini honours `background=transparent` for the 3:2 skyline requests, but it writes + garbled "HOLLYWOOD" lettering unless the prompt forbids signs. Skyline strips are 2:1 to match + one UV repeat of the ring. `elapsed_s = 620` gives the *Evening* phase (pink sky), not night. + The gemini-flash-lite realism scores are noisy (±1–2), and the judge sometimes returns a 400 + "API key not valid" from the provider, which the one retry covers. None of the v2 assets are + wired into the game yet. - **Blender asset library (v0.6.0, integrated 2026-11-01):** `tools/blender_assets.py` (`build`/`render` in Blender; `audit`/`sheet`/`list` stdlib) writes `assets/models/blender/{npc,npc_gear,props}/*.glb`, `manifest.json` (integration source of diff --git a/TODO.md b/TODO.md index b217458..46d98d9 100644 --- a/TODO.md +++ b/TODO.md @@ -1,7 +1,7 @@ # TODO Godot 4.3 prototype. Latest release **v0.6.0** (Blender character/gear/prop library, baked AO, environment lift). -Headless suite **222/222** plus **69** Python tooling tests; the session, PLAN-verb, crowd, emergency, +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. @@ -25,7 +25,7 @@ and scene visuals with those mockups — verified with - [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). -- [ ] 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] 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). - [ ] Document one convention for game vs reference vs development images across `assets/textures/`, `assets/images/`, `assets/models/generated/`, `docs/screenshots/`, and `docs/screens/designs/`. - [ ] 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. @@ -80,77 +80,109 @@ measure the in-game result against that target with the screenshot tools. Plan: **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/`, scene references to `docs/screens/concepts/`, -and trial captures and reports to `docs/screens/realism//`. +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//`. ### Step 1 — Tooling (`tools/scene_concepts.py`) -- [ ] Add a catalogue of prompts in three groups: `scene` (16:9 example 3D game frames), +- [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. -- [ ] `generate [--group] [--only] [--variants N]`: call the OpenRouter image API through +- [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. -- [ ] `process`: turn raw backdrops into 2048×512 RGBA strips that tile horizontally (edge +- [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. -- [ ] `audit`: run `asset_pipeline.audit_image` on the processed candidates (`backdrop` / +- [x] `audit`: run `asset_pipeline.audit_image` on the processed candidates (`backdrop` / `tile` roles) and fail on any bad result. -- [ ] `realism`: for each trial capture, report the Pillow detail metrics (edge density, +- [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. -- [ ] Unit tests (`tools/test_scene_concepts.py`): catalogue shape, the no-overwrite path +- [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 -- [ ] Generate 3D-game-style example frames for every venue and time of day: Hollywood entrance +- [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. -- [ ] Review the set and record the visual targets each frame sets (sky, haze, material detail, +- [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) -- [ ] Generate skyline panoramas for day, dusk and night (lit windows): Hollywood/Los Angeles +- [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. -- [ ] 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. +- [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 -- [ ] Generate higher-detail seamless tiles: red brick facade, granite/limestone facade +- [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. -- [ ] Process them into 1024² game-ready tiles plus normal maps in - `assets/textures/ai/game_ready/v2/` and audit them. +- [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) -- [ ] Add `src/test/capture_realism.gd`. It boots the Hollywood venue, captures a fixed shot +- [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//`. -- [ ] Capture the baseline (current assets) and the candidate set (v2 skyline + textures), and +- [x] Capture the baseline (current assets) and the candidate set (v2 skyline + textures), and copy them into `docs/screens/realism//{baseline,candidate}/`. ### Step 6 — Compare against the realistic target -- [ ] Run `scene_concepts.py realism` on baseline and candidate. Record the metric deltas and the - vision scores, and note which candidate textures/backdrops win. -- [ ] Note the remaining realism gaps (sky/fog, lighting, building geometry, NPC fidelity) as +- [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 diff --git a/assets/images/ui/access_inspection.png b/assets/images/ui/access_inspection.png new file mode 100644 index 0000000..ef23836 Binary files /dev/null and b/assets/images/ui/access_inspection.png differ diff --git a/assets/images/ui/body_camera_timeline.png b/assets/images/ui/body_camera_timeline.png new file mode 100644 index 0000000..4051307 Binary files /dev/null and b/assets/images/ui/body_camera_timeline.png differ diff --git a/assets/images/ui/crowd_panic.png b/assets/images/ui/crowd_panic.png new file mode 100644 index 0000000..245a099 Binary files /dev/null and b/assets/images/ui/crowd_panic.png differ diff --git a/assets/images/ui/emergency_radio.png b/assets/images/ui/emergency_radio.png new file mode 100644 index 0000000..a956202 Binary files /dev/null and b/assets/images/ui/emergency_radio.png differ diff --git a/assets/images/ui/escalation_hud.png b/assets/images/ui/escalation_hud.png new file mode 100644 index 0000000..db7a498 Binary files /dev/null and b/assets/images/ui/escalation_hud.png differ diff --git a/assets/images/ui/joke_shop_queue.png b/assets/images/ui/joke_shop_queue.png new file mode 100644 index 0000000..1338360 Binary files /dev/null and b/assets/images/ui/joke_shop_queue.png differ diff --git a/assets/images/ui/late_night_avenue.png b/assets/images/ui/late_night_avenue.png new file mode 100644 index 0000000..af03f42 Binary files /dev/null and b/assets/images/ui/late_night_avenue.png differ diff --git a/assets/images/ui/movement_precision.png b/assets/images/ui/movement_precision.png new file mode 100644 index 0000000..4fa5577 Binary files /dev/null and b/assets/images/ui/movement_precision.png differ diff --git a/assets/images/ui/night_flashlight.png b/assets/images/ui/night_flashlight.png new file mode 100644 index 0000000..6db0d39 Binary files /dev/null and b/assets/images/ui/night_flashlight.png differ diff --git a/assets/images/ui/pause_overlay.png b/assets/images/ui/pause_overlay.png new file mode 100644 index 0000000..b87b2dc Binary files /dev/null and b/assets/images/ui/pause_overlay.png differ diff --git a/assets/images/ui/prop_gallery.png b/assets/images/ui/prop_gallery.png new file mode 100644 index 0000000..9e94724 Binary files /dev/null and b/assets/images/ui/prop_gallery.png differ diff --git a/assets/images/ui/radial_menu.png b/assets/images/ui/radial_menu.png new file mode 100644 index 0000000..113e4b1 Binary files /dev/null and b/assets/images/ui/radial_menu.png differ diff --git a/assets/images/ui/radio_report.png b/assets/images/ui/radio_report.png new file mode 100644 index 0000000..9c5cf0f Binary files /dev/null and b/assets/images/ui/radio_report.png differ diff --git a/assets/images/ui/responder_arrival.png b/assets/images/ui/responder_arrival.png new file mode 100644 index 0000000..a9a190c Binary files /dev/null and b/assets/images/ui/responder_arrival.png differ diff --git a/assets/images/ui/settings_panel.png b/assets/images/ui/settings_panel.png new file mode 100644 index 0000000..e9bf909 Binary files /dev/null and b/assets/images/ui/settings_panel.png differ diff --git a/assets/images/ui/shift_review.png b/assets/images/ui/shift_review.png new file mode 100644 index 0000000..fd40295 Binary files /dev/null and b/assets/images/ui/shift_review.png differ diff --git a/assets/images/ui/start_menu.png b/assets/images/ui/start_menu.png new file mode 100644 index 0000000..5940673 Binary files /dev/null and b/assets/images/ui/start_menu.png differ diff --git a/assets/images/ui/studio_arrival.png b/assets/images/ui/studio_arrival.png new file mode 100644 index 0000000..e760de5 Binary files /dev/null and b/assets/images/ui/studio_arrival.png differ diff --git a/assets/images/ui/targeting_npc.png b/assets/images/ui/targeting_npc.png new file mode 100644 index 0000000..f49043a Binary files /dev/null and b/assets/images/ui/targeting_npc.png differ diff --git a/assets/images/ui/venue_overview.png b/assets/images/ui/venue_overview.png new file mode 100644 index 0000000..39c7016 Binary files /dev/null and b/assets/images/ui/venue_overview.png differ diff --git a/assets/images/ui/wand_screening.png b/assets/images/ui/wand_screening.png new file mode 100644 index 0000000..657e039 Binary files /dev/null and b/assets/images/ui/wand_screening.png differ