# TODO.md

Actionable task list for this project. This file is the single, central place for planned work, claims, and progress marks. Milestone goals, scope, and release gates are in [ROADMAP.md](ROADMAP.md).

## Conventions

- Mark items **open** (`- [ ]`), **active/in progress** (`- [A]`, **deferred** `- [D]`), or **done** (`- [x]`). Keep the marks accurate.
- A level-three (`###`) section being worked on carries `- active - <sessionId>` (and optionally the branch name) in its heading. Remove the suffix when you stop.
- When all steps in a version section are done: write a `CHANGELOG.md` entry, then remove the version section from this file.
- Release gate: a version is tagged only on the owner's explicit go-ahead once its release checks pass, not automatically when the checkboxes close.

## 0.1.5 — Façade finishing (patch)

Suggested blender skills: **references** (reference-image-match against the photographs), **historical-worlds** / **archviz** (1920s Hollywood Blvd neoclassical detail), **materials** and **lookdev** for the remaining surface work.

The `0.1.4` kit, materials and theatre trim are signed off; these are the geometry items that were carried forward rather than grown inside that patch.

### Patch tasks

- [A] **Retail neighbours (6822 Budget, 6806–6820, 6800 Lee Drug) from their own references.** **Started 2026-11-09.** Fetched the one usable reference Commons holds for this run — `Art/reference/retail-neighbours/01-lee-drug-and-neighbor.jpg` (Gb321, CC BY-SA 4.0, 1920×953) — which shows 6800 **and** its neighbour at street level; the vision pre-check confirmed shopfronts and parapets are visible. The 18-frame theatre set cannot stand in for these façades, and Commons has nothing else for 6822 or 6806–6820, so per-building references for those two remain the blocker. **Kit layout fixed while here:** bay count was `round(width / 4.96)`, which gave 6922 thirteen bays across 65.8 m (a window every 4.96 m on a 37 m block) and left bare wall under the cornice; bays are now capped at 9 with the module widened, and the storey spread fills the available height (6922 9 × 11, 6806 7 × 3, 6800 4 × 3, theatre 8 × 6).
- [x] **Hero façade: fluting and the motto band as geometry.** **Done 2026-11-09.** Fluting: 20 grooves per column (thin shadow-tone cylinders set into the shaft, 120 pieces) instead of boolean cuts — it breaks the flat highlight at a fraction of the poly cost. Motto band: a real recess now, with a moulded surround standing 6 cm proud and the panel set 12 cm behind it, replacing the 8 cm dark stripe. Hero is 271 objects / 5 492 tris (from 148 / 3 044) and still 14.50 m. **En route it exposed a placement bug:** `ue_hero_facade_import.py` carried its own stale hero position `(-12024.5, -1450)` from before the `0.1.0` frontage fix, so running the importer alone moved the hero 13 m east and onto the north side — invisible in a render, and it dropped the reference score from 0.69 to 0.56. Placement now lives in `Tools/ue_placement.py` with span validators, asserted after every import (`span ok: X -14644..-12028`), and the spawn-view score recovered to **0.72**.
- [x] **Blosm blockout cleaning pass.** **Done 2026-11-09 — the cleaning it needed was material and placement hygiene, not more geometry.** Audit found **604 of 620 mesh actors with no material at all**: `ensure_material` deleted and recreated each site material on every run, orphaning every reference held by the 598 kit actors and the theatre trim, while the map looked merely slightly flat. Fixed by updating materials **in place** (`delete_all_material_expressions` then rebuild the graph) instead of delete+create. Also fixed 53 duplicated kit actor labels (both shop piers of a bay shared one name). New `Tools/ue_audit_scene.py` gates the chain on: every mesh actor has a material, every verified frontage span is within ±1 m, no duplicate labels — wired into `render_screenshots.sh`, which now runs the staging chain in the correct order and fails on an audit failure. Scene audit: **0 failures**.
- [x] **Re-measure 1440p performance** with 625 kit actors and 8 generated textures in the map. **Done 2026-11-09:** 2.76 ms average (363 fps), p99 3.64 ms at 2560×1440, Epic preset, TSR, VSync off, no frame generation — about **12 %** more frame time than `0.1.0` (2.42 ms / 414 fps) and still ~6× the 60 fps floor. Recorded in `Docs/release-checks.md`; series at `Docs/perf/0.1.5-kit-walk-frametimes.csv`. Note: runs showing ~105 fps were two overlapping game instances, not the build.
- [ ] Tag `v0.1.5` and write `CHANGELOG.md` entry; then remove this section.

