godot-kotlin-jvm

Godot callbacks (e.g., _ready, _process, _physicsProcess) are handled differently than ordinary functions.

When a function overrides a Godot method, simply use the override keyword. Do not use @Register on these methods; Godot recognizes compatible overrides automatically in the default Inferred mode.

override fun _process(delta: Double) {
    // Update this node each frame.
}

The godot-bootstrap is a shadow JAR (fat JAR) that includes godot-library and the runtime code required to reload user code within the Godot editor after a rebuild.

Usage:

• It is shipped alongside the Godot engine for editor use.
• It is bundled with the game executable during the export process.
• Note: You should never add this as a dependency or use it directly.

Notification handlers are treated differently than regular Godot methods:

• Storage: They are stored as regular functions with specific notification metadata.
• Selection: They are identified by RegisteredFunction.notification.
• Generation: They are generated using repeated notification(id, Class::method) calls.
• Visibility: They are not exposed as regular callable Godot methods.
• Deduplication: They are not deduplicated by notification ID; multiple methods can handle the same notification.

Lifecycle and Dispatch: Notification handlers are collected through the hierarchy and registered in child-to-parent order (matching runtime storage order).

• Parent-to-child calls: Godot walks the list in reverse.
• Child-to-parent calls: Godot walks the list forward.

Godot enums are mapped to JVM enums. The generated enum includes a .value property representing the underlying Godot value.

Important: Do not use Godot class constants that represent enum values (e.g., Node.PAUSE_MODE_INHERIT). Instead, use the generated enum type (e.g., Node.PauseMode.INHERIT).

The registrar generation process is designed to be language-agnostic. It relies on a two-step process:

1. Information Gathering: A tool gathers source code information and converts it into a set of model classes that the registrar generator understands. For JVM languages (Kotlin, Java, and Scala), this tool is godot-class-graph-symbol-processor.
2. File Generation: The godot-class-graph-symbol-processor analyzes bytecode using ClassGraph (a bytecode processor) to collect the necessary data, then calls the registrar generator to produce the required registrar files.

By using ClassGraph instead of a direct compiler plugin (like KSP or MpApt), the system works against a more stable bytecode API, making it easier to support additional JVM languages.

Most Godot built-in types (like Vector3, Transform3D, etc.) are passed by value. This means modifying a property returned by a getter actually modifies a temporary copy, not the object itself.

The Problem:

node3D.rotation.y += 10f // This modifies a copy; the actual node rotation remains unchanged

The Solution (Standard): You must retrieve the object, mutate it, and then re-assign it back to the property.

val rotation = node3D.rotation
rotation.y += 10f
node3D.rotation = rotation

The Solution (Kotlin-only optimization): Use the rotationMutate extension for a concise syntax:

node3D.rotationMutate {
  y += 10f
}

// Kotlin concise mutation
node3D.rotationMutate {
  y += 10f
}

You can create new instances of Godot types using standard JVM instantiation. Godot singletons are exposed as static access points in their respective language.

// Instantiation
val node3D = Node3D()
val vec = Vector3()

// Singleton access
Physics2DServer.areaGetTransform(area)

When exposing a callable as a registered property in a Java or Scala class, you should use the base Callable type for the property signature rather than the typed CallableN variants.

Even though the property surface seen by the registration layer uses Callable, the actual instance stored can be a typed LambdaCallableN or MethodCallableN to preserve type safety at runtime.