godot-binding-dev

name

godot-binding-dev

description

Working on the Scala Native ↔ Godot GDExtension binding in this workspace — the gdext library, the igen code generators, the sbt-godot-scala-native plugin, or harness-scala game classes. Use when touching Variant/GString/StringName/math-type marshalling, generated engine classes, Ptrcall or MethodBind, the FFI Interface, GodotScriptClass/ClassMeta/casting/refcounting, class registration macros (Register.auto, @func, @gdexport, @signal, ExportType, ExportHint, comp-enum dropdowns), RegistrationScan auto-discovery, the generated entry point, editor hot-reload, the godot_scala editor addon, publishing/JitPack/versioning, or when hitting segfaults, "Cannot get class", stale-NIR link errors, editor freezes on reload, or struct/sizeof/FFI crashes. Carries the co-development build order and an index of per-layer reference docs.

Binding development

Build order (non-negotiable)

harness-scala consumes the binding and plugin as published artifacts — there is no source ProjectRef. So any change under language-binding-scala/ (binding code, generator, or plugin) must be republished before harness will see it:

cd language-binding-scala && sbt publishLocal   # gdext + plugin @ 0.1.6
cd harness-scala          && sbt godotBuild     # generate, compile, link, swap .so

Skipping the publish links the previous jar and shows up as a confusing runtime failure, not a build error. The check-publish-local hook warns when binding sources are newer than the last publish.

Other commands:

• cd language-binding-scala && sbt igen/regenerate — regenerate FFI, engine classes, and the node validation harness from the dumped API JSON.
• cd harness-scala && sbt clean — required after moving the entry symbol; stale .nir causes "multiple definition of godot_scala_init".
• sbt --client "~godotBuild" — what the editor addon runs for hot-reload.

To prove a change works, use the godot-binding-verify skill. A clean compile is not proof.

Never hand-edit (generated)

Path	Regenerate with
gdext/classes/ (~1025 files)	igen/EngineClassGenerator.scala → sbt igen/regenerate
gdext/internal/ffi/	igen/InterfaceGenerator.scala → sbt igen/regenerate
godot/scala.gdextension	plugin godotManifest; tune godotLibName / godotCompatibilityMinimum / godotManifestName
game/GeneratedRegistrations.scala, game/GeneratedEntry.scala	RegistrationScan (runs every compile)
game/harness/Harness*.scala, godot/harness_manifest.json, godot/node_harness.tscn	igen/HarnessClassGenerator → sbt igen/regenerate

A PreToolUse hook blocks edits to the first three. When editing the editor addon, change both the plugin's template resource and the installed copy in godot/addons/godot_scala/ — they differ only in SBT_PROJECT_DIR.

Reference map

Read only what the task needs.

Reference	Read when you need to…
architecture.md	understand modules, package layout, public-vs-internal surface, bootstrap, publishing
conventions.md	recall hard-won gotchas: struct writes, sizeof, the C ABI exception boundary, hot-reload protocol, logging split
layer1-ffi.md	touch the raw GDExtension FFI, interface loading, or gdextension_interface.json codegen
layer2-builtin.md	work on Variant, GString/StringName, math types, Array/Dictionary marshalling
layer3-engine.md	work on generated engine classes or the engine-class generator
layer4-obj.md	work on casting, refcounting, instance lifetime, ClassMeta (note: there is no Gd[T] smart pointer)
layer5-register.md	register user classes: macros, annotations, methods/properties/signals, export hints

Invariants worth restating

• Public surface is gdext.api, gdext.classes, gdext.builtin, gdext.annotations. Everything else is gdext.internal.*, much of it private[gdext] and compiler-enforced.
• Never let exceptions unwind across the C ABI — catch at the boundary.
• Dev version is 0.1.6; releases are plain semver tags built by JitPack.

Maintenance

When you change the project's structure or discover a new gotcha, update the matching references/*.md — that is how a from-scratch session stays accurate. Add binding and plugin changes to the topmost Unreleased section of the root CHANGELOG.md.