Skip to content

Hot Reload Internals

This document describes the current @ScriptClass reload path.

Scope

Kanama supports reload for attachable script classes:

  • @ScriptClass: reloadable. These classes register script templates in KanamaScript and are loaded from kanama-scripts.jar.
  • @RegisterClass: not reloadable. These classes are registered permanently in Godot's ClassDB and require an editor restart after changes.

Runtime Flow

  1. ./gradlew syncExampleAddonJar builds the checked-in example project, or ./gradlew installAddonJar -PkanamaProjectDir=/path/to/project -PkanamaProjectScriptsDir=/path/to/project builds an external project:
  2. kanama.jar: the Kanama runtime and any runtime-bundled registrars.
  3. kanama-scripts.jar: project .kt scripts plus generated project class and script registrars.
  4. Godot loads kanama.jar through bootstrap.c.
  5. KanamaBinding.initializeCallback registers the runtime:
  6. KanamaScript
  7. KanamaScriptLanguage
  8. .kt resource loader/saver
  9. optional permanent KanamaRegistry entries from the runtime jar
  10. KanamaHotReload.initialize() loads kanama-scripts.jar through a child-first classloader.
  11. On first load, the generated KanamaClassRegistry registers project @RegisterClass classes with ClassDB. These classes are permanent for the Godot process.
  12. The generated KanamaScriptRegistry registers only reloadable @ScriptClass templates.
  13. KanamaScriptLanguage.callFrame() periodically calls KanamaHotReload.frameTick(), which checks the script jar mtime and reloads changed templates. Each load sets the Engine metadata kanama_scripts_jar_loaded_mtime to the jar's time (a failed one sets kanama_scripts_jar_failed_mtime), and the Kanama Tools plugin reloads the open scenes after a build only once one of them matches the new jar, so no scene is rebuilt on the old build's code.

Connections Across A Reload

