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 inKanamaScriptand are loaded fromkanama-scripts.jar.@RegisterClass: not reloadable. These classes are registered permanently in Godot's ClassDB and require an editor restart after changes.
Runtime Flow¶
./gradlew syncExampleAddonJarbuilds the checked-in example project, or./gradlew installAddonJar -PkanamaProjectDir=/path/to/project -PkanamaProjectScriptsDir=/path/to/projectbuilds an external project:kanama.jar: the Kanama runtime and any runtime-bundled registrars.kanama-scripts.jar: project.ktscripts plus generated project class and script registrars.- Godot loads
kanama.jarthroughbootstrap.c. KanamaBinding.initializeCallbackregisters the runtime:KanamaScriptKanamaScriptLanguage.ktresource loader/saver- optional permanent
KanamaRegistryentries from the runtime jar KanamaHotReload.initialize()loadskanama-scripts.jarthrough a child-first classloader.- On first load, the generated
KanamaClassRegistryregisters project@RegisterClassclasses with ClassDB. These classes are permanent for the Godot process. - The generated
KanamaScriptRegistryregisters only reloadable@ScriptClasstemplates. KanamaScriptLanguage.callFrame()periodically callsKanamaHotReload.frameTick(), which checks the script jar mtime and reloads changed templates. Each load sets theEnginemetadatakanama_scripts_jar_loaded_mtimeto the jar's time (a failed one setskanama_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:
- Build tag.
GodotSignal.connectArgstakes the user's callback asorigin(the typedSignal0…Signal5connections and theKanamaScriptmember forms pass the callback;awaitpasses null: its connection is closed when the script scope is cancelled at the free).SignalCallbackRegistryrecordsEntry.build, the defining class loader oforiginwhen it is aChildFirstClassLoader, else null (runtime code). A script lambda or::methodreference compiled withinvokedynamicis a hidden class of its host, so it reports the script jar's loader. iOS has no hot reload: itsconnectArgsignoresorigin. - Live count.
ScriptBridgecounts live script objects per build at one tracking site,noteScriptObject: fromtrackKotlinObject(a new instance) andScriptOwnerLinks.materialize(an owner link's rebuilt instance, which moves the owner to the current build).siFreeuncounts. 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. - Sweep.
KanamaHotReload.sweepRetiredConnections(), on the main thread, runs right afterAutoloadReload.recreateinreloadScripts, at the nextframeTickafter the flag is set, and before each retired-loader check (a backstop). For each retired build with no live script object it takesSignalCallbackRegistry.connectionsOf(build), unregisters each entry (its release hook does not run) and then disconnects it throughSignalCallables.disconnectwhile the emitter exists, and prints onepush_warningper 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. - Logs.
retired-loader-check collected=C alive=A alive_ids=… swept=Nreports 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¶
@RegisterClasshot reload is not supported because Godot ClassDB extension registrations are permanent for the process. Project@RegisterClasschanges 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.