builds/.agents/handoffs/forge-windows-4.7.md

Handoff → Forge (Ozan's Windows box): build Windows 4.7 + ship GodotSharp

Date: 2026-06-19 · From: macOS 4.7 native-module migration · For: Windows build owner

Why

The engine moved to Godot 4.7 and Terrain3D + agent_skinned are now native engine modules (compiled into the binary — no GDExtension .framework). macOS is done and shipped in this repo (engine/macos-arm64/). Windows is still 4.6.5 with the GDExtension and must be brought up to 4.7 the same way, or Windows teammates can't run the new ariki-game (the game-side cutover removed the terrain GDExtension).

The critical bit (don't skip)

After the 4.7 build you must regenerate GodotSharp and ship it next to the binary. A native module changes the engine's class list; the C# bindings (GodotSharp) must be regenerated to include Terrain3D / MultiSkinnedMeshInstance3D, or the game throws Wrapper class not found for type: Terrain3D (terrain = water, animals frozen). The engine does not regenerate GodotSharp at runtime.

Steps (Windows)

1. Sync engine source to the current tinqs/engine main (single 4.7 snapshot, 4ba7b5b).

   cd engine
   tinqs pull            # or: git fetch origin && git checkout main && git reset --hard origin/main
   

2. Build the editor:

   scons platform=windows target=editor arch=x86_64 module_mono_enabled=yes
   scons platform=windows target=editor arch=x86_64 module_mono_enabled=yes windows_subsystem=console   # console binary
   

3. Regenerate the mono glue + GodotSharp assemblies (this is the step that fixes the wrapper errors):

   bin\tinqs.windows.editor.x86_64.mono.exe --headless --generate-mono-glue modules\mono\glue
   python modules\mono\build_scripts\build_assemblies.py --godot-output-dir=bin --godot-platform=windows
   

   Confirm bin\GodotSharp\Api\Debug\GodotSharp.dll exists and that modules\mono\glue\...\Generated\Constructors.cs contains Terrain3D (grep it).
4. If you hit the same build errors I did (already fixed in main, but for reference): a core module can't expose an editor-API type — Terrain3D::set_plugin must take Object* not EditorPlugin*; Terrain3DAssetResource must be GDREGISTER_ABSTRACT_CLASS; drop the redundant Terrain3DRegion::duplicate bind. These are already in main — a clean pull should have them.
5. Drop into this builds repo (engine/windows-x64/):
   • tinqs.windows.editor.x86_64.mono.exe (+ .console.exe)
   • the whole GodotSharp/ folder ← new requirement; was previously .gitignored
6. Update manifest.json windows-x64 block: version 4.7…, engine_commit 4ba7b5b, new sha256s, add "godotsharp": "engine/windows-x64/GodotSharp", clear the "pending" note.
7. tinqs push.

Verify

On a Windows machine with ariki-game: run the update-engine skill (.agents/skills/update-engine, Windows path), launch game.sh run. Healthy = terrain renders, animals animate, 0 Wrapper class not found, no .NET assemblies not found.

Notes

• .gitattributes already LFS-tracks engine/**, so the binary + GodotSharp go to LFS automatically.
• The macOS side in this repo is the reference for exactly what the layout should look like.
• Game-side cutover (GDExtension removal, project.godot→4.7) is committed on ariki-game main (held pending team sync) — Windows teammates need this engine before that lands for them.