gig-line/ROADMAP.md

# ROADMAP.md

Living roadmap for this project. This file is the single source of truth for current progress.

## Status at a glance — 2026-11-07 08:50

Workstation and geo pipeline are done and verified. The art pipeline has a first blockout, terrain, and street in metres, in one shared coordinate frame. Unreal 5.8.4 is installed and starts headlessly; no project exists yet.

| Area | State |
| --- | --- |
| Workstation | Bazzite `45.20261105`, driver `615.78.08`, Vulkan good, `git-lfs`/`clang`/`cmake`/`ninja` installed |
| Tooling | Blender 5.2 + MPFB 2.0.18 + Blosm 2.7.28 working headless; QGIS 4.2.3; PROJ 9.9.0; Unreal 5.8.4 installed |
| Geo | extract, address + footprints + bounds, CRS + origin, 3DEP DEM, street profile, cross-sections — all verified and committed |
| Engine | 5.8.4 extracted, headless `-NullRHI` init passes, Vulkan RHI unproven |
| Blender | blockout (87 meshes), terrain, street (road/kerbs/sidewalks), site assembly — all in one frame, walk-checked |
| Reference | 72 images local, uncommitted; hero entrance located; inherited eight-step claim overturned |
| Unreal project | not created — C++ project, packaging, and imports all open |

**Open decisions:** code licence (MIT proposed); whether shipped builds carry a derived OSM database (ODbL posture).

## 0.1.0 — Local setup and walkable Hollywood block (weeks 1–6)

### Environment setup

Status detail in [Docs/setup.md](Docs/setup.md); workstation audit in [Docs/environment.md](Docs/environment.md); pins in [Docs/toolchain.md](Docs/toolchain.md).

- [x] Update Bazzite using its supported mechanism; verify NVIDIA driver and Vulkan operation.
- [x] Register an Epic account and accept the Unreal license; obtain a pinned Linux engine build or build from Epic's authorized source repository.
- [-] Validate Unreal runs on Bazzite before asset production (not an officially supported distribution). 5.8.4 fully extracted (73 GiB, CL 58902052, promoted build); headless smoke test passed 2026-11-07 (`UnrealEditor-Cmd -nullrhi -run=BlankProgram`, clean startup and shutdown). Editor GUI launch on Vulkan still pending.
- [-] Install the engine-required compiler/SDK, Git, Git LFS, and an editor; use Distrobox for isolated CLI dependencies where useful. clang 23.1.4 / cmake 4.3.0 / ninja 1.13.2 installed; verified 2026-11-07 that this engine build bundles no Linux clang, so the system compiler is the toolchain — final proof lands with the first C++ project compile.
- [-] Pin Blender, MPFB, Blosm, and QGIS versions; confirm add-on compatibility; record in `docs/toolchain.md`. Done: Blender 5.2.0 LTS, MPFB 2.0.18, Blosm 2.7.28 (imports headless on 5.2 in `3Dsimple`; two headless workarounds documented), QGIS 4.2.3 with PROJ 9.9.0, stale QGIS `lts` 3.28.9 uninstalled 2026-11-07, Unreal 5.8.4 recorded as pin in `Docs/toolchain.md`. Left: finalize the Unreal pin once the editor GUI launches.
- [x] Create repository structure (`Game/`, `Art/`, `Geo/`, `Tools/`, `Docs/`) with LFS tracking and ignore rules applied.
- [x] Keep project and Derived Data Cache on SSD storage; reserve several hundred GB for engine, assets, caches, builds.

### Project bootstrap

- [ ] Create a C++ Unreal project with Blueprint gameplay iteration and Enhanced Input.
- [ ] Package and launch a blank Linux build.
- [ ] Export one static mesh from Blender and import into Unreal; verify scale and materials.
- [ ] Export one MPFB character with baked materials and deform skeleton; verify import.
- [ ] Document initial setup in `Docs/`: engine install, project checkout, fresh-checkout build procedure.

### Geographic data

- [x] Save a versioned OSM extract; document date, bounds, and source in `Geo/`.
- [x] Acquire separately licensed elevation data if needed. Needed and acquired: USGS 3DEP 1 m DEM in EPSG:26911, public domain, NAVD88, 984 KB committed (`Geo/manifests/2026-11-06-3dep-dem.md`); measured relief 3.94 m.
- [x] Download the 3DEP 1 m DEM for the demo bounds, reproject it to EPSG:26911 with the recorded origin and vertical datum, and record the source, clip bounds, and checksum in `Geo/`.
- [x] In QGIS, set a suitable local projected CRS (e.g. EPSG:26911) and record a local origin. EPSG:26911, origin and projected easting/northing are recorded in `Geo/manifests/local-origin.md` with PROJ 9.9.0 control points; QGIS 4.2.3 is installed for the DEM reprojection step.
- [x] Verify the address, building footprints, and demo boundaries for 6840 Hollywood Blvd against source data.
- [-] Import OSM blockouts through Blosm; clean and detail them in Blender. Imported 2026-11-06 (`Art/blender/blockout/blockout-2026-11-06.blend`, 86 meshes, scale 1:1 against OSM, re-framed into EPSG:26911 with a 0.0 cm affine residual); cleaning and detailing not started.
- [ ] Preserve geographic coordinates in metadata; define explicit meter→centimeter conversion to local Unreal coordinates. The frame is defined (`Geo/manifests/local-origin.md`: EPSG:26911, origin Hollywood × Highland, X east / Y north / Z up, ×100 on export) and the Blender meshes already use it; the export preset and the asserted ×100 are not built yet.