## 0.2.0 — MPFB player body, third-person camera, basic animation (weeks 7–9)

### Character setup

- [x] Generate MPFB human base mesh; export baked materials and deform skeleton. Done in bootstrap: idle-pose 19 158-vert human with a 137-bone standard rig, `Tools/mpfb_character_export.py` (now `--pose idle` + warm `make_diffuse`).
- [x] Import character into Unreal; validate skeleton, scale, and materials. Done: `/Game/Test/Character` — `SkeletalMesh` (138 bones), `Skeleton`, warm `M_Character_Export` material with baked `T_Character_Diffuse`.
- [x] Promote the character asset into a reusable NPC prefab (visible body, collision capsule, idle pose) ready for pedestrians (`0.5.0`) once the third-person body lands. Done 2026-11-07: `AGigLineNPCPerson` (see the 0.1.0 Character-development item); `0.5.0` reuses it as the pedestrian base.
- [ ] Create basic idle/walk animation set.
- [ ] Verify animation plays correctly on the imported rig.

### Camera and controls

- [ ] Add third-person camera following the player body.
- [ ] Add first/third-person toggle.
- [ ] Add camera collision to prevent clipping through geometry.
- [ ] Document any input changes.

### Release checks

- [ ] Third-person traversal works end-to-end in the demo area.
- [ ] No blocking animation or rig defects.
- [ ] Performance target still met at 1440p.
- [ ] Tag `v0.2.0` and write `CHANGELOG.md` entry; then remove this section.

## 0.2.1 — Rig fixes (patch)

### Patch tasks

- [ ] Fix skeletal/rigging defects reported after `0.2.0`.
- [ ] Tag `v0.2.1` and write `CHANGELOG.md` entry; then remove this section.

## 0.2.2 — Skin and hair tuning (patch)

### Patch tasks

- [ ] Tune skin shading and hair materials on the player character.
- [ ] Tag `v0.2.2` and write `CHANGELOG.md` entry; then remove this section.

## 0.2.3 — Camera clipping fixes (patch)

### Patch tasks

- [ ] Fix remaining camera clipping cases in `0.2.x`.
- [ ] Tag `v0.2.3` and write `CHANGELOG.md` entry; then remove this section.

## 0.3.0 — Chaos vehicle, enter/exit, closed driving route (weeks 10–13)

### Vehicle production

- [ ] Model one vehicle in Blender with collision meshes; export to Unreal.
- [ ] Set up Chaos Vehicle with wheel and physics configuration.
- [ ] Implement enter/exit interaction.
- [ ] Build a closed driving route with boundaries.
- [ ] Tune basic handling to a drivable state.

### Release checks

- [ ] Player can enter, drive the closed route, and exit without defects.
- [ ] No blocking vehicle collision or packaging defects.
- [ ] Performance target still met at 1440p.
- [ ] Tag `v0.3.0` and write `CHANGELOG.md` entry; then remove this section.

## 0.3.1 — Handling tuning (patch)

### Patch tasks

- [ ] Refine vehicle handling feel based on `0.3.0` feedback.
- [ ] Tag `v0.3.1` and write `CHANGELOG.md` entry; then remove this section.

## 0.3.2 — Vehicle collision fixes (patch)

### Patch tasks

- [ ] Fix vehicle collision defects (mesh/physics mismatches).
- [ ] Tag `v0.3.2` and write `CHANGELOG.md` entry; then remove this section.

## 0.3.3 — Input fixes (patch)

### Patch tasks

- [ ] Fix vehicle/character input issues in `0.3.x`.
- [ ] Tag `v0.3.3` and write `CHANGELOG.md` entry; then remove this section.

## 0.4.0 — Small connected neighborhood and map streaming (weeks 14–17)

