Kanama

Kotlin for Godot through a GDExtension runtime powered by the JVM and the Foreign Function & Memory API.

Kanama lets Kotlin scripts attach to Godot nodes through a GDExtension runtime. In the Godot editor, Kanama .kt files appear as script resources and can be attached directly to nodes like .gd scripts. Kanama aims to preserve the Godot workflow while giving game code access to Kotlin, Gradle, coroutines, and the JVM ecosystem.

Related Projects

Kanama is experimental and uses a Panama/FFM-based GDExtension architecture. If you want a more established Kotlin integration for Godot today, also evaluate Godot Kotlin/JVM. It is a separate project with a different runtime and export model.

Status

Kanama is experimental and desktop-first. The 0.2.1 preview baseline is Godot 4.7 beta 4. Use the Godot 4.7 beta 4 archive for compatible editor/player binaries and Android export templates. Desktop release kits are the packaging path for new projects; exported-game packaging remains a separate release-readiness track.

Android support is experimental for the v0.2.1 line: the current workflow builds a Godot Android plugin AAR, uses PanamaPort from Maven Central for the Android FFM layer, and has emulator/Pixel 7 smoke coverage for public demo APKs. Web export is not planned.

See Version Support for the current test matrix and the 0.2.1 public preview criteria.

Highlights

• Kotlin scripts attach to Godot nodes like GDScript
• No engine fork, no engine module, no JNI glue in game code
• Desktop runtime powered by the JDK Foreign Function & Memory API
• Experimental Android runtime through Godot's Android plugin AAR flow
• Hot reload and editor build tools for a fast iteration loop
• Growing Godot API wrapper surface with generated KDoc from Godot docs
• Desktop-first: macOS arm64 is the primary beta 4 validation path; Windows x64, Linux x64, and Linux ARM64 remain tracked smoke targets

Requirements

Desktop/editor workflow:

• Godot 4.7 beta 4 from the Godot 4.7 beta 4 archive
• JDK 25+ (Temurin 25 recommended)
• CMake 3.22.1+ and a platform C toolchain for source checkout workflows that build the desktop native bootstrap locally; release kits already include the platform bootstrap
• macOS arm64, Windows x64, Linux x64, or Linux ARM64 for the current editor/runtime smoke paths

Experimental Android export workflow:

• Godot 4.7 beta 4 Android export templates from the Godot 4.7 beta 4 archive
• Android SDK API 36, build-tools 36.1.0, and NDK 29.0.14206865 for Godot export
• CMake 3.22.1 for the Kanama Android plugin native bootstrap
• JDK 21 for Android Gradle/export tooling
• JDK 25 for normal Kanama desktop development

Quick Start

For a release kit, download the matching desktop zip from a Kanama GitHub release and build the starter Kotlin script. Use this path for a new project:

unzip kanama-desktop-kit-v<version>-<platform>.zip -d kanama-starter
cd kanama-starter
./gradlew buildScripts

Open kanama-starter/project.godot in Godot and press Play. After editing kotlin-src/HelloScript.kt, press Build Scripts in Godot or rerun ./gradlew buildScripts.

For an existing Godot project, download kanama-store-addon-v<version>.zip instead, unzip it at the project root, then initialize the project:

sh addons/kanama/setup-kanama-project.sh
./gradlew buildScripts

See Use a Store Addon for the Windows command and existing-Gradle-project notes.

For the source checkout workflow:

git clone https://github.com/falcon4ever/kanama
cd kanama
./gradlew createStarterProject \
  -PkanamaStarterProjectDir=/path/to/kanama-starter
./gradlew installAddonJar \
  -PkanamaProjectDir=/path/to/kanama-starter \
  -PkanamaProjectScriptsDir=/path/to/kanama-starter

Example

package com.example.game

import net.multigesture.kanama.annotations.OnReady
import net.multigesture.kanama.annotations.ScriptClass
import net.multigesture.kanama.api.GD
import net.multigesture.kanama.api.KanamaScript
import net.multigesture.kanama.api.Node
import java.lang.foreign.MemorySegment

@ScriptClass(attachTo = "Node")
class HelloKanama(godotObject: MemorySegment) :
    KanamaScript<Node>(godotObject, ::Node) {
    @OnReady
    fun ready() {
        GD.print("Hello from Kotlin")
    }
}

Documentation

The latest public documentation is published at falcon4ever.github.io/kanama.

• Getting Started
• Use a Release Kit
• Use a Store Addon
• Use a Source Checkout
• Work on Kanama
• The Editor Loop
• Writing Kotlin Scripts
• Calling Godot APIs
• Exports and Resources
• Signals and Callbacks
• Porting GDScript
• Kotlin Style
• Desktop and Packaging
• Android Experimental
• Version Support
• API Coverage
• C# Comparison
• Changelog
• Contributor Guide

To preview documentation changes locally:

pip install -r docs/requirements.txt
mkdocs serve

Demos

The companion demo repository is falcon4ever/kanama-demos. Keep it beside this checkout:

dev/
  kanama/
  kanama-demos/

Current demo ports cover starter kits, official Godot demos, and GDQuest 3D controller demos. The demo repo is also where new wrappers are validated against real gameplay before release.

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.