gig-line/Docs/setup.md

# Setup

Ordered procedure for bringing the workstation and the project to a buildable state. Status markers follow `TODO.md`:

- `[x]` done and verified
- `[A]` started, not finished
- `[ ]` not started

Anything marked **human step** needs credentials, licence acceptance, or a decision that cannot be automated. Never store Epic credentials, tokens, or licence keys in the repository.

## Status — 2026-11-07

**Initial setup is complete.** Sections 1 to 4 are done and verified; the project builds, packages, and imports Blender assets with the pinned toolchain. What remains in section 3 is one optional geo environment.

| Section | State |
| --- | --- |
| 1. System | done — Bazzite `45.20261105`, driver `615.78.08`, Vulkan verified, host build tools layered |
| 2. Engine | done — UE `5.8.4` at `/run/media/system/DATA/Engines/UE_5.8.4`, editor launches with Vulkan on the 5070 Ti |
| 3. Tooling pins | done except the optional geo venv; Blender 5.2, MPFB 2.0.18, Blosm 2.7.28, QGIS 4.2.3 all verified |
| 4. Project bootstrap | done — C++ project, packaged blank build, static-mesh scale test, MPFB character import |
| 6. Content pipeline | in progress — blockout, terrain, street, hero façade and the walkable `DemoMap` exist; façades and materials are planned patches (`0.1.4`) |
| 5. Repository | procedure documented; a fresh checkout has not yet been exercised end to end |

Next: `0.1.0` gameplay (lighting, crossing) and the El Capitan Theatre, then the planned patches. Current task list is [TODO.md](../TODO.md); version direction is in [ROADMAP.md](../ROADMAP.md).

## 1. System

- `[x]` Update Bazzite with its supported mechanism. `ujust update` (or `rpm-ostree upgrade`) followed by a reboot. Deployment `45.20261105` is booted and default; `44.20261026` retained as rollback.
- `[x]` Verify the NVIDIA driver and Vulkan from the desktop session. `nvidia-smi` names the RTX 5070 Ti on driver `615.78.08` and the Wayland desktop renders through it. Vulkan enumerates it as GPU0: discrete, proprietary driver `615.78.08`, API `1.4.351`, conformance `1.4.3.3`. The integrated RADV GPU is GPU1 — watch that the engine does not select it.
- `[x]` Install `git-lfs`, `cmake`, `ninja-build`, `clang` as an ostree layer, reboot, then `git lfs install`. Done: `git-lfs 3.7.1`, `clang 23.1.4`, `cmake 4.3.0`, `ninja 1.13.2`; lfs filter active, `Tools/check-lfs.sh` passes.

## 2. Engine acquisition

- `[x]` **Human step.** Create an Epic account, accept the Unreal license. Done on 2026-11-06 with the account email recorded locally; no credentials stored in the repository.
- `[x]` **Human step.** Acquire one pinned engine build. Two routes:
  - **Launcher build**: install the Linux Epic Games Launcher, download the pinned engine version, install to the DATA volume, and disable auto-update so the pin holds.
  - **Source build**: clone the pinned `release` branch from the Epic Games GitHub organisation, then `./Setup.sh`, `./GenerateProjectFiles.sh`, `make -j16`. Budget 120–200 GB and a multi-hour first build on 16 threads. **5.8.4** downloaded to `/run/media/system/DATA/Downloads/Linux_Unreal_Engine_5.8.4.zip`: 39 819 212 076 bytes (37.08 GiB), ZIP central directory present with 299 959 entries, `Engine/Build/Build.version` reports **5.8.4**, changelist 58902052, `++UE5+Release-5.8`.
