gig-line/TODO.md

TODO.md

Actionable task list for this project. Planned work and progress marks live here; supporting observations are in MEMORY.md. 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.
• Every task section carries a **Suggested skills:** line naming the packs to load before starting. Load them with the skill tool — blender-director for asset pipelines, ue-project-context for engine work, then the packs named — and use them as method guides, since this project runs Blender and Unreal headless from scripts.

Toolchain — end-to-end asset check (done 2026-11-10)

[!IMPORTANT] Plan for 0.3.1 before other patches

See toolchain notes.

Suggested skills: no pack covers the local ComfyUI, judge or driver tooling — work from Tools/README.md, Tools/review/ and the toolchain notes in MEMORY.md.

• Group the sixty tools by sandbox: Tools/unreal/, Tools/blender/, Tools/review/, Tools/gen/, Tools/input/, with the layout documented in Tools/README.md.
• Empty both maps and verify that no actors remain using Tools/unreal/ue_recreate_maps.py.
• Clear the whole level in both builders.
• Two-model judge with reconciliation, and a two-checkpoint texture generator that compares before choosing.
• Texture generation through the documented Stability Matrix workflows (texture subcommand).
• Local ComfyUI documented, including "start Stability Matrix first" and the per-model licence rules.
• Driver hardening: unlink result files before each step, stream child output to a per-step log, refuse to start while another editor is alive.
• Make the judge useful again.
  • Examine comfyui tool to extend judge coverage or improve its scoring mechanism.
• Wire the e2e driver into the release checks once the judge can be trusted.

Vehicle physics — Chaos rig (own task, from 0.3.0)

[!IMPORTANT] Plan for 0.3.1 before other patches

See historical notes.

Tasks

Suggested skills: ue-physics-collision, ue-module-build-system (plugin enablement), ue-actor-component-architecture, ue-gameplay-framework, ue-input-system, ue-testing-debugging, cpp; Blender side vehicle-artist, collision-proxy, export-pipeline, unreal-export. No pack covers Chaos Vehicles — the notes in this section and the ChaosVehiclesPlugin headers are the reference.

• Give SK_Vehicle_Sedan a physics asset whose single chassis body matches the car's box. Resolved 2026-11-10 — two causes, both fixed: ChaosVehiclesPlugin was not enabled in .uproject, so CreateVehicle() never ran (0 wheels); and BuildPhysicsAsset never set Body->PhysicsType, so the body stayed PhysType_Default (follow owner) and never simulated. Enabling the plugin (5e328f5) and setting PhysicsType = PhysType_Simulated (927e937) make the pawn simulate, settle at Z 77 cm, and drive (-drivetest moved 36.3 m).
• Find what writes the actor transform in DemoMap but not in ReviewMap. Resolved — it was never a transform writer: the body was not simulating (see above), so the "float" and "teleport" were the unsimulated chassis being driven by the regular rigid-body solver instead of the Chaos async solver.
• Confirm Wheels.Num() becomes 4 once the vehicle is created; log it at the settle check. 4 wheels once the plugin is enabled (setups=4 wheels=4).
• Re-stage the pawn, re-add enter/exit and the driving route. Drives backwards (-96.5 km/h): the next bug is the reverse direction — rear wheels bAffectedByEngine, engine torque sign, or wheel bone axle orientation — not the physics setup.

Hero facade rework — from the ReviewMap review (own task)

See historical notes.

Tasks

Suggested skills: blender-director, archviz, historical-worlds, realistic-style, hard-surface (relief and mouldings), materials, texture-workflow, uv-workflow, lookdev, rendering, camera-cinematography, references (visual-match checklist), qa-review; engine side ue-materials-rendering.