A lambda signal connection is owned by the build (the script jar's class loader generation) that made it. Godot keys a connection's custom Callable to its receiver and emitter only, so without a build key a lambda whose receiver outlives its maker (the SceneTree, a GDScript autoload, a kept node) keeps running the old build's code and pins the retired loader. The pieces:

  1. Build tag. GodotSignal.connectArgs takes the user's callback as origin (the typed Signal0…Signal5 connections and the KanamaScript member forms pass the callback; await passes null: its connection is closed when the script scope is cancelled at the free). SignalCallbackRegistry records Entry.build, the defining class loader of origin when it is a ChildFirstClassLoader, else null (runtime code). A script lambda or ::method reference compiled with invokedynamic is a hidden class of its host, so it reports the script jar's loader. iOS has no hot reload: its connectArgs ignores origin.
  2. Live count. ScriptBridge counts live script objects per build at one tracking site, noteScriptObject: from trackKotlinObject (a new instance) and ScriptOwnerLinks.materialize (an owner link's rebuilt instance, which moves the owner to the current build). siFree uncounts. When a retired (closed) build's count reaches 0, KanamaHotReload.requestSweep() sets a flag; the free itself may run inside an emission, so nothing is disconnected there.
  3. Sweep. KanamaHotReload.sweepRetiredConnections(), on the main thread, runs right after AutoloadReload.recreate in reloadScripts, at the next frameTick after the flag is set, and before each retired-loader check (a backstop). For each retired build with no live script object it takes SignalCallbackRegistry.connectionsOf(build), unregisters each entry (its release hook does not run) and then disconnects it through SignalCallables.disconnect while the emitter exists, and prints one push_warning per sweep: hot-reload: dropped N lambda connection(s) of build B whose script objects are gone (Emitter.signal xN, ...); the new build's _ready connects again. The emitter is named by its node name (an autoload reads as its global) or its class. A build that still has live objects keeps its connections.
  4. Logs. retired-loader-check collected=C alive=A alive_ids=… swept=N reports the connections the sweeps dropped since the previous check; with nothing left to pin it, the retired loader is collected (alive=0). The line is printed when something changed (a collection, a sweep, a different set of live loaders), not every second. The check forces garbage collections only while some retired build has no live script object left: a build whose objects are still alive (a running game whose scene was not reloaded) cannot be collected, and forcing collections for it stalled the main thread once a second.

AutoloadReload still disconnects the lambdas bound to a reset autoload node at once (receiver-keyed); the build sweep covers every other target. An emission in the same frame as the build's last free still reaches the old lambda: the sweep runs on the next frame tick.

Autoloads Across A Reload

A desktop hot reload resets each Kotlin autoload in place, so the autoload stays the same node: Autoloads.<Name>, GDScript's global name and any reference other code holds keep working.

Survives the reload Does not survive
the node itself: its identity, name, place under /root and GDScript global the old script object: each Kotlin node of the autoload gets a new one, from the new build
an exported property whose type did not change: its value is set back an exported property whose type changed: it takes the new default, or the autoload scene's value
the nodes of the autoload's scene (.tscn children) children created at run time, in _ready or later: they are freed
connections other objects made to the autoload lambda connections the autoload made (signal.connect(self) { ... }): they are disconnected
any other lambda connection of the old build: dropped once the old build's last script object is gone, with one warning
every other Kotlin field: it starts from its initializer

Then _ready runs again on the reset nodes, children before parents as Godot readies a tree, so whatever _ready sets up exists once, from the new code. This is a scene reload for the autoload, minus the new node. Hot reload runs in the editor process too (Build Scripts while the editor is open), so a @Tool autoload in the editor's tree is reset the same way. The editor adds an autoload to its own tree only when the autoload's script is a tool script (@Tool), as Godot does for GDScript; reading any other autoload from editor code throws there.

Editor Workflow

The optional res://addons/kanama_tools plugin provides Build Scripts, debounced build-on-save, scene reload after sync, and JDWP settings. See Edit, Build, Run for the daily workflow.

After a sync, existing KanamaScript resources are rebound to the newest template. Scene reload is still recommended for reliable live-node replacement.

For breakpoint debugging, enable kanama/debug/jdwp_enabled. Kanama tools registers kanama/debug/jdwp_port with the conventional runtime/game default 5005. Restart the game process after changing either setting. Kanama reads these settings before starting the embedded JVM and enables JDWP at localhost:PORT for runtime/game processes (skipped, with a log line, when another Kanama process holds the port's lock, or on macOS and Linux when something else listens on it); attach IntelliJ with a Remote JVM Debug configuration pointed at localhost:PORT. Editor processes skip the runtime port so pressing Play does not create a port conflict.

Edit Loop Timing

Measured on a fresh starter: save HelloScript.kt with a changed print line, then time until the change shows.

From saving a .kt file until Median p90
./gradlew buildScripts has finished (build only) 2.0 s 2.1 s
a newly started game prints the new line (build, then Play again) 2.4 s 2.5 s
the editor shows it: build on save, then the scene reloads 3.7 s 3.8 s
a running game has loaded the new build 2.6 s 2.9 s

Five runs each after one warm-up run, with the Gradle daemon running (the first build after starting it took 4.3 s). Machine: Apple M1 Max, 64 GB, macOS 26.6, Godot 4.7.2, JDK 25, headless editor and game; measured 2026-10-18.

About 1.5 s of the editor number is build on save waiting for you to stop saving: it scans for changed files every 0.6 s and builds once kanama/tools/auto_build_debounce_ms (800 ms) has passed without another change. A running game checks for a new build every 0.5 s, but the nodes it already has keep running their old code until their scene reloads; new instances and Kotlin autoloads use the new code at once. For a change you want to see in the game, restarting it is the fastest path.

The budget is a median of 5 s or less from save to the change showing in the editor. To measure your own machine, run this from the root of your Kanama checkout:

python3 scripts/measure_edit_loop.py /path/to/godot --runs 5

It creates a fresh starter from the checkout, runs the four measurements, and prints the median, the p90 and a budget line. The budget line is a report: the script fails only when it cannot take a measurement.

Verification

Use:

./scripts/hot_reload_smoke.sh /absolute/path/to/godot_binary
./scripts/runtime_smoke.sh /absolute/path/to/godot_binary

runtime_smoke.sh is the main headless runtime smoke. It verifies that Godot loads Kanama, registers the script language and resource loader, and runs the example project far enough to observe expected markers.

hot_reload_smoke.sh edits example_project/HelloScript.kt, rebuilds the script jar, and verifies the changed marker appears in a new headless editor run.

hot_reload_in_process_smoke.sh keeps one headless Godot process alive, edits and rebuilds kanama-scripts.jar, waits for the runtime hot-reload loop to rebind scripts, reloads the current scene, and verifies the updated script marker without restarting Godot. It also checks retired script classloaders via weak references and asserts that the old loader is collected after the old script instance is freed. A lambda HelloScript connects to the GDScript autoload (a target that survives the reload) must run once per build, never for build A after the reload, with the hot-reload: dropped 1 lambda connection(s) warning.

Current Behavior

  • @RegisterClass hot reload is not supported because Godot ClassDB extension registrations are permanent for the process. Project @RegisterClass changes require an editor/game restart.
  • Live in-place replacement of already-instanced nodes is partial; scene reload remains the reliable editor workflow.
  • The child-first package list is fixed in KanamaHotReload.
  • A lambda connection dies with the build that made it: once the old build's last script object is gone, its lambda connections are disconnected with one warning, whatever their target. Make connections in _ready; by-name connections are Godot's and survive, as in GDScript.