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 09:45

Workstation, geo pipeline, and engine validation are done. The art pipeline has a first blockout, terrain, and street in metres, in one shared coordinate frame. Project bootstrap is complete: Game/GigLine builds, packages, and both content-acceptance tests (static-mesh scale, MPFB skeletal character) pass. Remaining 0.1.0 work is geo detailing, asset production, gameplay, and release checks.

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 installed and validated: headless + Vulkan GUI editor launch pass on the RTX 5070 Ti
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	bootstrap complete: C++ project builds, blank Linux build packaged + launch-tested, scale test and MPFB skeletal character accepted

Next up: model the hero façade and block frontage from the reference set, then first-person traversal on the site terrain. Release gate: v0.1.0 is tagged only on the owner's explicit go-ahead once the release checks pass — not automatically when the checkboxes close.

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; workstation audit in Docs/environment.md; pins in Docs/toolchain.md.

• Update Bazzite using its supported mechanism; verify NVIDIA driver and Vulkan operation.
• 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). 2026-11-07: headless -NullRHI smoke test and full editor GUI launch with the Vulkan RHI passed — device NVIDIA GeForce RTX 5070 Ti, Vulkan loader 1.4.350, VULKAN_SM5, map check 0 errors. Only benign log noise (Android Turnkey status, telemetry DNS failures).
• 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; this engine build bundles no Linux clang, so the system compiler is the toolchain. Accepted 2026-11-07: the first C++ game-module compile and link (libUnrealEditor-GigLine.so) succeeded with system clang.
• 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, QGIS 4.2.3 with PROJ 9.9.0 (stale lts removed 2026-11-07), Unreal 5.8.4 finalized as pin after the editor GUI launch.
• Create repository structure (Game/, Art/, Geo/, Tools/, Docs/) with LFS tracking and ignore rules applied.
• 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. Created 2026-11-07 at Game/GigLine/GigLine.uproject (primary game module + default game mode, Enhanced Input plugin + input classes in Config/DefaultInput.ini); GigLineEditor target compiles clean with system clang (UBT: Result Succeeded).
• Package and launch a blank Linux build. 2026-11-07: UAT BuildCookRun (cook + build + stage + pak, Development config) succeeded in 56 s; 1.1 GiB archive at /run/media/system/DATA/Builds/GigLine (outside the repo, uncommitted). GigLine.sh launched on the desktop session, created a Vulkan swapchain, and rendered 759 frames across a 60 s test. Known minor: one handled PSOPrecache ensure fires at exit only; not blocking, watch it in 0.1.x.
• Export one static mesh from Blender and import into Unreal; verify scale and materials. 2026-11-07: calibration scene (three 1 m cubes at origin / +10 m east / +10 m north) exported from Blender with preset ue_metric_v1 (Tools/scale_test_export.py) and imported headless via Tools/ue_scale_test_import.py. Measured in UE: cubes exactly 100.00 cm, origin preserved, material imported. Axis mapping: east → +X, north → −Y, up → +Z (the Y mirror is inherent to the right-handed→left-handed conversion; importer handles winding).
• Export one MPFB character with baked materials and deform skeleton; verify import. 2026-11-07: MPFB 2.0.18 generated human (19 158 verts, 1.66 m tall) + standard rig with weights (137 bones) + v2 skin baked to a 1024² diffuse texture (Tools/mpfb_character_export.py, export preset ue_character_v1). Imported headless (Tools/ue_character_import.py) into /Game/Test/Character: SkeletalMesh + 138-bone Skeleton + Material with the baked Texture2D assigned to slot 0. Quirks recorded: 5.8 Interchange skips materials for skeletal FBX imports (finished in script); Blender 5.2 dropped the FBX armature_nla option; the baked image needs image.filepath set for FBX to reference it.
• Document initial setup in Docs/: engine install, project checkout, fresh-checkout build procedure. 2026-11-07: Docs/setup.md reconciled with reality (all engine/bootstrap items marked done with evidence); Docs/build.md completed with the fresh-checkout build, packaging, and headless-content-check procedures plus known engine quirks.

Geographic data

• Save a versioned OSM extract; document date, bounds, and source in Geo/.
• 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.
• 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/.
• 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.
• 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) and the ×100 conversion is now verified by the 2026-11-07 scale test, with the axis mapping recorded (north realizes as UE −Y). Left: build the production export preset for the actual site meshes using these settings.

Asset production

• Establish a consistent scale test, named export presets, and repeatable import settings. Scale test = the three-cube calibration scene (Art/blender/scaletest/, regenerable via Tools/scale_test_export.py); named export preset ue_metric_v1 (FBX settings in that script); named import preset ue_metric_v1 (FbxImportUI settings in Tools/ue_scale_test_import.py). Both scripts are the templates for production asset export/import.
• [-] 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.
• 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.