gig-line/Docs/setup.md

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.
• [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 — 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.
• [ ] 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.

Decision taken 2026-11-06: fetch the current stable release — Linux_Unreal_Engine_5.8.4.zip is downloading — and keep the verified 5.2.0 archive only as a fallback until 5.8.4 launches. Once 5.8.4 validates, delete the 5.2.0 archive and pin 5.8.4 in toolchain.md; two engines on disk invite accidental mixing.

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 is still beside it and should be uninstalled.
• [ ] 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.

5. Repository

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.