zwitschi
1c476e4fb5
The archive on disk is Unreal Engine 5.2.0 (CL 25360045, payload dated 2023-05-06), 19.59 GiB, ZIP central directory present and unzip -tq clean. That contradicts the planned 5.8.x pin, so the decision, its costs, and the extraction plan are written into Docs/setup.md rather than silently pinned.
87 lines
7.2 KiB
Markdown
87 lines
7.2 KiB
Markdown
# 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.
|