builds/README.md

# tinqs/builds

Build artifacts for the Tinqs stack — engine editor binaries (+ their GodotSharp C# bindings).
**Binaries and GodotSharp are stored via Git LFS** (see `.gitattributes`). Source lives in
`tinqs/engine`, `tinqs/ariki-game`, `tinqs/ariki-sim`. See `manifest.json` for exact versions.

> **Use `tinqs pull` / `tinqs push`, never raw git** — these are LFS-heavy.

## Installing / updating the engine

**Don't copy files by hand — run the `update-engine` skill (it lives in the game repo, which everyone has):**
[tinqs.com/tinqs/ariki-game · .agents/skills/update-engine](https://tinqs.com/tinqs/ariki-game/src/branch/main/.agents/skills/update-engine/SKILL.md).
Hand it to your agent; it `tinqs pull`s ariki-game + builds, installs the binary + GodotSharp into
`../engine/bin/`, wipes stale caches, and verifies. Covers macOS + Windows.

## ⚠️ The one rule: binary + GodotSharp are a MATCHED PAIR

Each engine binary ships with a `GodotSharp/` folder (Godot's C# bindings) **generated from that
exact engine build**. You must install them **together** and replace any old `GodotSharp`.

- The engine does **NOT** regenerate GodotSharp at runtime. If it's missing you get a
  **`.NET assemblies not found`** dialog pointing at `engine/bin/GodotSharp/Api/Debug`.
- A **stale** GodotSharp (from an older engine) against a newer binary throws
  **`Wrapper class not found for type: Terrain3D`** → terrain renders as water, animals don't animate.

This matters now because **Terrain3D and `agent_skinned` are native engine modules** (no separate
`addons/terrain_3d` GDExtension `.framework`). Built-in module classes need their wrappers baked
into GodotSharp, so GodotSharp had to be regenerated — and must ship here alongside the binary.

## Current contents

| Platform | Engine | Terrain3D | GodotSharp shipped? |
|---|---|---|---|
| `engine/macos-arm64/` | **4.7.2** (`7fb81364`) — normal-roughness pre-pass built-in, tonemap cinematic stack, render-thread CPU profile, crash/freeze/device-lost reporting + structured engine errors (R0 P5), on top of everything `1e7be28b` had | built-in module | ✅ yes (`GodotSharp/`) |
| `engine/windows-x64/`  | **4.7.2** (`7fb81364b`) — everything `0ec39c95` had (GPU diet + R0 P5) plus crash-handler fixes (first-wins crash claim, freeze-report note/context, pause handling); `template_release` here is still the `1e7be28b` tree | built-in module | ✅ yes (`GodotSharp/`) |

Mac is engine `7fb81364` as of 2026-10-17 (`--version` prints `4.7.2.stable.mono.custom_build.7fb81364b`; `0ec39c95` + crash-report review fixes, no API change; Windows carries `7fb81364` too): `IN_NORMAL_ROUGHNESS_PASS` (heavy materials skip their texture work in the SSAO/SSIL pre-pass), the cinematic stack (CA, vignette, grain) inside the tonemap pass, render-thread CPU in `--gpu-profile`, and R0 P5 crash dumps / freeze watchdog / D3D12 device-removed reason / structured engine errors. Windows carries `7fb81364b` as of 2026-10-17 (second Forge rebuild the same day: `a040761bd1` consistent note/context in freeze reports + pauses never count as stall time, `7fb81364b5` one first-wins atomic claims a Windows crash; [`.agents/handoffs/forge-windows-gpu-diet-r0-p5.md`](.agents/handoffs/forge-windows-gpu-diet-r0-p5.md); editor target only, `template_release` is still the `1e7be28b` tree). macos-arm64 is still `0ec39c95` — Kraken is rebuilding, so the game pin is version-only `4.7.2`; pin `4.7.2@7fb81364b` once mac lands. Earlier: Mac is engine `1e7be28b` as of 2026-10-05 night (`--version` prints `4.7.2.stable.mono.custom_build.1e7be28b1`; same code as `b0daf759`, relinked to match the Windows pair so `required_engine_build` is pinned to `4.7.2@1e7be28b`): GPU culling Stage C (previous-frame depth-pyramid occlusion, default off), zero per-frame cull uploads, static-cache single-sample + hard-filter options (default = unchanged), true per-pass Metal GPU profile, parallel shadow instance fill, on top of Stage B2 CPU band skip for GPU-culled MultiMeshes (the x4.7 draw explosion of `gpucull veg on` is gone; the path still stays off by default) on top of everything 51ed21d5 had (shadow diet incl. tile budget / live caster size cull / inverted-contract switch, video adapter memory query, GPU device-lost diagnostics) plus GPU-driven MultiMesh culling Stage A (compute frustum cull + indirect draws, `multimesh_set_gpu_cull`) and Stage B (per-instance GPU LOD bands, `multimesh_set_gpu_lods`), real Metal GPU timestamps (`renderGpuMs`), staggered far cascades, fit-to-visible-depth (SDSM-lite, default off), the Metal argument-buffer copy-queue stall fix and the Vulkan breadcrumb barrier fix (#185). Windows carried `b1bc0aef` (2026-09-28, 4.7.2 + static shadow cache, then `1e7be28b` 2026-10-05) until the 2026-10-17 Forge rebuild delivered all of the above plus the video adapter memory query. The engine source repo stays private. Check `manifest.json` for sha256. The 4.7 Windows cutover handoff is resolved: [`.agents/handoffs/forge-windows-4.7.md`](.agents/handoffs/forge-windows-4.7.md).

Long-term: CI (Gitea Actions) builds on push and publishes here / to S3 —
`docs/ai/plans/build-pipeline-architecture-2026-06-07.md`.