gig-line/PLAN.md

PLAN.md

Goal

Build a Linux-first Unreal Engine game for walking and driving through a real city.

Initial release: 0.1.0 — a walkable exterior demo around 6840 Hollywood Blvd / El Capitan Entertainment Centre, including the surrounding block frontage and buildings directly across Hollywood Boulevard.

Verify the address, building footprints, and demo boundaries before modeling. Treat these as distinct structures where the source data indicates; do not assume similarly named venues share one footprint.

Stack

• Unreal Engine: rendering, gameplay, World Partition, Chaos Vehicles.
• Blender: modeling, UVs, baking, collision meshes, character preparation.
• MPFB: human base meshes; export baked materials and deform skeletons.
• QGIS: geographic cleanup, coordinate conversion, elevation preparation.
• Blosm: OSM building and street blockouts in Blender.
• Git + Git LFS: source control, large assets, tagged releases.

Pin compatible tool versions in docs/toolchain.md. Validate Blender-to-Unreal mesh, skeleton, material, and scale transfers before producing assets.

Release Policy

Use Semantic Versioning: MAJOR.MINOR.PATCH.

• Each major development milestone receives a minor release.
• Each completed small stabilization task receives a patch release.
• New milestone functionality lands in prereleases such as 0.2.0-alpha.1, not in patches.
• Patches contain fixes, optimization, documentation, or refinements without expanding scope.
• Tag releases as v0.1.0; maintain CHANGELOG.md.
• During 0.x, document breaking changes and asset migrations.
• 1.0.0 marks the stable, agreed game scope—not completion of an entire city.

Initial Local Setup

Target workstation: Bazzite Linux, Ryzen 7 7700X, 64 GB RAM, RTX 5070 Ti 16 GB.

1. Update Bazzite using its supported mechanism; verify NVIDIA/Vulkan operation.
2. Register an Epic account and accept the Unreal license. Obtain a pinned Linux engine build or build from Epic's authorized source repository.
3. Validate Unreal on Bazzite before asset production; it is not necessarily an officially supported distribution.
4. Install the engine-required compiler/SDK, Git, Git LFS, and an editor. Use Distrobox for isolated command-line dependencies where useful.
5. Pin Blender, MPFB, Blosm, and QGIS versions; confirm add-on compatibility.
6. Keep the project and Derived Data Cache on SSD storage. Reserve several hundred GB for engine files, assets, caches, and builds.
7. Create a C++ Unreal project with Blueprint gameplay iteration and Enhanced Input.
8. Package and launch a blank Linux build immediately.
9. Test one static mesh and one MPFB character export before proceeding.

Repository

Progress lives in ROADMAP.md; session findings live in MEMORY.md; rendered review captures and their approval state live in Screenshots/.

• Game/ — Unreal project, configuration, source, game-ready content.
• Art/ — editable Blender files and original textures.
• Geo/ — source manifests, permitted geographic data, processing scripts.
• Tools/ — repeatable import/export helpers.
• Docs/ — setup, licenses, architecture, release checks.

Track .uasset, .umap, .blend, and large source binaries with LFS. Ignore generated Binaries/, Intermediate/, Saved/, and Derived Data Cache. Do not commit Unreal Engine source, credentials, or non-redistributable assets.

Geographic and Art Pipeline

1. Save a versioned OSM extract and document its date, bounds, and source.
2. Acquire separately licensed elevation data if needed.
3. In QGIS, use a suitable local projected CRS, such as EPSG:26911, and record a local origin.
4. Import OSM blockouts through Blosm; clean and detail them in Blender.
5. Preserve geographic coordinates in metadata; convert to local Unreal coordinates with explicit meter-to-centimeter conversion.
6. Export modular buildings, sidewalks, roads, collision, and materials.
7. Use licensed reference photography for manual façade work.
8. Treat OSM as layout data—not authoritative façade, height, or pavement detail.

Use a consistent scale test, named export presets, and repeatable import settings.

Initial Demo: 0.1.0

Included

• Named site frontage, surrounding block frontage, and buildings across the street.
• Walkable sidewalks and a designated street crossing.
• First-person movement, mouse look, collision, reset, and pause.
• Recognizable hero façades; simplified background buildings.
• Fixed daytime lighting and basic ambience.
• Packaged Linux build with documented controls.

Excluded

Driving, interiors, crowds, traffic simulation, multiplayer, and a full-city map.

Acceptance

• Player can traverse both sides of the demo without falling through geometry.
• Building placement, street scale, and site identity have been checked against references.
• No blocking collision or packaging defects.
• Target 60 FPS at 1440p on the development workstation using a documented quality preset.
• Record whether upscaling is enabled and report performance without frame generation.
• A fresh project checkout builds with the documented external engine installation.

Indicative Timeline

Solo-development estimate: approximately 30–40 weeks, subject to asset quality and available hours.

Release	Weeks	Larger task	Small patch tasks after release
0.1.0	1–6	Local setup and initial walkable Hollywood block	0.1.1 collision fixes; 0.1.2 scale/façade corrections; 0.1.3 packaging and setup fixes
0.2.0	7–9	MPFB player body, third-person camera, basic animation	0.2.1 rig fixes; 0.2.2 skin/hair tuning; 0.2.3 camera clipping fixes
0.3.0	10–13	One Chaos vehicle, enter/exit interaction, closed driving route	0.3.1 handling tuning; 0.3.2 vehicle collision fixes; 0.3.3 input fixes
0.4.0	14–17	Expand to a small connected neighborhood; stream map cells	0.4.1 seam fixes; 0.4.2 streaming corrections; 0.4.3 HLOD tuning
0.5.0	18–21	Pedestrians, crosswalk behavior, limited ambient traffic	0.5.1 navigation fixes; 0.5.2 crossing fixes; 0.5.3 simulation optimization
0.6.0	22–24	Visual/audio pass and evening lighting preset	0.6.1 lighting fixes; 0.6.2 material corrections; 0.6.3 audio balancing
0.7.0	25–27	Settings, control rebinding, save/load, accessibility basics	0.7.1 save fixes; 0.7.2 UI fixes; 0.7.3 input persistence fixes
0.8.0	28–30	Performance budgets and broader Linux hardware testing	0.8.1 VRAM reductions; 0.8.2 frame-time fixes; 0.8.3 compatibility fixes
0.9.0	31–34	Realistic buildings: façade system, per-building models, measured material library, LODs and collision proxies	0.9.1 façade fixes
0.10.0	35–38	Feature freeze, public beta, license and build audit	0.10.1 blocker fixes; 0.10.2 regression fixes; 0.10.3 documentation fixes
1.0.0	39–44	Stable neighborhood-scale walking/driving release	1.0.x maintenance and compatibility fixes

Finish each milestone's release checks before expanding scope. Cut map size and simulation complexity before compromising the core walking/driving experience.

Licensing and Distribution

• Publish project-owned code under a chosen open-source license.
• Unreal remains proprietary/source-available; this is not a fully open-source engine stack.
• Separate code, art, engine, and geographic-data licensing.
• Record asset provenance and redistribution permissions in THIRD_PARTY_NOTICES.md.
• Verify licenses for every MPFB asset, texture, animation, vehicle, and audio file.
• Keep restricted assets out of the public repository; prefer redistributable replacements.
• Review Epic distribution requirements before publishing builds.