0 Fork 0

Files

T

zwitschi 1b722048ce fix(tools): importers clear the read-only LFS bit before saving; docs refresh

0.1.3 packaging and setup fixes from what 0.1.x actually exposed.

- New Tools/ue_common.py: make_writable() clears the read-only bit an LFS .umap
  checks out with (save_map() otherwise returns False silently and the staged actor
  is lost) and require_saved() makes that failure visible. ue_hero_facade_import and
  ue_import_north_buildings now call it; the map builders already did. Verified from
  a forced 0o444 map: chmod logged, save_map True, exit 0.
- Docs/build.md: pipeline table now lists the seven site FBXs plus frontage, north,
  hero and map steps and the shared FBX preset; packaging archive corrected to
  Builds/GigLineQA; packaged-log location and -qaselftest usage documented; new
  'Traps that cost real time in 0.1.x' table (read-only save, hero --out is the FBX,
  MPFB add-on path, shot actor quitting under QA, null-RHI trace trap).
- Docs/setup.md: fresh-checkout build marked verified 2026-11-08 and the blocker
  closed; new optional-keys section for OPENROUTER_API_KEY and MAPBOX_ACCESS_TOKEN
  (gitignored .env, not needed by build/tests/release).
- Docs/Architecture 07 + architecture.md: build-output path corrected, marked
  outside the repository.
- 5 new tests for ue_common (54 total).

2026-11-08 18:50:37 +01:00

11 KiB

Raw Blame History

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; version direction is in 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. 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.
[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 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. Done 2026-11-07.

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.

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

11 KiB Raw Blame History Unescape Escape