### World expansion

- [ ] Extend geo pipeline to a small connected neighborhood beyond the demo block.
- [ ] Produce modular buildings, sidewalks, and roads for the expanded area.
- [ ] Set up World Partition with streaming cells.
- [ ] Configure HLOD for distant buildings.
- [ ] Verify no seams or popping between streamed cells during traversal.

### Release checks

- [ ] Continuous walking (and driving) across the expanded area works.
- [ ] Streaming does not introduce blocking defects.
- [ ] Performance target re-validated at 1440p with streaming active.
- [ ] Tag `v0.4.0` and write `CHANGELOG.md` entry; then remove this section.

## 0.4.1 — Seam fixes (patch)

### Patch tasks

- [ ] Fix visible seams between streamed cells.
- [ ] Tag `v0.4.1` and write `CHANGELOG.md` entry; then remove this section.

## 0.4.2 — Streaming corrections (patch)

### Patch tasks

- [ ] Correct streaming/loading issues found in `0.4.x`.
- [ ] Tag `v0.4.2` and write `CHANGELOG.md` entry; then remove this section.

## 0.4.3 — HLOD tuning (patch)

### Patch tasks

- [ ] Tune HLOD quality and distance settings.
- [ ] Tag `v0.4.3` and write `CHANGELOG.md` entry; then remove this section.

## 0.5.0 — Pedestrians, crosswalk behavior, ambient traffic (weeks 18–21)

### Simulation

- [ ] Add pedestrian characters with navigation, using `AGigLineNPCPerson` (the reusable NPC prefab) as the base, driving it via AI/`AutoPossessAI`.
- [ ] Implement crosswalk behavior (pedestrians use the designated crossing).
- [ ] Add limited ambient traffic on the street network.
- [ ] Optimize simulation cost to stay within frame budget.

### Release checks

- [ ] Pedestrians and traffic behave without blocking defects.
- [ ] Performance target re-validated at 1440p.
- [ ] Tag `v0.5.0` and write `CHANGELOG.md` entry; then remove this section.

## 0.5.1 — Navigation fixes (patch)

### Patch tasks

- [ ] Fix pedestrian navigation issues.
- [ ] Tag `v0.5.1` and write `CHANGELOG.md` entry; then remove this section.

## 0.5.2 — Crossing fixes (patch)

### Patch tasks

- [ ] Fix crosswalk behavior defects.
- [ ] Tag `v0.5.2` and write `CHANGELOG.md` entry; then remove this section.

## 0.5.3 — Simulation optimization (patch)

### Patch tasks

- [ ] Optimize pedestrian/traffic simulation cost.
- [ ] Tag `v0.5.3` and write `CHANGELOG.md` entry; then remove this section.

## 0.6.0 — Visual/audio pass and evening lighting preset (weeks 22–24)

### Look and sound

- [ ] Create an evening lighting preset.
- [ ] Complete a visual polish pass across the neighborhood.
- [ ] Add ambient audio (city ambience, traffic, basic SFX).
- [ ] Verify licenses for all added audio files.

### Release checks

- [ ] Both day and evening presets render without defects.
- [ ] Audio plays without gaps or licensing issues.
- [ ] Performance target re-validated at 1440p.
- [ ] Tag `v0.6.0` and write `CHANGELOG.md` entry; then remove this section.

## 0.6.1 — Lighting fixes (patch)

### Patch tasks

- [ ] Fix lighting defects in day/evening presets.
- [ ] Tag `v0.6.1` and write `CHANGELOG.md` entry; then remove this section.

## 0.6.2 — Material corrections (patch)

### Patch tasks

- [ ] Fix material errors found in `0.6.x`.
- [ ] Tag `v0.6.2` and write `CHANGELOG.md` entry; then remove this section.

## 0.6.3 — Audio balancing (patch)

### Patch tasks

- [ ] Balance audio levels across the scene.
- [ ] Tag `v0.6.3` and write `CHANGELOG.md` entry; then remove this section.

## 0.7.0 — Settings, control rebinding, save/load, accessibility (weeks 25–27)

### Systems

