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** (`73d20a40`) — `d4940046` plus the #250 parallel-recording nesting fix and the Texture2DRD bind-race fix | built-in module | ✅ yes (`GodotSharp/`) |
| `engine/windows-x64/`  | **4.7.2** (`d49400463`) — same hash as macos-arm64: parallel draw-list replay + recording (game ships both ON) plus the VUID-00050 pool-reset fix, **verified 10/10 oracle with zero VUIDs before publish**; `template_release` here is still the `1e7be28b` tree | built-in module | ✅ yes (`GodotSharp/`) |

Mac is engine `73d20a40` as of 2026-10-19 (`--version` `4.7.2.stable.mono.custom_build.73d20a40b`): `d4940046` plus `219b914c` (#250, parallel draw-list sub-recordings nest; Windows Ultra-bench FATAL) and `73d20a40` (RD texture wrappers allocate their RS texture before the render-thread bind, fixing the milky ocean under the separate render thread); GodotSharp regenerated, API unchanged. The game pin stays `d49400463` until Windows is published at the same commit. Before that, Mac was engine `d4940046` as of 2026-10-19 (`--version` `4.7.2.stable.mono.custom_build.d49400463`): `a967d12b` plus a per-frame reset of the parallel-replay secondary command pools (fixes VUID-vkBeginCommandBuffer-00050). `a967d12b` is `e64890fd` plus parallel draw-list replay (Vulkan only) and parallel draw-list recording (every driver), both engine-default off and turned on by the game; GodotSharp regenerated; oracle `parallel_draw_replay` Vulkan 10/10, Metal 5/5 (`engine/.agents/wiki/parallel-draw-replay.md`). **Windows is also engine `d49400463` as of 2026-10-19** — Forge verified the fix before publishing: replay+record oracle Vulkan `--gpu-validation` **10/10 exit 0 with ZERO VUID lines** (on `a967d12bf` the same run had 10× VUID-00050 — the finding that produced this fix). The parallel features' Windows story: the fps lane's in-game A/B on `a967d12bf` recorded no fps regression (42→46-48), rGPU down 8.1→6.8 ms, 10-min soak stable, eye check PASS, and the game ships both ON (`f7ddc64a1`); timing claims carry the throttled-box caveat from the engine wiki. Earlier Windows oracle work on `a967d12bf`: `draw_indirect_count` d3d12 with debug layer 22/0 + expected SKIP line; `multimesh_cull_pool` d3d12 4524/4524 (parity with Mac, pooled-cull gate met). Vulkan SDK + Graphics Tools are installed on Forge. Still owed: a `--gpu-validation` in-game soak on `d49400463`, tests=yes unit suites, crash checklist. Underneath: `e64890fd` (Apple autorelease-drain + G4 census) on `4fde0e94` (G2 pooled cull, fixed shadow band, `STATIC_SHADOW_AT_REST`) on the `9dcc5d458` pair (SSCS contact shadows, hero shadow min-combine, upstream 4.8 shadow fixes #121775/#124348 with the game sun bias 0.014, `draw_list_draw_indirect_count`).

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