# Setup

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

- `[x]` done and verified
- `[-]` 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.

## 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. Evidence in [environment.md](environment.md).
- `[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.
- `[-]` **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.
  Downloaded 2026-11-06 to `/run/media/system/DATA/Downloads/Linux_Unreal_Engine_5.2.0.zip`: 21 036 632 443 bytes (19.59 GiB), ZIP central directory present, `Engine/Build/Build.version` reports **5.2.0**, changelist 25360045, `++UE5+Release-5.2`, payload dated 2023-05-06.
  Not yet extracted, and the version conflicts with the 5.8.x target in [toolchain.md](toolchain.md) — see "Engine version decision" below.
- `[x]` Verify the archive end to end before extracting. `unzip -tq` on 2026-11-06: "No errors detected", exit 0.
- `[ ]` Extract to the DATA volume and record the install path. Plan: `mkdir -p /run/media/system/DATA/Engines/UE_5.2 && cd $_ && unzip -q <zip>`; engine root becomes `/run/media/system/DATA/Engines/UE_5.2/Engine`. Roughly 55–60 GB extracted, so keep it off the repository volume tree.
- `[ ]` Resolve the engine version: 5.2.0 is what is on disk, 5.8.x was the planned pin. Record the decision and its reasons.
- `[ ]` Record the exact engine version and build route in [toolchain.md](toolchain.md).
- `[ ]` Validate that the engine editor opens and a blank project runs on Bazzite. Unreal does not support this distribution; record any workarounds.

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

Alternative: fetch the current stable release instead, and keep the 5.2.0 archive as a fallback until the newer one is validated. Either way, one version gets pinned in [toolchain.md](toolchain.md) and the other is deleted, because a second engine on disk invites accidental mixing.

## 3. Tooling pins

- `[x]` Blender 5.2 LTS (Flatpak) and MPFB 2.0.18 recorded.
- `[-]` Install QGIS and record its version.
  The flathub `lts` branch installed **3.28.9** on an end-of-life Qt5 runtime — not an acceptable pin. Mirror the upstream LTR instead: `flatpak install flathub --user org.qgis.qgis//stable`, and if that is also stale, move QGIS into a distrobox container from the Fedora package. Details in [environment.md](environment.md).
- `[ ]` Install Blosm in Blender, record its version, and confirm it loads on Blender 5.2. Fall back to a side-by-side Blender 4.5 LTS only for the blockout step if it does not.
- `[ ]` Confirm the geo tool Python environment (venv with `pyproj`, `GDAL`, `shapely` from the QGIS or distrobox environment) and record it.

## 4. Project bootstrap

- `[ ]` Create the C++ Unreal project at `Game/GigLine/GigLine.uproject` with Enhanced Input enabled and Blueprint gameplay enabled. Commit `Config/`, `Source/`, and `GigLine.uproject`; leave `Binaries/`, `Intermediate/`, `Saved/`, and the DDC out of the repository — `.gitignore` already covers them.
- `[ ]` Point the local Derived Data Cache at the DATA volume. Confirm the setting name and section against the pinned engine's documentation rather than copying a config snippet from another version.
- `[ ]` 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.
- `[ ]` Package and launch a blank Linux build from the command line, so the packaging path is proven before any content exists.
- `[ ]` Export one static mesh from Blender with a known metric size and import it into Unreal. Verify the 100× scale conversion (1 m → 100 uu), the pivot, normals, and material assignment.
- `[ ]` Export one MPFB character with baked materials and a deform skeleton and verify it imports with the expected skeleton hierarchy and scale.
- `[ ]` Commit the baseline and write the fresh-checkout build procedure into [build.md](build.md).

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

## Known blockers

| Blocker | Owner | Needed for |
| --- | --- | --- |
| Epic account, license acceptance, engine download | human | All Unreal work |
| QGIS pin: replace the stale `3.28.9` flatpak | human | Geo pipeline |
| Blosm install and Blender 5.2 compatibility check | human | OSM blockouts |

Closed: Bazzite update and reboot, driver and Vulkan verification, `git-lfs`/`clang`/`cmake`/`ninja` layering.