- [ ] Build settings menu (graphics and audio options).
- [ ] Implement control rebinding with persistence.
- [ ] Implement save/load for player state.
- [ ] Add accessibility basics (e.g. FOV, subtitle, colorblind options as applicable).

### Release checks

- [ ] Settings, rebinding, and save/load all persist across restarts.
- [ ] No blocking UI defects.
- [ ] Tag `v0.7.0` and write `CHANGELOG.md` entry; then remove this section.

## 0.7.1 — Save fixes (patch)

### Patch tasks

- [ ] Fix save/load defects.
- [ ] Tag `v0.7.1` and write `CHANGELOG.md` entry; then remove this section.

## 0.7.2 — UI fixes (patch)

### Patch tasks

- [ ] Fix UI issues in `0.7.x`.
- [ ] Tag `v0.7.2` and write `CHANGELOG.md` entry; then remove this section.

## 0.7.3 — Input persistence fixes (patch)

### Patch tasks

- [ ] Fix rebinding persistence issues.
- [ ] Tag `v0.7.3` and write `CHANGELOG.md` entry; then remove this section.

## 0.8.0 — Performance budgets and broader Linux hardware testing (weeks 28–30)

### Performance

- [ ] Define performance budgets (frame time, VRAM) and document them.
- [ ] Profile the full neighborhood; fix budget violations.
- [ ] Test on broader Linux hardware and VRAM configurations; document results.
- [ ] Re-validate the 1440p quality preset with upscaling state recorded.

### Release checks

- [ ] Performance budgets met on documented hardware matrix.
- [ ] No blocking compatibility defects.
- [ ] Tag `v0.8.0` and write `CHANGELOG.md` entry; then remove this section.

## 0.8.1 — VRAM reductions (patch)

### Patch tasks

- [ ] Reduce VRAM usage where profiling shows excess.
- [ ] Tag `v0.8.1` and write `CHANGELOG.md` entry; then remove this section.

## 0.8.2 — Frame-time fixes (patch)

### Patch tasks

- [ ] Fix frame-time spikes found in `0.8.x`.
- [ ] Tag `v0.8.2` and write `CHANGELOG.md` entry; then remove this section.

## 0.8.3 — Compatibility fixes (patch)

### Patch tasks

- [ ] Fix compatibility issues from the hardware testing matrix.
- [ ] Tag `v0.8.3` and write `CHANGELOG.md` entry; then remove this section.

## 0.9.0 — Feature freeze, public beta, license and build audit (weeks 31–34)

### Freeze and audit

- [ ] Freeze features; document the freeze in `CHANGELOG.md`.
- [ ] Produce a public beta build for testers.
- [ ] Complete license audit: `THIRD_PARTY_NOTICES.md`, all MPFB assets, textures, animations, vehicles, audio.
- [ ] Review Epic distribution requirements before publishing.
- [ ] Verify a fresh checkout builds and packages reproducibly.

### Release checks

- [ ] Beta feedback triaged; blockers logged for `0.9.x`.
- [ ] Tag `v0.9.0` and write `CHANGELOG.md` entry; then remove this section.

## 0.9.1 — Blocker fixes (patch)

### Patch tasks

- [ ] Fix blockers reported during the public beta.
- [ ] Tag `v0.9.1` and write `CHANGELOG.md` entry; then remove this section.

## 0.9.2 — Regression fixes (patch)

### Patch tasks

- [ ] Fix regressions introduced by `0.9.x` fixes.
- [ ] Tag `v0.9.2` and write `CHANGELOG.md` entry; then remove this section.

## 0.9.3 — Documentation fixes (patch)

### Patch tasks

- [ ] Update all `Docs/` for accuracy before `1.0.0`.
- [ ] Tag `v0.9.3` and write `CHANGELOG.md` entry; then remove this section.

## 1.0.0 — Stable neighborhood-scale walking/driving release (weeks 35–40)

### Final release

- [ ] Complete final acceptance sweep across all `0.x` features.
- [ ] Confirm the stable, agreed game scope is met (neighborhood-scale walking and driving).
- [ ] Final build, documentation, and licensing verification.
- [ ] Tag `v1.0.0` and write `CHANGELOG.md` entry; then remove this section.