godot-binding-verify

name

godot-binding-verify

description

Verify a change to the Scala Native Godot binding actually works by running the Godot project headless — the ONLY real proof, since a clean sbt compile or nativeLink proves nothing. Use after editing anything in language-binding-scala (gdext binding, igen generator, sbt-godot-scala-native plugin) or harness-scala game classes, and before committing or claiming a binding change works. Covers the publishLocal → godotBuild → headless-run order, which verify script to pick (verify.gd, export_verify.gd, export_hints_verify.gd, export_comp_verify.gd, node_harness_verify.gd, the hot-reload and comp-enum editor addons), and which error strings mean failure ("Cannot get class 'X'", missing library, registration failure).

Verifying a binding change

A clean sbt compile is not proof. Compilation says the Scala typechecks; it says nothing about whether the .so loads, classes register with Godot, or ptrcall marshalling is correct. Only a clean headless run proves that.

The loop

Always in this order — harness consumes published artifacts, so skipping step 1 after a binding change silently links the previous jar:

cd language-binding-scala && sbt publishLocal   # after ANY change here
cd harness-scala          && sbt godotBuild     # generates + native-links + swaps .so
cd godot && godot --headless --path . --quit-after 5

godotBuild also regenerates godot/scala.gdextension and installs the editor addon. After moving the entry symbol, cd harness-scala && sbt clean first — stale .nir gives "multiple definition of godot_scala_init".

Which script proves what

Run from godot/. Scene runs use --quit-after N; script runs use --script.

Script	Proves	Invocation
verify.gd	core registration, methods, signals, properties	godot --headless --path . --script verify.gd
export_verify.gd	@gdexport round-trips, typed Arr/Dict defaults	--script export_verify.gd
export_hints_verify.gd	export hints / ranges / enum hints reach the inspector	--script export_hints_verify.gd
export_comp_verify.gd	component-reference dropdown property lists	--script export_comp_verify.gd
node_harness_verify.gd	all ~238 node types generate + subclass + register; prints HARNESS VALIDATION: PASS	--script node_harness_verify.gd
addons/hot_reload_verify/	E2E editor hot-reload (edit → rebuild → reload → property visible)	godot --headless -e -- verify-hot-reload
addons/comp_enum_verify/	comp-enum dropdowns in a real editor session	godot --headless --editor --path . -- verify-comp-enum

Pre-warm the hot-reload test with a sbt godotBuild first, or the cold sbt server blows its timeout.

Read the output — exit 0 is not enough

Godot exits 0 on plenty of failures. Scan stdout for:

• Cannot get class 'X' — the class never registered (registration failure, or the .so loaded an older image).
• Can't open dynamic library / missing library — the swap did not land, or scala.gdextension points at the wrong path/name.
• ERROR: / SCRIPT ERROR: — anything here is a failure even with exit 0.
• Silence where a self-test banner should be — the entry symbol never ran.

Logs split: binding internals → godot/.scala/log (file); game code → Godot's Output/stdout. GODOT_SCALA_TRACE=1 (or a .scala/trace file) turns on the verbose reload trace with thread ids + ms timestamps.

Scope limits

A headless runtime run cannot catch editor-only regressions — placeholder handling, inspector plugin behaviour, and reload recreate paths only manifest in an editor session. If the change touches registration flags (is_runtime), editor integration, or anything under EditorIntegration, run the editor-context addons above too; a passing scene run is not sufficient evidence there.