Export for Desktop¶
An exported Kanama game carries its own trimmed Java runtime, so players install nothing. You export from Godot as usual, then one script adds the runtime and your compiled scripts to the export. The same steps work for Windows, macOS and Linux, from any of the three.
Requirements¶
- The project runs in the editor: Godot and a JDK 25 or newer, as in Get Started.
- Godot's export templates for the Godot version of your Kanama (Godot Version), installed from Editor > Manage Export Templates.
- A checkout of the Kanama repository, which builds the runtime and holds the assembly script. If you started from a release kit or the store addon, clone it once as in Cloning Kanama; you do not need to change your project.
- An export preset for your target in Project > Export. A macOS preset also needs the settings in macOS Entitlements and Signing.
Exporting a Game¶
These steps export for the machine you work on. To export for another platform, do step 1 here, then follow Exporting for Another Platform.
-
Build your scripts. Press Build Scripts in the editor, or run:
cd /path/to/your-project ./gradlew buildScripts -
Build the Java runtime in the Kanama checkout:
cd /path/to/kanama ./gradlew jlinkGameRuntimeThe runtime lands in
build/game-runtime/runtime. -
Export the game from Godot with Project > Export, or from the command line:
godot --headless --path /path/to/your-project \ --export-release "Windows Desktop" /path/to/export/MyGame.exeUse your preset's name in place of
"Windows Desktop". -
Add the runtime and your scripts to the export, from the Kanama checkout:
cd /path/to/kanama scripts/export_game_assemble.sh \ --kanama-jar /path/to/your-project/addons/kanama/kanama.jar \ --scripts-jar /path/to/your-project/addons/kanama/kanama-scripts.jar \ /path/to/exportThe last argument is the folder that holds the exported executable.
The export folder now holds everything the game needs:
| File | What it is |
|---|---|
The executable and .pck |
Godot's export, as usual. |
libkanama_bootstrap.so |
The Kanama native library. Godot's export copies it. |
kanama.jar |
The Kanama runtime. |
kanama-scripts.jar |
Your compiled scripts. |
runtime/ |
The Java runtime the game starts. |
kanama-jvm-options.txt |
Your JVM options, when the project sets any. |
Ship the whole folder as one zip.
Running the Exported Game¶
Run the exported executable from a terminal once. Kanama prints which Java runtime it loaded:
[kanama] using libjvm: /path/to/export/runtime/lib/server/libjvm.so
The path is inside the export folder when the bundled runtime is in place. If
it names a JDK installed on your machine instead, the export has no
runtime/ folder: run step 4 again.
Exporting for Another Platform¶
You can build the runtime for any desktop target from any desktop host.
jlinkGameRuntimeCross builds it for the target you name, and the assembly
script takes it with --runtime:
cd /path/to/kanama
./gradlew jlinkGameRuntimeCross -PkanamaRuntimeTarget=windows-x64
scripts/export_game_assemble.sh \
--runtime build/game-runtime/windows-x64/runtime \
--kanama-jar /path/to/your-project/addons/kanama/kanama.jar \
--scripts-jar /path/to/your-project/addons/kanama/kanama-scripts.jar \
/path/to/windows-export
The targets are windows-x64, linux-x64, linux-arm64 and macos-arm64.
The first build for a target downloads that platform's Java modules (about
80 MB). They are kept in ~/.gradle/kanama-target-jmods, so later builds skip
the download. Set -PkanamaTargetJmodsCacheDir or KANAMA_TARGET_JMODS_CACHE
to keep them somewhere else.
The assembly script refuses a runtime built for a different platform than the export, because that game would not start on a player's machine.
Adding Java Modules¶
The runtime holds the Java modules every Kanama game needs and nothing more.
If your scripts use another part of the JDK, such as java.net.http, add its
module when you build the runtime:
./gradlew jlinkGameRuntime -PkanamaRuntimeAdditionalModules=java.net.http
Separate several modules with commas. jlinkGameRuntimeCross takes the same
property.
Download Size¶
The bundled runtime adds roughly 30 to 40 MB to the download, depending on
the platform, and kanama.jar roughly 12 MB. Godot's own executable is
usually the largest file.
JVM Options¶
Kanama starts Java with its default heap and garbage collector settings. To pass your own options, such as a heap size or a GC log, set them in one of three places. A later one wins:
kanama-jvm-options.txtnext tokanama.jar. This is how an exported game carries them. The assembly script writes it from the project setting below, or from--jvm-options "...". Lines that start with#are comments.- The project setting
kanama/jvm/options, in Project > Project Settings > Kanama with Advanced Settings on, or asjvm/options="..."under[kanama]inproject.godot. It applies when you run the game from the editor. Restart the game after you change it. -
The
KANAMA_JVM_OPTIONSenvironment variable, for one run:KANAMA_JVM_OPTIONS="-Xmx512m -Xlog:gc" godot --path /path/to/your-project
Separate options with spaces. Quote a part that contains spaces with "..."
or '...', as in -Dgame.title="My Game". A word that does not start with -
is reported and skipped, and options after the 64th are dropped.
JAVA_TOOL_OPTIONS also works, with one exception: Java ignores
-XX:MaxNewSize and -XX:NewSize there. Put those in one of the three places
above; -Xmn works in all of them.
If frames are slow for a few seconds after your game creates many objects at
once, such as on a level load, add -XX:MaxNewSize=128m. It costs a little
frame time the rest of the time, so add it only when you see that slowdown.
macOS Entitlements and Signing¶
A macOS export is an .app bundle; pass the .app as the assembly script's
last argument. The assembly script puts Kanama's files in
Contents/Resources/, beside the .pck:
MyGame.app/Contents
├── Frameworks/libkanama_bootstrap.dylib # where Godot's export puts it
├── MacOS/MyGame # the exported Godot executable
├── Resources
│ ├── MyGame.pck
│ ├── kanama.jar
│ ├── kanama-scripts.jar
│ └── runtime/ # the bundled Java runtime
│ ├── bin/{java,keytool}
│ └── lib/server/libjvm.dylib
└── _CodeSignature/CodeResources
Resources/ is the one place where codesign accepts the jars and the
runtime. Adding files after Godot's export breaks the signature Godot wrote,
so the script signs the bundle again with an ad-hoc signature:
codesign --force --sign - --preserve-metadata=entitlements,flags,identifier MyGame.app
Entitlements¶
The macOS export preset needs Import ETC2 ASTC turned on in the project's VRAM compression settings, for any universal or arm64 export. It also needs three hardened-runtime entitlements in the preset's codesign section, because Java writes and runs its own machine code:
| Preset option | Entitlement in the signed app | Why Java needs it |
|---|---|---|
allow_jit_code_execution |
com.apple.security.cs.allow-jit |
Without it Java crashes before it starts. |
allow_unsigned_executable_memory |
com.apple.security.cs.allow-unsigned-executable-memory |
Java runs code it generated itself. |
disable_library_validation |
com.apple.security.cs.disable-library-validation |
The runtime's libraries are signed by the JDK vendor, not by your team. |
Check a build with codesign -dv --entitlements - MyGame.app. It should list
those three entitlements, and codesign --verify --deep --strict MyGame.app
should pass.
Signing for Distribution¶
The ad-hoc signature is fine for your own machine. A game downloaded from the internet meets Gatekeeper, which needs a Developer ID signature and Apple's notarization. Kanama does not sign or notarize for you. To do it yourself:
- Export, then assemble. The assembly step replaces any signature the export had, so sign last.
-
Sign every executable file inside
Contents/Resources/runtime/first: every.dylib, plusbin/java,bin/keytoolandlib/jspawnhelper. Signing the.appdoes not sign them.codesign --force --timestamp --options runtime \ --sign "Developer ID Application: Your Name (TEAMID)" <file> -
Sign the
.appitself last, the same way. Changing any file inside it afterwards breaks the signature again. - Zip the
.app, submit it withxcrun notarytool submit, then runxcrun stapler staple MyGame.app.
Once the runtime carries your own signature, you can drop
disable_library_validation.
Troubleshooting¶
| Problem | Fix |
|---|---|
| The exported game cannot find Java, or uses a JDK installed on your machine. | The export has no runtime/ folder. Run the assembly step on the folder that holds the executable, or on the .app. |
| macOS kills the game at launch. | A file changed after the last signature. Run the assembly step again, which re-signs, and sign for distribution only after it. |
macOS reports "libkanama_bootstrap.dylib" Not Opened. |
Gatekeeper quarantined a downloaded copy. On your own machine, run xattr -dr com.apple.quarantine /path/to/MyGame.app. For players, sign and notarize the game. |
| The assembly script refuses the runtime. | The runtime was built for a different platform than the export. Build it with jlinkGameRuntimeCross for the export's target. |
jlinkGameRuntimeCross fails on a version mismatch. |
The downloaded Java modules must have the same major version as the JDK running Gradle. Build with a JDK 25. |
The export stops with Kanama: Export stopped:. |
A scene uses a Kotlin script that does not load in the editor. Press Build Scripts and export again. See Export Guard. |
| The exported game runs old Kotlin code. | Build your scripts, then run the assembly step again. It copies kanama-scripts.jar at the time you run it. |
On Other Platforms¶
On Windows, run .\gradlew.bat wherever this page says ./gradlew, and
run export_game_assemble.sh from Git Bash. The native library is
kanama_bootstrap.dll, and the runtime line ends in
runtime\bin\server\jvm.dll. A Windows game needs no Visual C++
redistributable on the player's machine.
On macOS, the native library is libkanama_bootstrap.dylib, and the
files sit inside the .app as shown in
macOS Entitlements and Signing. The
runtime line ends in Contents/Resources/runtime/lib/server/libjvm.dylib.
Ship the .app as one zip.
What does not work on desktop is listed in Limitations.