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.sofrom the APK, - captures the Android JVM through JNI,
- initializes the Kanama GDExtension,
- registers
KanamaScriptLanguage, - registers the
.ktresource 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 loadslibkanama_bootstrap.so, the Android native bootstrap library, remapped Kanama runtime classes, and.gdextensionmetadata 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.gdapreferences 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:
- 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. - It audits
kotlin-src/and remaps it and the registrars withKanamaAndroidRemap, compiled into the plugin fromandroid/godot-plugin/buildSrc(one copy of the remap and its audits). - It writes a plugin-owned Gradle build to
build/kanama/android/(the resources undergradle-plugin/src/main/resources/.../android/, rewritten on every run) and runs it with the project'sgradlew: an AGP library module,compileOnlyonkanama-android, PanamaPort and coroutines, the same API level as:scripts. Its settings declare exactly four repositories, withaddons/kanama/maventhe only one allowed to servenet.multigesture.kanamaand nomavenLocal(). - It installs both AARs and the
.gdap, edits the descriptor (KanamaAndroidPluginFiles,gradle-plugin/src/shared, which the rootbuildSrccompiles too, soinstallAndroidPluginAarwrites the same files), and turns onrendering/textures/vram_compression/import_etc2_astcinproject.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 loadslibkanama_bootstrap.so, the Android native bootstrap library, the remapped Kanama runtime + annotations sources, and a.gdextensionfile marked as an Android AAR plugin. Builds with no consumer project (assembleAndroidPluginAar);publishKanamaAndroidPackagepublishes it asnet.multigesture.kanama:kanama-androidinto the package repository, so every kit and the store addon carry it inaddons/kanama/maven.:scripts— scripts AAR (per project,KanamaAndroidScripts.debug.aar): the consumer project'skotlin-src/scripts and generated KSP registrars, remapped identically and compiled against the runtime classes (compileOnly(project(":plugin"))). The runtime.gdapwritten byinstallAndroidPluginAarreferences it as alocal=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 directinvoke(...)andinvokeExact(...). 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 reflectiveMethodwith.invoke(: writef(args)or go through aMethodHandle(scripts/check_android_remap_sources.pyfails on both). The hot handles still becomestatic finalconstants 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.