• Confirm the hero captures frame Hero_Facade.
• Seat the elevation detail in front of the mass.
• Remove the blank lintel band across the portals.
• Add window grilles, ashlar courses, and a roof balustrade.
• Warm the sandstone material in the engine.
• Match banner proportions and placement to the photographs.
• Make the generated ashlar albedo render.
• Add the carved inscription.
• Add medallion relief that reads at 45 m.
• Fix the motto band and surround.
• Add JIMMY KIMMEL LIVE banner lettering.
• Adjust the crimson banner tone and lettering.
• Re-render the three ReviewMap staging shots and update the status table.
• Obtain owner approval for the three hero facade staging shots.

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)

See vehicle production notes.

Suggested skills: blender-director, vehicle-artist, hard-surface, materials, uv-workflow, collision-proxy, lod-pipeline, asset-optimization, export-pipeline, unreal-export (against ue_metric_v1); engine side ue-project-context first, then ue-physics-collision, ue-actor-component-architecture, ue-gameplay-framework, ue-input-system, ue-character-movement (enter/exit), ue-world-level-streaming (route bounds), ue-testing-debugging, cpp.

• [A] Model one vehicle in Blender with collision meshes; export to Unreal.
• [D] Set up Chaos Vehicle with wheel and physics configuration.
• Fix the vehicle not rendering in the scene.
• Fix the character and car floating.
• Fix the vehicle material colour.
• Fix the missing vehicle glazing.
• Reconcile the road and sidewalk surfaces.
• Wire the vehicle LOD group in an editor session.
• 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

Suggested skills: ue-physics-collision, ue-input-system, ue-actor-component-architecture, ue-testing-debugging, cpp; vehicle-artist only if the fix is visual mass or wheel placement.

• 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

Suggested skills: collision-proxy, vehicle-artist, asset-optimization, export-pipeline, unreal-export, ue-physics-collision, ue-testing-debugging.

• 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

Suggested skills: ue-input-system, ue-character-movement, ue-gameplay-framework, ue-blueprint-cpp-interop, ue-testing-debugging.

• 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

Suggested skills: blender-director, environment-artist, procedural-modeling, geometry-nodes, archviz, scene-assembly, asset-optimization, lod-pipeline, uv-workflow, materials, export-pipeline, unreal-export; engine side ue-project-context first, then ue-world-level-streaming, ue-procedural-generation, ue-async-threading, ue-materials-rendering, ue-testing-debugging, cpp.

• 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

Suggested skills: ue-world-level-streaming, asset-optimization, environment-artist, ue-testing-debugging.

• 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

Suggested skills: ue-world-level-streaming, ue-async-threading, ue-testing-debugging.

• 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

Suggested skills: lod-pipeline, ue-world-level-streaming, asset-optimization, ue-testing-debugging.

• 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

Suggested skills: ue-project-context first, then ue-ai-navigation, ue-character-movement, ue-actor-component-architecture, ue-gameplay-framework, ue-state-trees, ue-mass-entity (crowd scale), ue-async-threading, ue-testing-debugging; the AGigLineNPCPerson prefab is Blender work — character-artist, rigging, animation, export-pipeline, unreal-export.

• 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

Suggested skills: ue-ai-navigation, ue-physics-collision, ue-testing-debugging.

• 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

Suggested skills: ue-ai-navigation, ue-state-trees, ue-gameplay-tags-messaging, ue-testing-debugging.

• 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

Suggested skills: ue-mass-entity, ue-async-threading, ue-testing-debugging, asset-optimization, lod-pipeline.

• 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

See pavement notes.

Suggested skills: lighting, rendering, lookdev, materials, texture-workflow, archviz, environment-artist, blender-director, references (visual-match checklist), qa-review; engine side ue-materials-rendering, ue-niagara-effects, ue-audio-system, ue-gameplay-cameras, ue-testing-debugging.

• Create an evening lighting preset.
• Complete a visual polish pass across the neighborhood.
• Model the pavement between kerb and building line.
• 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

Suggested skills: lighting, lookdev, rendering, references, qa-review, ue-materials-rendering.

• 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

Suggested skills: materials, texture-workflow, lookdev, qa-review, ue-materials-rendering.

