How utopia-rise/godot-kotlin-jvm works
This project is a language binding for the Godot game engine that lets you write game logic in Kotlin for a Godot-based game. The overall purpose is to provide a complete Kotlin/JVM binding to Godot so that developers can package their game logic as either a JAR with an embedded JVM or as a native dynamic library generated with GraalVM. The project itself is somewhat “full-stack” in the sense that it contains both the low-level native bindings (written in C++ using JNI) and high-level Kotlin tools that generate API wrappers, compiler integration (via Gradle plugins), extension libraries, and editor support.
Major Components
• Native Binding Layer – This exists in the “src” directory and is composed of several submodules:
– Binding code (e.g., src/binding) that exposes C++ functions.
– JNI infrastructure (the “src/jni” folder) that handles JNI environment, JVM startup, local frame management, method lookups, and conversion between Godot’s types and the JVM.
– JVM Wrapper code (in “src/jvm_wrapper”) which includes:
• The bootstrap code, registration bridges (e.g., callable_bridge, dictionary_bridge, variant bridges, etc.),
• Memory management components (e.g., transfer_context, memory_manager),
• Registration of Kotlin classes, methods, properties, and signals.
• Editor Integration Layer – Shown by files in “src/editor” where the Godot editor’s integration for this module is implemented. It has build management, export dialog components, and project generator code.
• Scripting Layer – The “src/script” folder that provides the runtime integration for Godot’s scripting system. This includes support for jvm_instance, jvm_script, and language-specific implementations (like in “src/language” where GDJ, Java and Kotlin scripts reside).
• Lifecycle and Bootstrapping – Code in “src/lifecycle” for managing the class loader, JVM managers, and user configuration. This layer ensures the JVM is started with the required options and does the initial native-to-JVM binding.
• Kotlin/Gradle and API Generation Infrastructure – This is represented by the “kt” directory and its subdirectories:
– API Generator (“kt/api-generator”) which parses Godot’s API (and metadata) to create Kotlin classes that mirror Godot’s types.
– Entry Generation (“kt/entry-generation”) for generating the code needed to register bindings.
– Kotlin Library Components (“kt/godot-library”, “kt/godot-core-library”, and other subprojects) that expose high-level APIs and runtime support.
– Gradle Plugins (“kt/plugins”) that offer integration with builds, configuring projects to use the Kotlin binding, setting up tasks for packaging, GraalVM native image support, and iOS/Android build tasks.
– Additional Tools (like “kt/tools-common”, “kt/utils”) that provide completions, build properties, and common utilities.
• Supporting Documentation and External Configuration – Directories like “docs” and configuration files (CMakeLists.txt, gradle files, .clang-format, etc.) which support project tooling and developer setup.
Relationships and Data Flow
• The Godot Game Engine (custom build) embeds the Kotlin/JVM module. At runtime the engine calls into native binding code (via C++).
• The native binding layer uses JNI to connect with the JVM, which then loads the Kotlin classes produced by the generator.
• The JVM Wrapper registers “bridges” that allow Godot’s engine events (signals, properties, etc.) to be forwarded to Kotlin methods.
• The Gradle plugins and API generator are part of the build-time processes, ensuring that the Godot API is correctly mapped to Kotlin classes. This build output is then combined into either a JAR file or used to generate a native dynamic library via GraalVM.
• Editor integration components provide dialogs and interfaces in the Godot editor for project builds, export, and debugging.
Architectural Patterns and Important Design Principles
• Layered Architecture: The project is separated into a native (C++) layer for binding and a high-level Kotlin layer. Communication between them is handled via JNI.
• Modularization: The architecture is highly modularized, with components for API generation, build plugins, runtime libraries, and editor integrations.
• Bridging and Registration: A crucial pattern is the use of "bridge" code in the JVM Wrapper to convert native Godot types into Kotlin types and vice versa.
• Build-time Code Generation: The project leverages code generators in Kotlin (entry-generator, API generator) to automate the creation of binding code.