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.3.0 — Chaos vehicle, enter/exit, closed driving route (weeks 10–13)

Vehicle production - active - session-5598ce7e-27e3-4c64-bb49-c04a4a31ee58 (branch vehicle-0.3.0)

• [A] Model one vehicle in Blender with collision meshes; export to Unreal. Model done (Tools/vehicle_build.py → Art/blender/vehicle/gigline-sedan.blend, preview in Art/blender/vehicle/preview.png): 4.72 x 1.80 x 1.44 m, 2.78 m wheelbase, 1.62 m track, 0.33 m wheels, 252 triangles, four UCX_ convex hulls. Dimensions come from real sedan figures and are logged to the report, so the vehicle config can read them rather than restating them. - Imported into Unreal (Tools/ue_vehicle_import.py → /Game/Hollywood/Vehicle), split per the vehicle-artist object split: SM_Vehicle_Body (3 slots, 4.76 x 1.76 x 1.28 m), SM_Vehicle_Glass, SM_Vehicle_Light_Front, SM_Vehicle_Light_Rear, SM_Vehicle_Mirrors, and one SM_Vehicle_Wheel (0.22 x 0.66 x 0.66 m) reused four times. The body FBX carries the UCX_ hulls as simple collision.
  • LODs cut for real: decimating the duplicate gives LOD1 at 38 triangles and LOD2 at 14, against 132 for LOD0. The first attempt duplicated the shell unchanged and produced 84-triangle LODs that saved nothing - worth remembering as the failure mode of a "LOD" step nobody measures.
  • LOD group wiring is open: StaticMeshEditorSubsystem.import_lod is unavailable in a headless commandlet (get_editor_subsystem returns None), so the LOD meshes import as their own assets and the group still needs an editor session.
• [~] Set up Chaos Vehicle with wheel and physics configuration. It sits on the road now; it does not drive yet.
  • Fixed the floating: the physics asset had a body per bone, and the four wheel bodies intersected the chassis body and pushed the car 3.7 m up. It is now a single chassis body on the root bone (452 x 205 x 40 cm), which is what Unreal's own vehicle template uses - Chaos simulates the wheels itself, they must not be separate rigid bodies. Settle check: Z 119 cm at a spawn of 120 (was 494).
  • Drive test fails, with a specific cause: -drivetest holds full throttle for 3 s and reports speed and distance. Result: speed=0 cm/s, travelled 2.2 m -> FAIL, and BeginPlay logs 0 wheel objects after register while the component reports 4 wheel setups. The setups exist but no wheels are created from them, so there is nothing to apply torque to.
  • Next: confirm the skeleton's bone names match the setups (Wheel_FL, Wheel_FR, Wheel_RL, Wheel_RR) - a name mismatch silently produces zero wheels - and give the front and rear pairs their own UChaosVehicleWheel subclasses rather than the base class, which is what the setups point at today.
  • Also open: LOD group wiring, enter/exit, driving route, handling.
• Fix the vehicle not rendering in the scene. Chased to a strong clue, not yet solved. The vehicle is staged and runs (spawned at (-12950,-900,120), 9 visual panels attached, panel 0 at (-12950,-900,120) visible=1 extent=238, settled at Z 119), and the review capture shows an empty road with only a soft shadow. Tools/visual_loop.py --verify passes the frame; Tools/judge_screenshot.py returns verdict=no confidence=1.0. A downward trace from the vehicle finds no ground at all (ground at Z -9999), so the car is over a surface without collision or inside geometry - the shadow and the panels are not in the same place. Fixed 2026-11-09 — the car renders, built from the owner's hot hatch.blend. Fixed: the vehicle was spawned 2.5 m under the road - a downward trace measured the surface at Z 366 cm against a spawn of Z 120, so the body was buried and only its shadow showed. The spawn is now Z 470 and it settles there.
  • Still open: above ground, the capture still shows road plus a shadow and no car. Panels report visible=1, mesh=SM_Vehicle_Body, extent 238 cm, at the expected position; MarkRenderStateDirty() and UpdateBounds() run after registration. Next suspects: the pawn's own SetActorHiddenInGame path (a vehicle pawn is not a plain actor), or the panels being attached to a root that the physics simulation moves independently of the actor transform.
• Fix the character and car floating. Character: the player start at Z 600 left the soles 39 cm in the air (the capsule settles at 561 on this pavement); the start is now the measured 561. Car: the template's lowest geometry is exhaust, so grounding on the whole model put the tyres 4 cm above the origin - it is now grounded on its wheels, staged at Z 342 after the traced road height (366) disagreed with the visible road by ~25 cm.
• Fix the vehicle's material colour. The template's car paint is a legacy mix-shader graph that the FBX exporter cannot map, so SM_Vehicle_Body imported holding WorldGridMaterial and rendered black while Blender showed red. Legacy graphs are now converted to Principled before export (saturated colour wins over the grey diffuse next to it), and the staged body panel is assigned M_Vehicle_HatchPaint. Judge: verdict=yes confidence=0.9.
• Fix the missing vehicle glazing. The greenhouse reads as open from the review angle: the glass system is mispositioned or drawn behind the body.
• 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.
• Model the pavement between kerb and building line; today that strip is the terrain mesh, which reads as bare ground under the shopfronts (Screenshots/README.md). Carried over 2026-11-09.
• 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 — Realistic buildings (weeks 31–34)

