gig-line/TODO.md

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.

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.2 — Scale and façade corrections (patch)

Suggested blender skills: references (reference-image-match and visual-match-checklist templates — measure the guessed heights and colonnade proportions against the photographs), archviz (real-world scale and façade composition discipline), camera-cinematography (reproduce the reference camera angles when comparing renders to photos).

Patch tasks - active - 01a1b26b-3c94-707f-9665-2f6b4a79b564 (branch scale-facade-0.1.2)

• Correct building scale and street proportions flagged against references. Mapbox adopted 2026-11-09. Geo/tools/mapbox_buildings.py merges our OSM heights with Mapbox's building data for the same footprints; after adopting its two findings the cross-check reports 66 match, 6 non-building, 0 disagreements. Adopted: LEVEL_HEIGHT 3.2 → 3.1 m (block_height_report.py, and the Blosm --level-height default), plus explicit HEIGHT_OVERRIDES (3.0 m) for the three rear building=yes/apartments structures Mapbox gives as single-storey. Blockout regenerated, frontage re-exported/re-imported, DemoMap rebuilt; packaged -qaselftest all PASS. Measured effect: 6922 42.1 → 39.1 m, El Capitan Theatre 20.0 → 20.5 m (both now ~1.9 m above their table height = roof mass).
• Refine hero façade details where reference photography shows discrepancies.
• Replace the placeholder heights. Resolved 2026-11-08 — they were never unknown buildings. The three "guessed" ways are not building volumes at all: 1360755125 and 1360755126 are building=roof at layer=1 (elevated canopies) and 1417995292 is amenity=shelter / shelter_type=public_transport (a transit shelter). The report defaulted them to "2 levels × 3.2 m" and produced the bogus 6.4 m. Geo/tools/block_height_report.py now classifies roof/shelter explicitly and reports 0 guessed heights: all 15 block volumes have a real height tag, a building:levels derivation, or are correctly excluded as non-building volumes. No photograph measurement was needed, and no frontage building was affected.
• Resolve the remaining unknown on the hero: the colonnade currently occupies about 45 % of the height against roughly 50–60 % in the photographs. Fix the vertical proportions. Fixed 2026-11-09. Measured baseline: colonnade (columns + capitals) 6.90 m of the 14.50 m envelope = 47.6 %, because the entablature (3.40 m) and parapet (2.20 m) left only 7.90 m for the order. Thinned both to 3.00 m and 1.80 m (Tools/hero_facade_build.py), which lifts the colonnade to 7.70 m = 53.1 % — inside the photographed 50–60 % band, with the 14.50 m envelope, the motto band and the medallions unchanged in position relative to the parapet. Hero rebuilt, re-imported (bounds 2604 × 1257 × 1450 cm) and re-rendered.
• Tag v0.1.2 and write CHANGELOG.md entry; then remove this section.

0.1.3 — Packaging and setup fixes (patch)

Suggested blender skills: export-pipeline and unreal-export (scale/pivot/normals/materials/collision verification) if any packaging defect traces back to the Blender export presets.

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.1.4 — Proper building façades (patch)

Suggested blender skills: procedural-modeling + geometry-nodes (the façade module kit — bay, pilaster, cornice, parapet, window, shopfront, door — as reusable node groups), archviz (real-world scale and façade composition), materials (procedural brick, concrete, stone, render, glass — the ported generators), texture-workflow (AO/curvature/normal bakes and decals for the motto band and medallions), uv-workflow (texel density and modular UV layouts for the kit), scene-assembly (assembling kit pieces onto the fifteen block buildings), lookdev (screenshot-comparison loop until shading reads correctly), historical-worlds or realistic-style (1920s Hollywood Blvd neoclassical direction), asset-optimization + unreal-export (pre-export validation, ue_metric_v1 preset), qa-review (final gate before the Tools/render_screenshots.sh review).

Patch tasks

• Finish the Blosm blockout cleaning/detailing (moved from the deferred 0.1.0 item). Import state: Art/blender/blockout/blockout-2026-11-06.blend (86 meshes, EPSG:26911, 0.0 cm affine residual) with cleaning tooling in Geo/tools/ and Art/blender/blockout/blosm_blockout.py. To do here: (a) untextured roofs/facades → Replace placeholder materials below; (b) Blosm setupScript façade styles → Give OSM buildings a façade style below; (c) the 3 of 15 buildings lacking height data are the 0.1.2 placeholder-heights item.
• Define the façade module. One set of reusable pieces (bay, pilaster, cornice, parapet, window, shopfront, door) at a fixed module, exported with the ue_metric_v1 preset so every building assembles from the same kit.
• Replace placeholder materials. Every blockout building currently carries Blender flat colours. Port the procedural generators from Tools/sibling_asset_audit.py's sibling project (brick_facade, seamless_concrete, asphalt) and add stone, render, and glass, then wire them through Unreal material instances.
• Give OSM buildings a façade style. Blosm exposes scene.blosm.setupScript (setup/neoclassical.py is the example) so a building can carry a real elevation instead of a plain extrusion. Build one style script for the south frontage and one for the north.
• Hero façade detail pass. Ionic capitals and fluting, the parapet motto band and medallions as geometry or decal, window rhythm behind the colonnade, and the three portal flights at their photographed proportions.
• El Capitan Theatre (6838) and the retail neighbours. Model from the 18-frame 5472×3648 reference set; the theatre shares the measured 4.96 m bay rhythm with the temple.
• Review every façade change with Tools/render_screenshots.sh before tagging.
• Tag v0.1.4 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. 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).
• 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.
• 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.