Skip to content

Android Internals

This page records the current Android implementation path: the runtime design, the PanamaPort fork, and the audits that guard the source remap. The support tier and the device evidence behind it are in Platform Evidence → Android; the user-facing export workflow is Export for Android. The API/build flow is less settled than the desktop path.

What Works

The nine Android smoke targets (the eight starter/creeps demos plus Bunnymark; tps-demo-kanama also carries an Android preset but sits outside the automated matrix) and their device results are the Android demo matrix. The 3D Platformer and third-person controller runs are the stronger signals because they exercise larger scenes, Android input overlays, and gameplay warmup paths. The exported APK path:

  • loads the Android Godot plugin AAR,
  • loads libkanama_bootstrap.so from the APK,
  • captures the Android JVM through JNI,
  • initializes the Kanama GDExtension,
  • registers KanamaScriptLanguage,
  • registers the .kt resource loader,
  • loads project Kotlin scripts,
  • reaches OnGodotMainLoopStarted, and
  • renders the 3D scene through Godot's OpenGL compatibility renderer.

This proves the Kanama runtime path on Android, including the forked-PanamaPort minified path. The validated Android version floors per build type are in Platform Evidence → Validated Android Versions.

Toolchain Versions

Kanama itself builds on the desktop JDK and Godot's Android Gradle export runs on its own JDK; both versions, and the Godot pin, are in Requirements and Platform Status. The Android game runtime is ART plus PanamaPort, not a desktop JDK. The full set of Android tool versions:

