# utopia-rise/godot-kotlin-jvm architecture

> Architecture diagram of the GitHub repository utopia-rise/godot-kotlin-jvm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/utopia-rise/godot-kotlin-jvm
- Repository: https://github.com/utopia-rise/godot-kotlin-jvm

## Overview

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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main External Node
    Godot["Godot Engine (Custom Build - Editor/Runtime)"]:::engine

    %% Native & JNI Layer Subgraph
    subgraph "Native & JNI Layer"
        NB["Native Binding Layer"]:::native
        BindingCode["Binding Code"]:::native
        JNIInfra["JNI Infrastructure"]:::native
        JVMWrapper["JVM Wrapper & Registration"]:::native
        EditorIntegration["Editor Integration"]:::native
        Lifecycle["Lifecycle & Bootstrapping"]:::native
    end

    %% Script Integration Layer Subgraph
    subgraph "Script Integration Layer"
        ScriptIntegration["Script Integration"]:::native
        LanguageSupport["Language Support"]:::native
    end

    %% Kotlin/Gradle Build & API Generation Subgraph
    subgraph "Kotlin/Gradle Build & API Generation"
        APIGen["API Generator"]:::kotlin
        EntryGen["Entry Generator"]:::kotlin
        KotlinLibs["Kotlin Runtime Libraries"]:::kotlin
        GradlePlugins["Gradle Plugins & Tools"]:::kotlin
    end

    %% Supporting Documentation & External Configuration Subgraph
    subgraph "Documentation & Configuration"
        DocsConfig["Documentation & Docs"]:::docs
        BuildConfig["Build & Config Files"]:::docs
    end

    %% Runtime Flow Connections
    Godot -->|"calls"| NB
    Godot -->|"calls"| ScriptIntegration
    NB -->|"contains"| BindingCode
    NB -->|"contains"| JNIInfra
    NB -->|"contains"| JVMWrapper
    NB -->|"integrates"| EditorIntegration
    NB -->|"manages"| Lifecycle
    ScriptIntegration -->|"worksWith"| LanguageSupport
    JNIInfra -->|"bridges(JNI)"| ScriptIntegration

    %% Build-Time Flow Connections (dashed)
    GradlePlugins -.->|"packages"| Godot
    APIGen -.->|"generates"| KotlinLibs
    EntryGen -.->|"generates"| KotlinLibs
    GradlePlugins -.->|"supports"| APIGen
    DocsConfig -.->|"configures"| NB
    DocsConfig -.->|"configures"| GradlePlugins
    DocsConfig -.->|"configures"| BuildConfig

    %% Click Events for Native Layer
    click BindingCode "https://github.com/utopia-rise/godot-kotlin-jvm/tree/master/src/binding"
    click JNIInfra "https://github.com/utopia-rise/godot-kotlin-jvm/tree/master/src/jni"
    click JVMWrapper "https://github.com/utopia-rise/godot-kotlin-jvm/tree/master/src/jvm_wrapper"
    click EditorIntegration "https://github.com/utopia-rise/godot-kotlin-jvm/tree/master/src/editor"
    click Lifecycle "https://github.com/utopia-rise/godot-kotlin-jvm/tree/master/src/lifecycle"

    %% Click Events for Script Integration Layer
    click ScriptIntegration "https://github.com/utopia-rise/godot-kotlin-jvm/tree/master/src/script"
    click LanguageSupport "https://github.com/utopia-rise/godot-kotlin-jvm/tree/master/src/language"

    %% Click Events for Kotlin/Gradle & API Generation
    click APIGen "https://github.com/utopia-rise/godot-kotlin-jvm/tree/master/kt/api-generator"
    click EntryGen "https://github.com/utopia-rise/godot-kotlin-jvm/tree/master/kt/entry-generation"
    click KotlinLibs "https://github.com/utopia-rise/godot-kotlin-jvm/tree/master/kt/godot-library"
    click GradlePlugins "https://github.com/utopia-rise/godot-kotlin-jvm/tree/master/kt/plugins"

    %% Click Events for Supporting Docs & Config
    click DocsConfig "https://github.com/utopia-rise/godot-kotlin-jvm/tree/master/docs"
    click BuildConfig "https://github.com/utopia-rise/godot-kotlin-jvm/blob/master/CMakeLists.txt"

    %% Styles
    classDef engine fill:#ffeb3b,stroke:#000,stroke-width:2px;
    classDef native fill:#90caf9,stroke:#01579b,stroke-width:2px;
    classDef kotlin fill:#a5d6a7,stroke:#1b5e20,stroke-width:2px;
    classDef docs fill:#eeeeee,stroke:#757575,stroke-width:2px;
```
