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 a preview-stage (0.4.0) project using 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 desktop-first. The badges above are the current platform tiers; Version Support is the one page that records what each tier was validated on, when, and with which caveats, and it is the only page that states requirements. Exported desktop games are unpack-and-play: they ship a bundled, jlink-trimmed JVM runtime, and that runtime is cross-target, so one host can produce Windows, Linux, and macOS builds — see Desktop and Packaging.

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
• Android runtime through Godot's Android plugin AAR flow (ART + PanamaPort)
• iOS runtime through a Kotlin/Native .xcframework, no on-device JVM
• Kotlin/Wasm Web backend through a generated proxy and a versioned JavaScript bridge, no on-device JVM
• Desktop script reload and editor build tools: Build Scripts rebuilds the Kotlin jar and rebinds attached scripts without restarting Godot (reloading the scene is the reliable path; @RegisterClass types need an editor restart; no reload on mobile or Web, see The Editor Loop)
• Every Godot 4.7 class has a Kotlin wrapper (1036/1036, generated KDoc from Godot docs; engine virtuals overridable via @OverrideVirtual). The builtin value types (Vector3, Transform3D, Color, ...) are thinner than GDScript's: only a subset of Godot's builtin methods and operators exist; see API Coverage

Requirements

The Godot pin and JDK are the badges above. The full list — per workflow, and per export platform — lives once, in Version Support → Requirements.

Quick Start

Use a source checkout for the current public onboarding path:

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

Open kanama-starter/project.godot in Godot and press Play. The starter script is kanama-starter/HelloScript.kt (at the project root). After editing it, press Build Scripts in Godot, or rerun the installAddonJar command above from the Kanama checkout. The starter project has no Gradle wrapper of its own, so ./gradlew buildScripts does not exist there; Build Scripts finds the checkout when it is a sibling folder named kanama (otherwise set the kanama/tools/repo_dir project setting, see The Editor Loop).

Package tasks can also build local desktop kit and store-addon zips for smoke testing:

./gradlew packageDistributions

If a matching GitHub zip release exists, a release kit can be used for a new project:

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

For an existing Godot project and a locally built or published store-addon zip, unzip it at the project root, then initialize the project:

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

The release-kit and store-addon pages describe those generated zip shapes; they become download flows once matching release artifacts are published.

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.GodotHandle
import net.multigesture.kanama.api.KanamaScript
import net.multigesture.kanama.api.Node

@ScriptClass(attachTo = "Node")
class HelloKanama(godotObject: GodotHandle) :
    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
• iOS
• 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.