Tool Version / Setting
Godot Android export template AGP 8.6.1
Godot Android export template compile SDK 36
Godot Android export template target SDK 36
Godot Android export template min SDK 24
Godot Android export template build tools 36.1.0
Godot Android export template NDK 29.0.14206865
Kanama Android plugin AGP 9.2.1
Kanama Android plugin compile SDK 36
Kanama Android plugin min SDK 33 (Android 13; the export guard stops a lower preset Min SDK)
Kanama Android plugin CMake 3.22+ (cmake_minimum_required; AGP's default 3.22.1 is what builds it)
Kanama AAR ABIs arm64-v8a, x86_64
Demo APK export ABI arm64-v8a

Configure Android SDK, NDK, CMake, and JDK locations through Godot editor settings or standard environment variables such as ANDROID_HOME, ANDROID_SDK_ROOT, and JAVA_HOME. Godot's export-template build needs the SDK platform, build-tools, and NDK versions in the table installed. Do not commit workstation-local paths.

The user page, Export for Android, lists only the SDK packages a game developer installs.

Plugin Files

The Android deliverable is two AARs (runtime/scripts split, mirroring desktop's kanama.jar / kanama-scripts.jar):

  • Runtime AAR (KanamaAndroid.debug.aar, project-agnostic): the Godot Android plugin class, a Java bootstrap that loads libkanama_bootstrap.so, the Android native bootstrap library, remapped Kanama runtime classes, and .gdextension metadata for Android AAR loading.
  • Scripts AAR (KanamaAndroidScripts.debug.aar, per project): the game's Kotlin scripts and generated KSP registrars, remapped and compiled against the runtime classes. The runtime plugin's .gdap references it as a local dependency, so both AARs land in the exported APK.

PanamaPort dependency metadata is declared in the .gdap. The exported game runs on Android ART with PanamaPort as the FFM layer rather than on a desktop JVM — how that works, and how the source remap is audited, is below. Game projects should not need JNI code, a custom Godot fork, or hand-edited Android native code.

installAndroidPluginAar builds android/godot-plugin (both halves), compiles the Android native bootstrap from bootstrap/bootstrap.c, writes android/plugins/KanamaAndroid.debug.aar (runtime) and android/plugins/KanamaAndroidScripts.debug.aar (your project's scripts + registrars, generated by this checkout's KSP processor over kotlin-src/), and writes android/plugins/KanamaAndroid.gdap referencing both.

installAndroidPluginAar also writes the Android entries into the project's addons/kanama/kanama.gdextension:

[configuration]
android_aar_plugin = true

[libraries]
android.debug.arm64 = "libkanama_bootstrap.so"
android.release.arm64 = "libkanama_bootstrap.so"
android.debug.x86_64 = "libkanama_bootstrap.so"
android.release.x86_64 = "libkanama_bootstrap.so"

The Android plugin AAR also carries matching .gdextension metadata. The project file uses Android entries so Godot's export scanner recognizes the GDExtension for Android instead of warning about a missing arm64 library.

Godot 4.7.2's --install-android-build-template flag only takes effect together with an export; the smoke scripts install the template by hand from android_source.zip when it is missing. The generated KanamaAndroid.gdap declares JitPack as a custom Maven repository (custom_maven_repos), which Godot passes to its Android Gradle build, so the PanamaPort fork resolves in a plain editor export. android_smoke.sh and android_export_minified.sh add no repository of their own, so they exercise exactly what a user's export gets and fail if the .gdap loses that entry. For a fork published elsewhere (for example to ~/.m2 while iterating), set KANAMA_PANAMAPORT_MAVEN_REPO=file://$HOME/.m2/repository (with KANAMA_ANDROID_TEMPLATE=reuse for android_export_minified.sh, which patches the installed template's build.gradle) and pass the coordinate as ORG_GRADLE_PROJECT_kanamaPanamaPortCore=<test coordinate>. Godot passes -Pplugins_maven_repos on its Gradle command line, so a plugins_maven_repos value in android/build/gradle.properties has no effect. The user page names the coordinate only as "PanamaPort"; -PkanamaPanamaPortCore=<coordinate> on installAndroidPluginAar selects another build, and the coordinate is printed in the Gradle build log.

The Kit Path

A project made from a desktop kit or the store addon has no checkout to build from. Its build.gradle.kts applies the Kanama Gradle plugin (net.multigesture.kanama, gradle-plugin/), which kits and the store addon carry in addons/kanama/maven beside the runtime AAR (kanama-android, the :plugin AAR, published by publishKanamaAndroidPackage). The plugin's buildAndroidScripts is installAndroidPluginAar without the checkout:

  1. It depends on the project's buildScripts, so the registrars come from the project's own KSP run of the kit's processor (build/generated/ksp/main/kotlin), the same processor the checkout runs.
  2. It audits kotlin-src/ and remaps it and the registrars with KanamaAndroidRemap, compiled into the plugin from android/godot-plugin/buildSrc (one copy of the remap and its audits).
  3. It writes a plugin-owned Gradle build to build/kanama/android/ (the resources under gradle-plugin/src/main/resources/.../android/, rewritten on every run) and runs it with the project's gradlew: an AGP library module, compileOnly on kanama-android, PanamaPort and coroutines, the same API level as :scripts. Its settings declare exactly four repositories, with addons/kanama/maven the only one allowed to serve net.multigesture.kanama and no mavenLocal().
  4. It installs both AARs and the .gdap, edits the descriptor (KanamaAndroidPluginFiles, gradle-plugin/src/shared, which the root buildSrc compiles too, so installAndroidPluginAar writes the same files), and turns on rendering/textures/vram_compression/import_etc2_astc in project.godot.

Every version the inner build uses (AGP, the Android Kotlin, compileSdk, minSdk, the API level, coroutines, PanamaPort) is in the generated KanamaVersions object, which gradle-plugin/build.gradle.kts reads from the files that pin them for the checkout (android/godot-plugin/build.gradle.kts, gradle.properties and scripts/build.gradle.kts; the root build for PanamaPort). scripts/check_kit_version_pins.py holds the copies the kit restates by hand. scripts/package_install_smoke.sh --android runs the documented commands from an unzipped kit or store addon with a fresh GRADLE_USER_HOME and checks the APK; package.yml runs it on Linux.

PanamaPort

The Android implementation uses a forked PanamaPort artifact, published via JitPack: com.github.falcon4ever.PanamaPort:Core:0.1.5-kanama-r8.1 — upstream v0.1.5 plus the Kanama patches listed below.

Upstream PanamaPort v0.1.3 miscompiles under Godot 4.7's R8 because its Android linker uses Java pattern switches over sealed storage/layout types. The fork rewrites the affected switch sites to explicit instanceof chains and is published to the configured local Maven repository for Android exports. Keep the fork diff small and retire it when the upstream artifact carries the fix.

The root cause, in full. R8/ProGuard minification is validated only with the fork. Root-caused on a Pixel 7 (2026-06-26), upstream PanamaPort v0.1.3 crashes in the FFI bootstrap at nativeLinker().downcallHandle() with AssertionError: Should not reach here; the recurring No loader found for resource: res://kotlin-src/*.kt and flickering splash are downstream of that crash. Deobfuscated, PanamaPort's Android linker (_AndroidLinkerImpl) builds native stubs with Java pattern-matching switches over sealed types (_LLVMStorageDescriptor storages and the MemoryLayout hierarchy), and Godot 4.7's R8 (AGP 8.6.1) mis-optimizes those switches so they fall through to default -> Utils.shouldNotReachHere(). This is unfixable from consumer keep rules: keeping the sealed types blocks the optimization PanamaPort's own @CheckDiscard rules require, failing the build; not keeping them leaves the switch broken at runtime. The fork rewrites the affected source switch sites to explicit instanceof branches and adds targeted R8 annotations/signing mechanics. scripts/android_export_minified.sh builds, installs, launches, and verifies the minified Match3 release APK on Pixel 7 (Android 16) and Moto g 5G 2023 (Android 14).

A second R8 landmine was fixed in fork r8.4 (2026-07-13): AGP 8.6.1's R8 collapses a one-element byte[]... varargs call into filled-new-array of byte[][], which the ART interpreter below Android 13 segfaults on; the fork's NativeCodeBlob.makeCodeBlobSingle removes the only such site. Fork r8.3 added the SDK_INT_FULL bootstrap guard that every device below Android 16 needs. Release builds below Android 13 crash on a separate release-mode PanamaPort constraint, which is why Android 13 (API 33) is Kanama's minimum; the evidence is in Platform Evidence → Validated Android Versions.

Keeping the fork close to upstream

The fork is upstream PanamaPort plus a short list of Kanama patches, rebased onto each upstream release rather than left to drift. Android OS updates do not follow Godot's schedule: in September 2026 a Pixel 7 took an Android 17 update (build CP3A.260905.009) and every Kanama app aborted in the FFI bootstrap (Check failed: IsExceptionPending() in MethodHandles.reflectAs, called from PanamaPort's hidden-field reflection) — the same phone had passed the full matrix on an earlier Android 17 build two weeks before — while upstream had shipped the Android 17 QPR fixes in v0.1.4/v0.1.5 and the fork was still on v0.1.3. Fork 0.1.5-kanama-r8.1 (upstream v0.1.5) fixed it with no Kanama code change.

The Kanama patches carried on top of upstream (none of them is in upstream v0.1.5):

Patch Why
Sealed-type switches rewritten as instanceof chains (+ R8 annotations) Godot's R8 miscompiles the pattern switches into shouldNotReachHere (minified release builds).
JitPack publishing (single release variant, unsigned local publish) JitPack serves the classified multi-variant AARs as 404s.
ArtVersion.SDK_INT_FULL_COMPAT Upstream reads the Android-16-only SDK_INT_FULL unconditionally; every device below 16 fails the bootstrap.
NativeCodeBlob.makeCodeBlobSingle R8 turns a one-element byte[]... call into filled-new-array [[B, which crashes ART's interpreter below Android 13. Below Kanama's minimum (API 33) since 2026-10-21, so a rebase may drop it.
compileSdk kept at 36 Upstream's 37 stamps minCompileSdk=37 into the AARs, which Godot 4.7.2's export template (compileSdk 36) rejects.

Rebase routine: before every Kanama release, compare the fork's upstream base with upstream's latest release and rebase if they differ; after an Android major or QPR update on a validation device, run the Android smoke early. A rebase is the table above as a checklist: re-apply each patch, drop it if upstream now covers it, prove the result on a device with the nine-demo matrix and the R8-minified Match3 release (-PkanamaPanamaPortCore=<test coordinate> switches the AARs and the .gdap end to end).

Desktop vs Android FFM

Desktop Kanama uses the JDK and java.lang.foreign.

Android does not run a desktop JDK inside the game. The Android runtime uses ART, and the Android build maps the Kanama FFM-facing code to PanamaPort's com.v7878.foreign package.

The build tools are also separate from the runtime: Kanama itself builds on the desktop JDK, Godot's Android Gradle export flow runs on its own JDK, and the exported game runs on ART and PanamaPort, not on a desktop JVM. The versions are in Requirements and Platform Status and the Android toolchain table.

Native heap pointers on Android are tagged: the top byte is 0xB4 (Android 11+ pointer tagging), so a malloced address is negative as a signed long. Pass it to native code as a value freely, but never use it as a segment offset: a whole-address-space segment (MemorySegment.NULL.reinterpret(Long.MAX_VALUE)) addressed with absolute addresses works on the desktop and throws IndexOutOfBoundsException on the device (task 138 item 21: every typed signal emit failed this way, through its heap-allocated frame; the signal-lambda argument reads and call-error writes, which Godot usually hands stack pointers, were changed too as hardening). Read and write through the pointer's own segment (ptr.reinterpret(size), offsets relative to it); keep that segment local on a hot path, so the JIT removes it. scripts/check_android_remap_sources.py rejects the idiom in the runtime sources.

A typed signal has to be seen firing on the device, not assumed from the desktop run. Kanama's own smokes therefore switch on a test hook, SignalSelfTest (src/jvmMain/kotlin/binding/runtime/SignalSelfTest.kt, task 138 item 23; shared JVM runtime code). It is off for users: it costs about 15-20 ms and a hundred classes on the first frame and registers an extension class, so it runs only when the project setting kanama/debug/signal_self_test is true in a debug build (KANAMA_SIGNAL_SELFTEST=1 / 0 forces it on / off on the desktop, where an environment variable can be set; an Android app needs the setting). scripts/android_smoke.sh backs up the demo's project.godot, writes the setting for the run and restores the file on exit, so android_smoke_all.sh gets it on every demo.

On the first frame it emits Signal0..Signal5 from Kotlin with a Long, Double, Boolean, String, Vector3 and an Object, received by a lambda and by a Callable to a method of a registered class (Godot's half of the @Function path: Callable, method bind, call_func; not the decoder KSP generates for a @Function), plus a one-shot connection, nested emits and the release of everything it created. A clean run logs

[kanama] SIGNAL SELFTEST: <n> passed, 0 failed in <ms> ms

and scripts/android_smoke.sh (like scripts/runtime_smoke.sh on the desktop) fails without a line with a non-zero pass count and 0 failed, or with any SIGNAL SELFTEST FAIL: <row> got <values> line. The <ms> is the cost of the test on the device. A new signal path that only the device can break belongs here as another row.

The smokes switch on a second hook the same way, OwnershipSelfTest (src/jvmMain/kotlin/binding/runtime/OwnershipSelfTest.kt, task 138 item 6): project setting kanama/debug/ownership_self_test, KANAMA_OWNERSHIP_SELFTEST=1 / 0 on the desktop. Over a few seconds of frames from the first one, a worker thread drops 10,000 owned Resources, which the collector and the main-thread drain must release; then for 5 s a worker calls getRid() on fresh owned Resources while every frame starts with a full collection (what KANAMA_GC_STRESS=1 does for a whole run); then it times a getter on the main thread, the same raw ptrcall without and with ObjectCalls.keepReachable after it, and the fence alone against the same empty loop (the fence's cost on ART). A clean run logs

[kanama] OWNERSHIP SELFTEST worker-owned GC releases: created=10000 released=10000 leaked=0 waited_ms=<ms> frames=<n> drained=<n> backlog=<n>
[kanama] OWNERSHIP SELFTEST worker GC stress: seconds=5 calls=<n> faults=0
[kanama] OWNERSHIP SELFTEST getter microbench ns/call: fence_off=<a> fence_on=<b> getter=<c> owned_get_close=<d> fence_alone=<e> loop_alone=<f> (best of 5 rounds of 20 ms per loop)
[kanama] OWNERSHIP SELFTEST: 3 passed, 0 failed in <ms> ms

Every frame does a bounded step (a slice of the id checks, one microbench round), because an FFI call costs several times more on ART than on HotSpot; the whole test takes about 15 s on a Pixel 7. scripts/android_smoke.sh waits for the verdict line after the launch wait (at most KANAMA_ANDROID_SELFTEST_WAIT more seconds, default 90) and fails on a missing verdict, a failed count above zero or an OWNERSHIP SELFTEST FAIL line.

The generated API exercise (ApiExerciseHook, one row per ObjectCalls helper the shared tree calls; see API Exercise Inventory and Wrapper Maintenance) is the same JVM code on ART, so it runs on the device on request: KANAMA_ANDROID_API_EXERCISE=1 scripts/android_smoke.sh ... builds the runtime AAR with -PkanamaApiExercise=true (the plugin copy then keeps the exercise/ sources it otherwise excludes), writes kanama/debug/api_exercise=true beside the two settings above, waits for the summary as it does for the ownership verdict and fails on any API EXERCISE FAIL line or a summary other than

[kanama] API EXERCISE: <n> passed, 0 failed, <w> weak, <k> known, <r> reach, <e> excluded in <ms> ms

The exercise stays opt-in on Android and runs on Match3 only: on a Pixel 7 it takes about 4 s of the first frame (340 passed, 0 failed, 254 weak ... in 3960 ms, against about 0.25 s on an iPhone 12), over the 2 s a first-frame test hook may cost. The desktop Godot runs inside the smoke (export, exported-scene check) get KANAMA_API_EXERCISE=0, which wins over the project setting the smoke writes. KANAMA_ANDROID_API_EXERCISE_TRACE=1 adds kanama/debug/api_exercise_trace (a line before each row, so a crash names its row). Without the variable the smoke checks that no API EXERCISE line appears. The rows run as platform android: DirAccess.get_drive_name(0) may be "" there, where a zero counts weak (STATIC_ZERO_ON). A flagged AAR is for that debug APK only: the plugin build refuses a release variant or a publication with the flag, publishKanamaAndroidPackage reads the AAR it publishes for exercise classes, and android_export_minified.sh (the release path) and CI's Android lane run generate_api_exercise.py --check-jar on the AAR. The demo keeps the flagged AAR until the next installAndroidPluginAar without the flag (the setting is restored, so the rows do not run).

Implementation Shape

The current Android implementation lives under android/godot-plugin, split into two AAR modules (task 36; mirrors desktop's kanama.jar / kanama-scripts.jar shape):

  • :plugin — runtime AAR (project-agnostic, KanamaAndroid.debug.aar): a Godot Android plugin class, a small Java bootstrap that loads libkanama_bootstrap.so, the Android native bootstrap library, the remapped Kanama runtime + annotations sources, and a .gdextension file marked as an Android AAR plugin. Builds with no consumer project (assembleAndroidPluginAar); publishKanamaAndroidPackage publishes it as net.multigesture.kanama:kanama-android into the package repository, so every kit and the store addon carry it in addons/kanama/maven.
  • :scripts — scripts AAR (per project, KanamaAndroidScripts.debug.aar): the consumer project's kotlin-src/ scripts and generated KSP registrars, remapped identically and compiled against the runtime classes (compileOnly(project(":plugin"))). The runtime .gdap written by installAndroidPluginAar references it as a local= dependency, so Godot's export adds both AARs and they dex into the same APK classloader — registrar lookup needs no loader-aware path.

Where the demo scripts are compiled from: this checkout, never mavenLocal. assembleAndroidScriptsAar (run by installAndroidPluginAar) first runs :project-scripts:kspKotlin over the project's kotlin-src/ (the root project-scripts build reads -PkanamaAndroidDemoDir), so the registrars the scripts AAR copies come from this checkout's KSP processor and API, and hands that output directory to the Android build as -PkanamaAndroidKspDir. The demo's own Gradle build (<demo>/gradlew, <demo>/build/generated/ksp) is not used: it resolves kanama/processor from mavenLocal, so a branch's API or processor change would have been checked against whatever main last published (task 119 item 40). scripts/android_smoke.sh and scripts/android_export_minified.sh also compile the scripts up front with :project-scripts:jar -PkanamaProjectScriptsDir=<demo>/kotlin-src, the path the demos' desktop CI lane uses, so an API break fails before the Android build, and the export-time desktop addon (installAddonJar) comes from the same checkout. To prove it without a device, run assembleAndroidScriptsAar from a scratch copy of the checkout whose processor writes a marker comment into the script registrars and look for the marker under android/godot-plugin/scripts/build/generated/kanamaAndroidScriptSources.

Both modules copy sources into generated Android source trees through the same PanamaPort compatibility remap, shared in buildSrc (KanamaAndroidRemap). The remap is deliberately guarded per module: auditAndroidKanamaSources (runtime) and auditAndroidKanamaScriptSources (scripts, plus the pre-remap demo-source audit) fail the Android build if stale desktop-only APIs or incorrectly rewritten Kotlin callback calls appear in the generated trees.

R8 note: the runtime AAR's consumer-rules.pro applies APK-wide, so its keeps for net.multigesture.kanama.generated.** and **.KanamaRegistry cover the scripts AAR's classes too — no second rules file is needed.

The demo project needs Android entries in addons/kanama/kanama.gdextension:

[configuration]
android_aar_plugin = true

[libraries]
android.debug.arm64 = "libkanama_bootstrap.so"
android.release.arm64 = "libkanama_bootstrap.so"
android.debug.x86_64 = "libkanama_bootstrap.so"
android.release.x86_64 = "libkanama_bootstrap.so"

The Android AAR also includes matching .gdextension metadata. The project file uses Android entries so Godot's export scanner recognizes the extension for Android instead of warning that no arm64 library exists.

Current Boundaries

The current Android path is intentionally narrow:

  • Android runs on ART, so the bootstrap attaches to the VM the app already has instead of creating a desktop JVM, and Kotlin classes load from the APK at startup. Hot reload is desktop-editor-only.
  • The Android source remap is a guarded Gradle step rather than a dedicated source-set design.
  • Some JVM APIs used on desktop have Android-compatible replacements.
  • Android downcall handles must go through invokeWithArguments(...); desktop keeps the direct invoke(...) and invokeExact(...). Compiled against android.jar, Kotlin emits both direct forms as plain varargs calls (invokeExact(Object[])), which ART rejects at run time. The remap rewrites every .invoke( and .invokeExact( in the Android copy to .invokeWithArguments(, and its audit forbids any .invokeExact( that survives. So in shared sources never call a Kotlin function value or a reflective Method with .invoke(: write f(args) or go through a MethodHandle (scripts/check_android_remap_sources.py fails on both). The hot handles still become static final constants on Android; only desktop gets the exact, JIT-folded call.
  • Demo Kotlin sources are audited before remap for nullable callback invocation such as callback?.invoke(), which would otherwise be rewritten like a low-level method-handle call.
  • The emulator's OpenGL compatibility path can differ visually from desktop rendering. In the 3D Platformer smoke, geometry and gameplay render, but the skybox/background is darker than the upstream desktop screenshot. Logcat also reports unsupported ASTC textures being converted at runtime.
  • The current validated demo exports use Godot's OpenGL Compatibility renderer on Android. Desktop can continue using its normal renderer.
  • Godot Android can also use Vulkan through the Mobile renderer; the nine-demo matrix passed under it on Pixel 7 (2026-07-10), while the demo corpus still ships OpenGL Compatibility as its default mobile renderer.
  • Mobile polish is per demo: screen size, orientation, touch input, and UI scaling are separate from the core runtime path.
  • Physical devices can expose first-use hitches when gameplay first instantiates scenes, decodes audio, starts particles, or builds generated meshes. Demo ports should warm up these resources during startup when Android smoke shows a hitch that is not visible on desktop.

The smoke script force-stops the launched package on exit so emulator runs do not leave demo processes alive after validation.

Validation Shape

Android validation uses the normal demo folders plus Android export metadata, the Kanama Android plugin AAR, adb install, logcat checks, screenshots, and a forced package stop after the run (scripts/android_smoke.sh, scripts/android_export_minified.sh). Which device runs back the current claim, and when they last ran on the current Godot pin, is the Gates Index ledger; never widen the support wording past what those runs validated.