- `[x]` Verify the archive end to end before extracting. `unzip -tq` on 2026-11-06: "No errors detected", exit 0.
- `[x]` Extract to the DATA volume and record the install path. Done 2026-11-07: `/run/media/system/DATA/Engines/UE_5.8.4`, 73 GiB on disk, extraction verified by full headless editor start.
- `[x]` Resolve the engine version: **5.8.4 pinned** (see the decision below). The 5.2.0 archive (19.59 GiB, CL 25360045) remains on disk as a fallback only and should be deleted once the pin is trusted.
- `[x]` Record the exact engine version and build route in [toolchain.md](toolchain.md). Done: 5.8.4, Epic download route, CL 58902052.
- `[x]` Validate that the engine editor opens and a blank project runs on Bazzite. Done 2026-11-07: headless `-NullRHI` smoke test **and** full editor GUI launch with Vulkan RHI on the RTX 5070 Ti (loader 1.4.350, `VULKAN_SM5`, map check 0 errors). No distribution workarounds were needed; only benign log noise (Android Turnkey status, telemetry DNS failures).

### Engine version decision

The archive on disk is **Unreal Engine 5.2.0**, released May 2023, three and a half years before this project started. That is a legitimate choice — nothing in the `0.1.0` scope needs a newer feature — but it carries known costs that must be recorded before pinning it:

- The bundled Linux toolchain in 5.2 targets an older glibc than Bazzite 45 ships. Project C++ compilation may need the bundled clang with older sysroot flags, or may simply fail; that has to be tested before any C++ work.
- GPU support: 5.2 predates the driver and Vulkan paths that Blackwell cards (RTX 50 series) exercise. Vulkan RHI should still work, but shader compilation and Lumen behaviour on a 5070 Ti are unvalidated.
- No engine fixes from 5.3 through 5.8, and no compatibility with content or plugins authored for newer versions.
- Bazzite is not a supported Unreal distribution in any version, so this risk compounds rather than introduces.

**Decision taken 2026-11-06, archive delivered 2026-11-07, extracted and validated 2026-11-07:** the current stable release is **5.8.4**, and that is the pin. The 5.2.0 archive stays only until the 5.8.4 pin is trusted through asset production, then gets deleted; two engines on disk invite accidental mixing. The 5.2.0 costs listed above are why the newer build was preferred. Note: this 5.8.4 build ships **no** bundled Linux clang — the system clang (23.1.4) is the game-code toolchain, accepted by the first C++ compile and by the packaged build.

## 3. Tooling pins

- `[x]` Blender 5.2 LTS (Flatpak) and MPFB 2.0.18 recorded.
- `[x]` Install QGIS and record its version. QGIS **4.2.3**, Flatpak `stable`, runtime `org.kde.Platform 6.11`, bundled PROJ `9.9.0`. The stale `lts` 3.28.9 install was uninstalled 2026-11-07; only `stable` remains.
- `[x]` Install Blosm in Blender, record its version, and confirm it loads on Blender 5.2. Blosm **2.7.28** imports the block extract headless in `3Dsimple` mode; the exact command and the two required headless workarounds are in `Art/blender/README.md`. No second Blender version was needed.
- `[ ]` **Optional.** Confirm the geo tool Python environment (venv with `pyproj`, `GDAL`, `shapely`). Not needed so far: every geo script in `Geo/tools/` is standard-library only, and PROJ 9.9.0 is invoked from the QGIS Flatpak (`LD_LIBRARY_PATH` trick in `Geo/manifests/local-origin.md`). Add the venv only when a step genuinely needs `pyproj` or GDAL in-process.

## 4. Project bootstrap