Suggested blender skills: archviz (real-world scale, façade composition, elevation read), references (reference-image-match and visual-match checklists — every building is judged against its own photograph), procedural-modeling + geometry-nodes (the façades system: bay module, cornice and coping profiles, storefront types as reusable node groups), materials (measured albedo and roughness per surface type), texture-workflow (baked AO/curvature/normal, decals for painted lettering and signs), uv-workflow (texel density and modular UVs), lod-pipeline (LOD chain per building), collision-proxy (UCX proxies so detail geometry is not the collider), lookdev (screenshot comparison loop), camera-cinematography (reproducing each building's reference angle), asset-optimization + unreal-export (pre-export validation, ue_metric_v1), qa-review (the gate before every review shot).

Façade system

• Extend the module kit beyond one order. Art Deco, neoclassical and streamline-moderne variants on the shared 4.96 m bay: alternate window proportions, spandrel and transom bands, and the way each order terminates at the roof.
• Build a profile library for cornices, copings, string courses, sills and storefront surrounds, so a building is assembled from named profiles rather than ad-hoc boxes.
• Storefront types: recessed entry, bulkhead and kickplate, mullion spacing, transom, awning/canopy brackets, and grille/shutter variants.
• Signage and lettering as decals. Painted wall lettering, blade signs and fascia panels become texture and decal work with a documented projection; 0.1.6 proved that lettering built as geometry plates cannot resolve at review distance.
• Document the system in Art/blender/README.md and the arc42 building block view.

Per-building models

Each building needs its own reference set; where none exists the blockout stays and the item says so.

• Hero façade (6840): raise to this pass's detail level — capitals and fluting, window rhythm behind the colonnade, parapet motto band and medallions.
• Hero façade (6840), entrance: doors at street level left and right of the central bay, as the photographs show, and correct positioning of the central-bay elements (column bases, entrance stairs, set-back entrance, door frames, banners and signage). Nothing may stand in front of the façade that blocks it — no awning, no temporary structure. Carried over from Screenshots/README.md, 2026-11-09.
• El Capitan Theatre (6838): marquee, blade sign, entrance and the theatre's own elevation from its 18-frame set.
• 6800 Lee Drug and 6806–6820: second pass on the 0.1.6 trim. Moved here from that patch because geometry cannot close them: wall lettering as a decal (a plate at 0.10 m still vanishes at 40 m), a moulded parapet profile instead of a two-tier box, richer corner-tower stepping, and the portrait panels reworked as textures rather than framed plates.
• Photography gap — 6822 Budget (deferred out of 0.1.6, blocked): no photograph exists; the single-storey 6.0 × 5.5 m volume cannot be read from the neighbour shot, so it stays a bare blockout until references are acquired. Record the sources checked in Geo/. Also re-shoot 6806–6820 and 6800 from the south sidewalk: the only reference is one oblique with a bus across Lee Drug's shopfront and a car across 6806's.
• 6902, 6922 and the remaining south frontage.
• North side: TCL Chinese Theatre and Madame Tussaud's façades from their reference sets.
• Reconcile every modelled height against Geo/tools/block_height_report.py and record the source per building.

Materials, UVs and performance

• Measured material library, including the hero's stone, which currently renders pale because it is a procedural graph and a generated texture set rather than a measured surface: stucco, painted render, ashlar, brick, terrazzo, glazing, bronze and steel trim, with albedo and roughness taken from the photographs rather than guessed; one Unreal material instance per surface type.
• Texel-density rule per building class, applied through modular UVs; lightmap UVs where required.
• LOD chain and collision proxies per building: UCX proxies for blocking volume, detail geometry non-colliding.
• Re-validate the 60 FPS floor at 1440p once the detail lands, and record the cost of the pass.

Release checks

• Every building with a photograph has a review shot measured against it, with silhouette and proportion deltas recorded in Screenshots/README.md.
• No building carries an unverified façade; blockouts without references are listed as such in TODO.md.
• Every building has a collision proxy and at least one LOD.
• No surface left on a placeholder material.
• THIRD_PARTY_NOTICES.md covers every photographic reference used in this pass.
• Performance target still met at 1440p.
• Tag v0.9.0 and write CHANGELOG.md entry; then remove this section.

0.10.0 — Feature freeze, public beta, license and build audit (weeks 35–38)

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.10.x.
• Tag v0.10.0 and write CHANGELOG.md entry; then remove this section.

0.10.1 — Blocker fixes (patch)

Patch tasks

• Fix blockers reported during the public beta.
• Tag v0.10.1 and write CHANGELOG.md entry; then remove this section.

0.10.2 — Regression fixes (patch)

Patch tasks

• Fix regressions introduced by 0.9.x fixes.
• Tag v0.10.2 and write CHANGELOG.md entry; then remove this section.

0.10.3 — Documentation fixes (patch)

Patch tasks

• Update all Docs/ for accuracy before 1.0.0.
• Tag v0.10.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.