• 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

Suggested skills: ue-audio-system, ue-testing-debugging.

• 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

Suggested skills: ue-project-context first, then ue-ui-umg-slate, ue-input-system, ue-serialization-savegames, ue-data-assets-tables, ue-gameplay-framework, ue-blueprint-cpp-interop, cpp, ue-testing-debugging.

• 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

Suggested skills: ue-serialization-savegames, ue-testing-debugging, cpp.

• 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

Suggested skills: ue-ui-umg-slate, ue-testing-debugging.

• 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

Suggested skills: ue-input-system, ue-serialization-savegames, ue-testing-debugging.

• 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

Suggested skills: ue-testing-debugging (Unreal Insights, stat unit, memreport), asset-optimization, lod-pipeline, ue-materials-rendering (scalability and upscaler state), ue-async-threading, ue-world-level-streaming, ue-niagara-effects, cpp.

• 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

Suggested skills: ue-materials-rendering (texture streaming, LOD bias), asset-optimization, texture-workflow, lod-pipeline, ue-testing-debugging.

• 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

Suggested skills: ue-testing-debugging, ue-async-threading, ue-niagara-effects, asset-optimization, lod-pipeline.

• 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

Suggested skills: ue-testing-debugging, ue-module-build-system (build and package differences), ue-materials-rendering (GPU and driver-specific paths).

• 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)

See realistic building notes.

Façade system

Suggested skills: blender-director, archviz, historical-worlds, realistic-style, procedural-modeling, geometry-nodes, hard-surface, materials, texture-workflow, uv-workflow, asset-optimization, lod-pipeline, export-pipeline, unreal-export, references, qa-review; engine side ue-materials-rendering.

• 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. Make painted wall lettering, blade signs and fascia panels texture and decal work with a documented projection.
• Document the system in Art/blender/README.md and the arc42 building block view.

Per-building models

Suggested skills: references (reference-image-match and visual-match), camera-cinematography (match the photograph's angle before detail), archviz, historical-worlds, realistic-style, blender-modeler, hard-surface, prop-artist (street-level details), materials, texture-workflow, uv-workflow, qa-review, blender-director.

• Use a building-specific reference set for each building; retain blockouts and record buildings without references.

• Hero façade (6840): add volute capital depth, lattice grille depth, window rhythm behind the colonnade, and heavy banded rustication.

• Hero façade (6840), entrance: add doors at street level left and right of the central bay and position the column bases, entrance stairs, set-back entrance, door frames, banners and signage correctly. Keep the façade unobstructed, with no awning or temporary structure.

• 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: add wall lettering as a decal, a moulded parapet profile, richer corner-tower stepping, and portrait panel textures.

• Acquire references for 6822 Budget and record the sources checked in Geo/; retain its bare blockout until references are acquired.

• Re-shoot 6806–6820 and 6800 from the south sidewalk.

• 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

Suggested skills: materials, texture-workflow, uv-workflow, lookdev, rendering, collision-proxy, lod-pipeline, asset-optimization, ue-materials-rendering, ue-testing-debugging.

• Measured material library, including the hero's stone: 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

Suggested skills: ue-project-context (refresh before the audit), ue-module-build-system (reproducible build), ue-testing-debugging, qa-review, de-ai-writing (Docs/ prose).

• 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

Suggested skills: ue-testing-debugging plus the pack for the subsystem each blocker lives in (see the mapping in AGENTS.md); cpp for non-engine code.

• 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

Suggested skills: ue-testing-debugging, plus the owning subsystem's pack, and cpp where the regression is in game code; check MEMORY.md for how the original defect was found.

• 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

Suggested skills: de-ai-writing (prose), ue-project-context (verify the project facts it records), ue-module-build-system (verify the build and checkout steps documented).

• 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

Suggested skills: qa-review, references (final visual-match sweep), ue-testing-debugging, de-ai-writing (Docs/), ue-project-context refresh.

• 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.