gig-line/Docs/toolchain.md

Toolchain

Pinned versions for this project. Record the exact build string a tool reports, not just the version family, and re-record it after every upgrade. The most common cause of scale, material, and import mismatches is silently mixing two versions of the same tool.

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
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: 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. 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.
Git LFS	3.7.1	rpm-ostree layer	Installed; git lfs install run, lfs filter active.
Host build tools	clang 23.1.4, cmake 4.3.0, ninja 1.13.2	rpm-ostree layer	Installed. These are host tools, not the engine toolchain.
distrobox	1.8.2.5	Bazzite image	Installed.
Python (tooling)	3.14.8 system	Bazzite image	Installed. Use a venv for geo/tool scripts.
ffmpeg	8.1.3	Bazzite image	Installed.

Unreal Engine 5.9 is in preview and Unreal Engine 6 has been announced as of November 2026. Neither is a pin candidate for 0.x. One engine family per milestone; a family change is a breaking change and belongs in CHANGELOG.md.

Agent skills

Item	Value
Package	blender-skills 1.3.0, upstream commit 8f778d2, MIT
Source	https://github.com/arjun988/blender-skills
Location	Local only: .agents/skills/blender-skills/ — not distributed with the repository
Installed	2026-11-06, copied from a local checkout of .claude/skills/ without edits

These are instructions and reference notes for agents, not code that runs in a build. Four of them assume a Blender MCP server; this project drives Blender headlessly through bpy (Tools/*.py) instead, so MCP is optional and nothing depends on it.

To update: copy .claude/skills/ from a newer upstream checkout over the local directory, then record the new version and commit hash in this table. Skills are read on demand, so the harness catalog may need a reload before they appear as first-class entries.

Pin rules

• One engine build per release. Record the launcher or source build, the patch version, and the build date in this file and in the release entry.
• Blender stays on an LTS family (5.2). Every add-on version used for a shipped asset is recorded here.
• Upgrading a pinned tool mid-milestone requires re-running the scale test and the Blender→Unreal import check before further asset work.
• Never install a tool from an unverified source. Record the download origin next to the version.

Open compatibility risks

1. Blosm on Blender 5.2 — worked around, not resolved. 3Dsimple import works headless (see the blockout). Two headless-only defects are patched around in the script rather than in the add-on: an asset-directory check that fires before mode is honoured, and a background-mode import path that uses a broken relative import when the default level table is empty. 3Drealistic mode has not been exercised; it loads the paid material pack and previously failed inside the realistic renderer setup. If realistic materials are wanted, test that mode separately before depending on it.
2. MPFB 2.0.18 on Blender 5.2. The extension declares Blender >= 4.2 but predates 5.x. Generation verified 2026-11-07: mpfb.create_human works headless once XDG_CONFIG_HOME points at the Flatpak config tree. Remaining acceptance test is the 0.1.0 requirement to export one MPFB character with baked materials and a deform skeleton and import it into Unreal.
3. QGIS 4.x recipes. Only stable (4.2.3) is installed now; the old lts was removed 2026-11-07. QGIS 4.x uses Qt6, so any processing recipe copied from a 3.x tutorial needs re-checking before it is trusted.
4. Driver and Vulkan validation on Bazzite. Not an officially supported Unreal distribution. The engine install itself is proven (full init headlessly); only the Vulkan RHI on the RTX 5070 Ti is unproven, and one desktop-terminal run settles it.