- `[x]` Create the C++ Unreal project at `Game/GigLine/GigLine.uproject` with Enhanced Input enabled and Blueprint gameplay enabled. Created 2026-11-07: primary game module + default game mode, Enhanced Input plugin and input classes in `Config/DefaultInput.ini`. `Config/`, `Source/`, and `GigLine.uproject` are committed; `Binaries/`, `Intermediate/`, `Saved/`, and the DDC stay out via `.gitignore`.
- `[x]` Point the local Derived Data Cache at the DATA volume. The engine lives on the DATA volume and installed builds default `LocalDDC` under the engine root, so the DDC is already off the repository SSD tree. Revisit only if a project-local DDC is later configured.
- `[x]` Enable Git LFS integration in the editor before importing content, so large assets are routed to LFS on import rather than on a later re-add. Satisfied by repo-level `.gitattributes` routing: content is added via `git add` (CLI or editor), and the attributes send `.uasset`/`.umap`/`.blend` to LFS regardless of which tool wrote them. `Tools/check-lfs.sh` is the guard.
- `[x]` Package and launch a blank Linux build from the command line, so the packaging path is proven before any content exists. Done 2026-11-07: UAT `BuildCookRun` succeeded in 56 s; 1.1 GiB archive at `/run/media/system/DATA/Builds/GigLine`; `GigLine.sh` rendered 759 frames across a 60 s smoke test. Full procedure in [build.md](build.md).
- `[x]` Export one static mesh from Blender with a known metric size and import it into Unreal. Verified 2026-11-07 with the three-cube calibration scene: 1 m → exactly 100.00 cm, origin preserved, material imported; axis mapping east → +X, north → −Y, up → +Z. Presets and scripts in [build.md](build.md) and `Art/blender/README.md`.
- `[x]` Export one MPFB character with baked materials and a deform skeleton and verify it imports with the expected skeleton hierarchy and scale. Done 2026-11-07: MPFB 2.0.18 generated human (19 158 verts) + standard rig (137 bones, weights) + v2 skin baked to a 1024² diffuse; imported into Unreal as a `SkeletalMesh` with a 138-bone `Skeleton`, a `Material` carrying the baked `Texture2D`, in `/Game/Test/Character`.
- `[x]` Commit the baseline and write the fresh-checkout build procedure into [build.md](build.md). Done 2026-11-07.

## 5. Repository

```bash
git clone <remote> gig-line
cd gig-line
git lfs install          # writes filter.lfs.* into git config; required before any content commit
git lfs pull
Tools/check-lfs.sh       # fails when the lfs filter or the pointer storage is missing
```

Without `git lfs install`, adding an LFS-matched file does not error — it commits the file as a plain blob. `Tools/check-lfs.sh` is the guard for that.

Sizes: the engine lives outside the repository (pinned install path recorded in `toolchain.md`). The repository holds the Unreal project, Blender sources, geo sources, and tooling.

**Fresh checkout verified 2026-11-08.** A clean clone of `main` with `git lfs pull` built both `GigLineEditor` and `GigLine` against the documented external engine (recorded in [release-checks.md](release-checks.md)). Re-run it before a release tag if the engine pin or the module's dependencies change.

### Optional keys (local only)

Two tools talk to paid services and read their keys from the gitignored `.env`:

| Variable | Used by | Needed for |
| --- | --- | --- |
| `OPENROUTER_API_KEY` | `Tools/judge_screenshot.py`, `Tools/facade_detail_concepts.py` | vision pre-check and AI concept plates |
| `MAPBOX_ACCESS_TOKEN` | `Geo/tools/mapbox_buildings.py` | the second building-height source |

Nothing in the build, the tests or the release path needs either key. Never commit `.env`; `git check-ignore .env` should succeed.

## Known blockers

| Blocker | Owner | Needed for |
| --- | --- | --- |
| Delete the fallback 5.2.0 engine archive (`/run/media/system/DATA/Downloads/Linux_Unreal_Engine_5.2.0.zip`) once the 5.8.4 pin is trusted through asset production | agent | Disk hygiene (19.6 GiB), pin safety |
| ~~Fresh-checkout build exercised against the documented procedure~~ | — | Done 2026-11-08 |

Closed 2026-11-07: Epic account and engine download, QGIS `lts` removal, Blosm and MPFB on Blender 5.2 (headless invocation fix in `Art/blender/README.md`), engine validation on Bazzite, full project bootstrap. Earlier closed: Bazzite update and reboot, driver and Vulkan verification, `git-lfs`/`clang`/`cmake`/`ninja` layering.