builds/.agents/skills/update-engine/SKILL.md

---
name: update-engine
description: Update this machine to the current Tinqs engine so ariki-game runs. Pulls the ariki-game game repo AND the builds repo, then installs the prebuilt engine (binary + GodotSharp C# bindings) into ../engine/bin. Use when an engine update is announced, when setting up a new machine, or when the game shows ".NET assemblies not found" or "Wrapper class not found for type: Terrain3D" (terrain is water / animals don't animate). Covers macOS (arm64) and Windows (x64).
---

# Update this machine to the current Tinqs engine

Run this and your machine ends up current: **game repo pulled + engine installed + verified.**
**Only Ozan edits the engine source.** Everyone else installs the prebuilt engine from the `builds`
repo into `../engine/bin/`, which is where `ariki-game` looks for it.

## TL;DR for an agent

1. `tinqs pull` the **ariki-game** repo (latest game code) and the **builds** repo (latest engine).
2. Copy the platform binary **+ its GodotSharp** from `builds/engine/<platform>/` into `../engine/bin/`.
3. `rm -rf ariki-game/.godot/mono`, then `game.sh run` to verify.

Detail below.

## ⚠️ Read this first — binary + GodotSharp are a MATCHED PAIR

The engine binary and its `GodotSharp/` folder (Godot's C# bindings) are **both generated from the
same engine source** and must be installed **together**. The binary does **not** regenerate
`GodotSharp` — it must sit next to the binary on disk. Mismatch symptoms:

| Symptom | Cause |
|---|---|
| `.NET assemblies not found` dialog (looks for `engine/bin/GodotSharp/Api/Debug`) | no `GodotSharp` present |
| `Wrapper class not found for type: Terrain3D` / `MultiSkinnedMeshInstance3D` — terrain renders as water, animals don't animate | **stale** `GodotSharp` from an older engine that predates the built-in Terrain3D / agent_skinned modules |

So: always **replace `GodotSharp` wholesale** when you take a new binary, and clear the game's C#
cache so it rebuilds against the new bindings.

## Assumed layout

```
tinqs-ltd/
  ariki-game/    ← the game  (looks for ../engine/bin/…)
  engine/bin/    ← install target: binary + GodotSharp live here
  builds/        ← this repo (prebuilt engine)
```
Adjust paths below if your checkout differs.

## 1. Pull the game repo + the builds repo

```bash
cd <…>/ariki-game && tinqs pull   # latest game code (4.7 cutover etc.)
cd <…>/builds     && tinqs pull   # latest engine binary + GodotSharp (LFS)
```
Never `git pull` — `tinqs` handles LFS + auth. If a repo is missing, clone first:
`tinqs clone tinqs/ariki-game` / `tinqs clone tinqs/builds` (and `tinqs/ariki-sim` if you run the sim).
Check `builds/manifest.json` for the current version/commit per platform.

## 2a. Install — macOS (arm64)

```bash
BUILDS="<…>/builds"; ENGINE="<…>/engine/bin"; GAME="<…>/ariki-game"
mkdir -p "$ENGINE"
# 1) binary
cp "$BUILDS/engine/macos-arm64/tinqs.macos.editor.arm64.mono" "$ENGINE/"
chmod +x "$ENGINE/tinqs.macos.editor.arm64.mono"
# 2) GodotSharp — REPLACE wholesale (matched pair)
rm -rf "$ENGINE/GodotSharp"
cp -R "$BUILDS/engine/macos-arm64/GodotSharp" "$ENGINE/GodotSharp"
# 3) clear the game's stale C# cache
rm -rf "$GAME/.godot/mono"
```

## 2b. Install — Windows (x64), PowerShell

```powershell
$builds="<…>\builds"; $engine="<…>\engine\bin"; $game="<…>\ariki-game"
New-Item -ItemType Directory -Force -Path $engine | Out-Null
# 1) binaries
Copy-Item "$builds\engine\windows-x64\tinqs.windows.editor.x86_64.mono.exe" $engine -Force
Copy-Item "$builds\engine\windows-x64\tinqs.windows.editor.x86_64.mono.console.exe" $engine -Force
# 2) GodotSharp — REPLACE wholesale (matched pair)
Remove-Item -Recurse -Force "$engine\GodotSharp" -ErrorAction SilentlyContinue
Copy-Item -Recurse "$builds\engine\windows-x64\GodotSharp" "$engine\GodotSharp"
# 3) clear the game's stale C# cache
Remove-Item -Recurse -Force "$game\.godot\mono" -ErrorAction SilentlyContinue
```

## 3. Verify

```bash
"$ENGINE/tinqs.macos.editor.arm64.mono" --version          # matches manifest.json
ls "$ENGINE/GodotSharp/Api/Debug/GodotSharp.dll"            # MUST exist
```
Then run the game (`cd ariki-game && bash tools/game.sh run`). Healthy = terrain renders, animals
animate, log shows **0** `Wrapper class not found` and no `.NET assemblies not found` dialog.

## Notes

- **GodotSharp must be present in this repo for the copy to work.** If `builds/engine/<platform>/GodotSharp`
  is missing, the build owner needs to add it (it ships *with* the binary — see `manifest.json`).
- Don't mix a new binary with an old `GodotSharp`. Always replace both, together.
- Terrain3D and the skinned-animation classes are **built into the engine binary** now (no separate
  `addons/terrain_3d` GDExtension `.framework`). If you still have `addons/terrain_3d/terrain.gdextension`
  or the macOS `.framework`, remove them — they conflict with the built-in module.