From f9f4f887dd35d4beea2ad7309c627c220a82bddc Mon Sep 17 00:00:00 2001 From: Zwitschi Date: Sat, 7 Nov 2026 09:30:47 +0100 Subject: [PATCH] docs: bring setup and toolchain in line with a finished bootstrap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Initial setup is complete: setup.md opens with a per-section status table and drops the stale blockers, toolchain.md records that every pin has been exercised on real work (engine compile + package, Blender/MPFB/Blosm assets, PROJ origin), and MPFB's load-and-export check moves from pending to verified. Records the one unexercised path — a fresh checkout — as a v0.1.0 release check. --- Docs/setup.md | 21 +++++++++++++++++++-- Docs/toolchain.md | 6 ++++-- MEMORY.md | 6 ++++++ 3 files changed, 29 insertions(+), 4 deletions(-) diff --git a/Docs/setup.md b/Docs/setup.md index 012f03c..d228edd 100644 --- a/Docs/setup.md +++ b/Docs/setup.md @@ -8,6 +8,20 @@ Ordered procedure for bringing the workstation and the project to a buildable st 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 | +| 5. Repository | procedure documented; a fresh checkout has not yet been exercised end to end | + +Next: `0.1.0` content work (façade, block frontage, gameplay). Current board is [ROADMAP.md](../ROADMAP.md). + ## 1. System - `[x]` Update Bazzite with its supported mechanism. @@ -47,7 +61,7 @@ The archive on disk is **Unreal Engine 5.2.0**, released May 2023, three and a h - `[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. -- `[ ]` Confirm the geo tool Python environment (venv with `pyproj`, `GDAL`, `shapely` from the QGIS or distrobox environment) and record it. +- `[ ]` **Optional.** Confirm the geo tool Python environment (venv with `pyproj`, `GDAL`, `shapely`). Not needed so far: every geo script in `Geo/scripts/` 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 @@ -73,10 +87,13 @@ Without `git lfs install`, adding an LFS-matched file does not error — it comm 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 not yet tested end to end.** The build procedure in [build.md](build.md) was produced from a working tree, not from a clean clone. Exercise it before `v0.1.0` is tagged — it is a release check on the board. + ## Known blockers | Blocker | Owner | Needed for | | --- | --- | --- | -| Delete the fallback 5.2.0 engine archive once the 5.8.4 pin is trusted through asset production | agent | Disk hygiene, pin safety | +| 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 | agent | `v0.1.0` release check | 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. diff --git a/Docs/toolchain.md b/Docs/toolchain.md index 82556b8..26c522a 100644 --- a/Docs/toolchain.md +++ b/Docs/toolchain.md @@ -4,6 +4,8 @@ Pinned versions for this project. Record the exact build string a tool reports, Audited 2026-11-06, updated 2026-11-07 on the development workstation. +**State:** initial setup is complete. Every pinned tool below has been exercised on real work — the engine compiled game code and packaged a build, Blender/MPFB/Blosm produced committed assets, and QGIS's PROJ produced the project origin. The only unexercised path is a fresh checkout, tracked as a `v0.1.0` release check. + ## Pins | Component | Pinned | Source | Status | @@ -11,9 +13,9 @@ Audited 2026-11-06, updated 2026-11-07 on the development workstation. | Bazzite | `45.20261105` (Kinoite, `bazzite-dx-nvidia`), kernel `7.2.15-ogc1.1.fc45` | `ujust update` / `rpm-ostree upgrade` | Booted and default. `44.20261026` retained as rollback. | | NVIDIA driver | `615.78.08`, open kernel module | Bazzite image | Verified: desktop session renders through the RTX 5070 Ti; Vulkan GPU0 is the RTX 5070 Ti on driver `615.78.08`, conformance `1.4.3.3`. | | Unreal Engine | `5.8.4` — CL 58902052, `++UE5+Release-5.8`, promoted build | Epic download | Fully extracted to `/run/media/system/DATA/Engines/UE_5.8.4` (73 GiB on disk). **Validated 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). Pin is final. The verified 5.2.0 archive stays as fallback. | -| Unreal Linux toolchain | system `clang 23.1.4` (Fedora 45) | `rpm-ostree` layer | This 5.8.4 build ships **no** bundled Linux clang (no `clang++` anywhere in the engine tree, verified 2026-11-07); UBT compiles game code with the system toolchain. **Accepted 2026-11-07:** first game-module compile and link succeeded (`GigLineEditor` target, `libUnrealEditor-GigLine.so`). Note: game targets must use `BuildSettingsVersion.V7` to share the engine's build environment. | +| Unreal Linux toolchain | system `clang 23.1.4` (Fedora 45) | `rpm-ostree` layer | This 5.8.4 build ships **no** bundled Linux clang (no `clang++` anywhere in the engine tree, verified 2026-11-07); UBT compiles game code with the system toolchain. **Accepted 2026-11-07:** game-module compile and link (`GigLineEditor`, `libUnrealEditor-GigLine.so`) and a packaged Development build. Game targets use `BuildSettingsVersion.V7` + `EngineIncludeOrderVersion.Latest` (`Source/GigLine.Target.cs`, `Source/GigLineEditor.Target.cs`) to share the installed editor's build environment. | | Blender | `5.2.0` LTS (build 2026-07-14) | Flatpak `org.blender.Blender` | Installed. Run headless from the app tree with `LD_LIBRARY_PATH` + `BLENDER_USER_SCRIPTS`; `flatpak run` is unavailable to the agent shell. | -| MPFB | `2.0.18` (extension `bl_ext.blender_org.mpfb`, `blender_version_min 4.2.0`) | Blender extensions platform | Installed. **Headless-verified 2026-11-07 on 5.2:** enables and generates a default human (19 158-vert mesh, UVs) via `Tools/addon_compat_probe.py`. Headless runs must set `XDG_CONFIG_HOME=$HOME/.var/app/org.blender.Blender/config` or the extension is not discovered (see `Art/blender/README.md`). Load-and-export (skeleton + baked materials) check still pending. | +| MPFB | `2.0.18` (extension `bl_ext.blender_org.mpfb`, `blender_version_min 4.2.0`) | Blender extensions platform | Installed. **Fully verified 2026-11-07:** generates a default human (19 158 verts, UVs), standard 137-bone rig with weights, and a baked 1024² skin; the character imports into Unreal as a `SkeletalMesh` with Skeleton, Material, and Texture. Headless runs must set `XDG_CONFIG_HOME=$HOME/.var/app/org.blender.Blender/config` or the extension is not discovered (`Art/blender/README.md`). | | Blosm | `2.7.28` (legacy add-on, `bl_info.blender = (4, 5, 0)`, manifest min 4.2) | blosm.com | Installed and importing on Blender 5.2 in `3Dsimple` mode. Two headless workarounds are required; see `Art/blender/README.md`. Paid material asset pack lives in `~/Downloads/blosm-assets/` and is not committed. | | QGIS | `4.2.3`, Flatpak `stable`, runtime `org.kde.Platform 6.11`; bundled PROJ `9.9.0` | flathub | Installed 2026-11-06. Stale `lts` branch (`3.28.9`, EOL Qt5 runtime) uninstalled 2026-11-07; only `stable` remains. | | Git | `2.56.0` | Bazzite image | Installed. | diff --git a/MEMORY.md b/MEMORY.md index 685edf5..d26af9d 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -65,3 +65,9 @@ Scope: facts and traps that cost time to establish. Planned work lives in [ROADM - **Flatpak Blender headless needs `XDG_CONFIG_HOME=$HOME/.var/app/org.blender.Blender/config`** for extensions: `bpy.utils.user_resource('EXTENSIONS')` otherwise resolves to `~/.config/blender/5.2/extensions` (empty) and `bl_ext.blender_org.mpfb` is undiscoverable. Blosm unaffected (scripts/addons via `BLENDER_USER_SCRIPTS`). Found via `Tools/addon_compat_probe.py`; documented in `Art/blender/README.md`. - **UE 5.8 Interchange skips material/texture assets for skeletal FBX imports** (static imports do get materials). Finish the chain in Python: import texture, build Material via `MaterialEditingLibrary`, assign with `sm.set_editor_property('materials', [SkeletalMaterial])` — the struct field is `material_interface`, not `material`, and `SkeletalMesh.set_material()` does not exist. See `Tools/ue_character_import.py`. - **Blender 5.2 FBX exporter removed `armature_nla`** (passes for 4.x recipes fail). Also: a baked image is only referenced by the FBX exporter when `image.filepath` (not just `filepath_raw`) is set and the exporter can map the node — MPFB's v2 skin node-group tree can't be mapped, so a flat export material is required. + +## 2026-11-07 — Collaboration and scope + +- **Two sessions edit this repo at once.** The other session created the Unreal project and the blank package while this one was documenting. Check `git log` and `git status` before committing, and never `git add -A` blindly: it once swept generated `Game/GigLine/Build/**` logs into a commit. Stages the source files deliberately. +- **`Build/` under a project is generated**, not source — `FileOpenOrder/*.log` and packaging output. `.gitignore` now covers it alongside `Binaries/`, `Intermediate/`, `Saved/`, `DerivedDataCache/`. +- **Scope boundary for `0.1.0`:** do not tag `v0.1.0` without an explicit go-ahead from the owner. It is a minor release and carries the walking/driving demo promise; the board's release checks decide when it is ready, not the pace of work.