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** (`e64890fd`) — `4fde0e94` plus the Apple render-thread autorelease drain (fixes the Mach-port / Metal leak under `thread_model=2`) and the G4 mergeable-draw counter | built-in module | ✅ yes (`GodotSharp/`) |
| `engine/windows-x64/`  | **4.7.2** (`e64890fd3`) — same hash as macos-arm64: `4fde0e94` (G2 pooled cull, fixed shadow band, `STATIC_SHADOW_AT_REST`) plus the G4 mergeable-draw counter (the autorelease-drain fix is Apple-only); `template_release` here is still the `1e7be28b` tree | built-in module | ✅ yes (`GodotSharp/`) |

Mac is engine `e64890fd` as of 2026-10-18 (`--version` prints `4.7.2.stable.mono.custom_build.e64890fd3`): `4fde0e94` plus the separate render thread draining an Objective-C autorelease pool each flush — before, autoreleased Metal command buffers, encoders and drawables leaked ~88 Mach ports/s until no new Metal process could start (66k ports / 23 GB after 1.5 h); now flat at ~640 ports — and `RENDERING_INFO_GPU_CULL_MERGEABLE_DRAWS_IN_FRAME`. Underneath, `4fde0e94` added: G2 pooled GPU cull over shared storage arenas (`rendering/occlusion_culling/gpu_cull_pooled`, game dial `env gpucull pool`), a fixed shadow LOD band for gpu-culled MultiMeshes (`gpu_cull_shadow_fixed_band`, `env gpucull shadowband`) and the `STATIC_SHADOW_AT_REST` shader built-in (`static_casters_at_rest`, `env gpucull staticrest`); all default off. GodotSharp regenerated (API + Tools). Oracles on Metal: `multimesh_cull_pool` 4524/4524, `draw_indirect_count` 24/24. Windows is also engine `e64890fd` as of 2026-10-18 (`.agents/handoffs/forge-windows-e64890fd.md`) — both platforms and the `4.7.2@e64890fd3` pin share one hash; the autorelease-drain fix is Apple-only, Windows gains the G4 census counter (`env gpucull status` shows `(N mergeable)`). Headless game boot clean on Forge. Underneath, `4fde0e94` (`.agents/handoffs/forge-windows-g2-4fde0e94.md`) added: G2 pooled GPU cull over shared storage arenas (`rendering/occlusion_culling/gpu_cull_pooled`, game dial `env gpucull pool`), a fixed shadow LOD band for gpu-culled MultiMeshes (`gpu_cull_shadow_fixed_band`, `env gpucull shadowband`) and the `STATIC_SHADOW_AT_REST` shader built-in (`static_casters_at_rest`, `env gpucull staticrest`; the game's `tree_wind.gdshader` uses it); all default off. Underneath is 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`), where the D3D12 oracle on RTX 5080 was 22 passed / 2 failed — the base-instance pair, the documented D3D12 gap (`.agents/handoffs/forge-windows-sscs-9dcc5d45.md`); `--gpu-validation` needs the D3D12 debug layer, which Forge lacks (Graphics Tools not installed). Still owed on Windows: `multimesh_cull_pool` oracle (gates making pool the default), the validation pass, and in-world checks (`herocombine`, `contactshadow`, SSCS in `--gpu-profile`, sun acne at bias 0.014, pooled gpucull census, mergeable counter).

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