Contributor Guide¶
This section is for changing Kanama itself: runtime code, generated wrappers, Android support, demos, documentation, and release-facing validation.
Start with the root CONTRIBUTING.md, then read the page that matches the area
you are changing:
- Architecture before touching bootstrap, FFI, script lifetime, ClassDB registration, or hot reload.
- Wrapper Maintenance before changing generated wrappers, generator policy, ABI helpers, or generated KDoc.
- Shared Wrapper Tree: Design Check before proposing to merge the desktop and iOS generated wrapper trees.
- Godot Upgrade Runbook before bumping the Godot engine baseline.
- API Coverage and Wrapper Generator Report (generated reports) before promoting wrapper coverage or changing generator skip policy.
- Hot Reload Internals before changing script reload behavior or reload smoke checks.
- Demo Porting Rules before changing demo ports or gameplay parity checks.
- The backend internals pages, one per non-desktop platform, before changing that platform's runtime or export support: Android Internals, iOS Backend Architecture, and Web Internals (the Kotlin/Wasm backend, its generated proxy, and the versioned JS bridge). The user-facing export workflow for each lives under Shipping Your Game; these pages hold the design and the gates.
- Gates and Claims before adding or changing a check: the local gate, the rules every gate script follows, red runs and the checks that read the docs.
- Release Process before building packages, changing a platform's support status or cutting a release.
- Gates Index (generated from
local_ci.sh, the workflows, and the ledger) to find what eachlocal_ci.shstage, CI job, and local-only device/browser gate proves and where it runs, and to see theevidence/gates.jsonledger of when those local gates last ran on the current Godot pin.
Landing a change that removes a limitation is its own kind of change: the
comments asserting that limitation are now false and nothing else will notice.
Grep for them, and see "Documented Limitations" in the root CONTRIBUTING.md
for the KANAMA-BLOCKED marker that makes the machine-checkable ones fail the
build the day they go stale.
Building From Source¶
The user steps are on Install From a Source Checkout. What sits under them:
- The desktop native bootstrap is built from the GDExtension headers tracked in this repository, the JDK 25 headers, CMake and the platform C toolchain. No Godot source checkout is involved.
- Gradle passes its JDK 25 toolchain to CMake as
-DKANAMA_JAVA_HOME. Without Gradle,bootstrap/CMakeLists.txtusesJAVA_HOME, then on macOS/usr/libexec/java_home -v 25, then the system default JDK. - On every OS the configure step stops with a message naming the JDK it found
when that JDK's
jni.hhas noJNI_VERSION_21, so a bareJNI_VERSION_21 undeclaredfrombootstrap.cdoes not appear. ./gradlew syncExampleAddonJarrefreshes the checked-inexample_projectand is the local smoke-test path for it: the counterpart ofinstallAddonJarfor that project.
JDK Lookup¶
The user rules are on JDK Selection.
The Kanama Tools plugin (plugin.gd) and the native runtime (bootstrap.c)
resolve the JDK the same way; scripts/check_jdk_locations_parity.py keeps
their install-folder tables equal and scripts/check_jdk_lookup_parity.sh
compares their picks.
- Order. The
kanama/build/jdk_patheditor setting, thenJAVA_HOMEfrom the editor's environment, then the best JDK in the install folders. - Install folders. A JDK counts when its
releasefile says 25 or newer andlib/server/libjvm.*exists. Among those, a GA release beats an early-access one, exactly 25 beats a newer major version, then the newer version wins, then the path that sorts first. - The editor setting must be an absolute path;
~/is expanded. A wrong value is an error, never silently replaced by another JDK. AJAVA_HOMEolder than 25 is skipped, not an error, since it is usually set for another project. - Build Scripts needs a full JDK with
include/jni.h, because a JRE cannot compile the native bootstrap. If none qualifies, the build stops before it starts with an error that nameskanama/build/jdk_pathandJAVA_HOME. The bootstrap's CMake step also checks thatjni.hdefinesJNI_VERSION_21(a JDK 21 or newer header) and names the JDK when it does not. - The runtime cannot read editor settings when Godot loads it. The plugin
writes a valid
kanama/build/jdk_pathto.godot/kanama_jdk_homein the project, and removes the file when the setting is empty or invalid; the runtime reads that file first. If the JDK it names has been removed or is older than 25, the runtime logs[kanama] ignoring .godot/kanama_jdk_home=...with the reason and goes on withJAVA_HOMEand the install folders. The runtime reads the file once, when Godot loads the extension, which is before the plugin can write it. So on the first open of a project (a fresh clone, a deleted.godot) with the setting set, and after any change to the setting, the plugin warns "Restart the editor to use JDK ..." instead of reporting OK. - Gradle runs on any JDK 25+. The build pins
jvmToolchain(25); with only another JDK installed (a JDK 26-only machine, say), the foojay toolchain resolver insettings.gradle.kts, and in the release kit'ssettings.gradle.kts, downloads a JDK 25 once into~/.gradle/jdks. - An exported game with a bundled runtime ignores all of this and uses its
own
runtime/folder.
Use the narrowest useful check while iterating, then run the broader local gate before release-facing changes:
./gradlew check -PkanamaBuildNativeBootstrap=false
mkdocs build --strict
python3 scripts/check_wrapper_generator.py
./gradlew jvmJar
./scripts/local_ci.sh /path/to/godot
-PkanamaBuildNativeBootstrap=false skips the native bootstrap build, so the
Gradle checks run without CMake.
For release-facing changes, prefer the fresh-clone gate so the result does not depend on your active development checkout or old local build state:
./scripts/fresh_clone_smoke.sh /path/to/godot