### Asset production

- [ ] Establish a consistent scale test, named export presets, and repeatable import settings.
- [-] Collect reference photography for manual façade work. Local only, never committed: `Art/reference/` is gitignored. **72 images in eleven folders**: hero façades to 4k, the El Capitan Theatre exterior series, premiere-night staging, Ovation Hollywood, the north side, and the Lee Drug neighbour. Gaps largely closed by the Flickr/web-search pass: the hero entrance is now documented (three portals with individual short flights — the inherited "eight steps, 12 m wide" is overturned), and the 6806–6822 retail run appears in an oblique 2013 frame. Still missing: a clean isolated frame of the door recess and a night frame of 6840 itself.
- [x] Download reference photography for the two north-side buildings inside the 50 m buffer — TCL Chinese Theatre (OSM way 424105908, 6925 Hollywood Blvd) and Madame Tussaud's (way 424105889, 6933 Hollywood Blvd). Done 2026-11-06 with `Tools/commons_fetch.py` against the Wikimedia Commons API: eleven frames in the local `Art/reference/north-chinese/` and `Art/reference/north-tussauds/`, provenance in each `sidecar.json`, nothing committed.
- [ ] Model hero façade for the El Capitan Entertainment Centre site.
- [ ] Model surrounding block frontage.
- [ ] Model simplified background buildings directly across Hollywood Boulevard.
- [-] Build sidewalks, roads, and collision meshes. Terrain, road, sidewalks and kerbs exist (`Art/blender/terrain/`, `street/`) and are assembled in `site/site-2026-11-06.blend`; collision and details (crossing markings, kerb radii, aprons) are not built. Ground must follow the DEM: 3.94 m fall along the block, ~2 % crown between the gutters at ±10–11 m from the centreline, north sidewalk higher than south. Kerb height is an unresolved assumption — the DEM does not resolve it (`Geo/verification/2026-11-06-cross-sections.md`).
- [ ] Materials and look development for all exported assets.

### Gameplay

- [ ] First-person movement, mouse look, and Enhanced Input bindings.
- [ ] Collision, reset, and pause functionality.
- [ ] Walkable sidewalks and a designated street crossing. Crossing chosen: mid-block signalised crossing, OSM way 385648319, at 130 m along the block (`Geo/verification/2026-11-06-street-profile.md`).
- [ ] Fixed daytime lighting and basic ambience.
- [ ] Geographic attribution display ("© OpenStreetMap contributors" + license link).

### Release checks

- [ ] Player can traverse both sides of the demo without falling through geometry. Blender pre-check passes: 0 raycast holes along both sidewalks and the designated crossing; worst seam step 15.8 cm at the sidewalk's outer edge (`Art/blender/README.md`). Engine traversal still to be tested.
- [ ] Building placement, street scale, and site identity checked against references.
- [ ] No blocking collision or packaging defects.
- [ ] 60 FPS at 1440p on the dev workstation (Bazzite, Ryzen 7 7700X, 64 GB RAM, RTX 5070 Ti 16 GB) using a documented quality preset; record upscaling state; report performance without frame generation.
- [ ] Fresh project checkout builds with the documented external engine installation.
- [ ] Package Linux build with documented controls.
- [ ] Tag `v0.1.0` and write `CHANGELOG.md` entry; then remove this section.

## 0.1.1 — Collision fixes (patch)

### Patch tasks

- [ ] Audit and fix any collision gaps or fall-through geometry found in `0.1.0`.
- [ ] Regression-test traversal on both sides of the demo.
- [ ] Verify no new packaging defects.
- [ ] Tag `v0.1.1` and write `CHANGELOG.md` entry; then remove this section.

## 0.1.2 — Scale and façade corrections (patch)

### Patch tasks

- [ ] Correct building scale and street proportions flagged against references.
- [ ] Refine hero façade details where reference photography shows discrepancies.
- [ ] Tag `v0.1.2` and write `CHANGELOG.md` entry; then remove this section.

## 0.1.3 — Packaging and setup fixes (patch)

### Patch tasks

- [ ] Fix any packaging or build issues encountered in `0.1.x`.
- [ ] Update `Docs/` setup instructions for anything that changed.
- [ ] Tag `v0.1.3` 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

- [ ] Generate MPFB human base mesh; export baked materials and deform skeleton.
- [ ] Import character into Unreal; validate skeleton, scale, and materials.
- [ ] 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.
- [ ] 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 ODbL obligations for any distributed derived geographic database.
- [ ] 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.