# 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: Linux_Unreal_Engine_5.2.0.zip, 19.59 GB, Built on 2026-11-03.
- `[ ]` 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.

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