Signals and Await¶
Every Godot signal is a typed Kotlin property, and your own signals are
declared with @Signal. You connect them to lambdas or to functions by name,
and you await them inside a coroutine, as in GDScript. The snippets sit
inside a script like the one in
Writing Scripts, which lists the imports.
Engine Signals¶
func _ready():
area.body_entered.connect(func(body): body.hide())
timer.timeout.connect(_on_timeout, CONNECT_ONE_SHOT)
await timer.timeout
var body = await area.body_entered
private val area by node<Area3D>("Area")
private val timer by node<Timer>("Timer")
@OnReady
fun ready() {
area.bodyEntered.connect { body -> body.hide() } // body is a Node3D
timer.timeout.connect(GodotObject.ConnectFlags.ONE_SHOT) { onTimeout() }
launch {
timer.timeout.await()
val body = area.bodyEntered.await()
GD.print("entered: ", body.name)
}
}
private fun onTimeout() {
GD.print("time is up")
}
Each signal's type comes from Godot's API: area.bodyEntered is a
Signal1<Node3D>, so body is a Node3D.
connect { }binds the lambda to your script's node, as a GDScript lambda is bound to its script. Godot drops the connection, and Kanama releases the lambda, when that node or the emitter is freed, or after one call withConnectFlags.ONE_SHOT.ConnectFlags.DEFERREDandor-combinations work as in Godot. Outside a script, pass the owner yourself:area.bodyEntered.connect(owner) { body -> }.connectreturns aSignalConnection.close()it to disconnect early, or scope it withuse { }.await()suspends insidelaunch { }. A one-argument signal returns the value. A signal with two to five arguments returns them to destructure:val (id, data) = signal.await(), where GDScript returns anArray. If the emitter is freed first, or your script's node is, the wait is cancelled.emit(...)takes typed arguments:button.pressed.emit().connect(target, "method_name")connects a function by name, as a scene connection does. See Connecting by Name.
Signal Arguments¶
private var lastEvent: InputEvent? = null
@OnReady
fun ready() {
val control = self.requireAs<Control>("Panel")
control.guiInput.connect { event -> lastEvent = event } // safe to keep
}
Arguments follow Godot's API: an int is Long, a float is Double,
String and StringName are String, an object is its class, and a
Variant is Any?. Godot does not mark engine signal arguments as enums, so
an engine signal hands you an enum as a Long; wrap it with
Node.ProcessMode(value) when you want the type. An object argument is
non-null unless Godot can emit null for it, such as the body of
Area3D.bodyShapeEntered when the body has no node.
You can keep any argument, as in GDScript. A Resource or InputEvent
argument is a reference of your own: close() it when you are done, or the
garbage collector releases it later (see
Resource Ownership). A Node argument is the
node itself: it is == to your own reference to it, and it stays usable until
the node is freed.
A value of the wrong type, from a GDScript emit_signal for example, is
reported as a script error that names the signal, and the lambda is not
called.
Custom Signals¶
import net.multigesture.kanama.generated.coinCollected
@ScriptClass(attachTo = "Area2D")
class Coin(godotObject: GodotHandle) : KanamaScript<Area2D>(godotObject, ::Area2D) {
@Signal
fun coinCollected(value: Long) = Unit
fun collect() {
coinCollected.emit(10L)
}
}
signal coin_collected(value)
coin_collected.emit(10)
A @Signal function declares the signal; Godot sees it as coin_collected,
so saved scene connections to it keep working. The build generates a typed
handle with the same name, which you emit, connect and await like an engine
signal. Calling the @Signal function itself does nothing: emit with
coinCollected.emit(...). A property named like the handle would hide it, so
the build rejects one.
From another script, use the handle on the script object:
import net.multigesture.kanama.generated.coinCollected
private var score = 0L
private val coin by script<Coin>("Coin")
@OnReady
fun ready() {
coin.coinCollected.connect { value -> score += value }
}
When you hold the emitter as a Godot object rather than as its script, such as
an autoload node or a node you looked up, the generated CoinSignals object
gives the same handle: CoinSignals.coinCollected(node).connect { value -> }.
A Godot enum works as a signal argument (@Signal fun modeChanged(mode:
Node.ProcessMode) = Unit). GDScript receives the int, and the typed handle
hands Kotlin the Node.ProcessMode.
A signal with more than five arguments, or with an argument that has no typed
form such as a packed array, has no typed handle. Connect it by name, or with
the CoinSignals.connectCoinCollected(...) and awaitCoinCollected(...)
functions the build generates for every signal.
Connecting by Name¶
import net.multigesture.kanama.generated.PlayerNames
@OnReady
fun ready() {
val area = self.requireAs<Area3D>("Area")
area.bodyEntered.connect(self, PlayerNames.Methods.onBodyEntered)
}
fun onBodyEntered(body: Node3D) {
body.hide()
}
Every public function of a script can be a signal target under its
snake_case name, here on_body_entered. The build generates a PlayerNames
object for each script, with Methods, Properties and Signals constants,
so you never spell the name by hand. The target function may take the
argument as its class (Node3D) instead of GodotObject. Engine classes have
Signals constants too, such as Area3D.Signals.bodyEntered.
Signals Known Only by Name¶
import net.multigesture.kanama.generated.Autoloads
@OnReady
fun ready() {
val events = Autoloads.Events // a GDScript autoload
val bar = self.requireAs<ProgressBar>("Hud/Health")
val healthChanged = Signal1(events, "health_changed", SignalArgType.LONG)
healthChanged.connect { hp -> bar.value = hp.toDouble() }
}
A signal a GDScript declares, or one Godot adds at runtime, gets a typed handle
the same way: name its argument types and use it like any other. For a signal
whose arguments you do not know, events.signal("health_changed") is the
untyped handle. Its connect(target, argumentCount) { args -> } receives the
arguments as a List<Any?>, and await(target, argumentCount) returns them;
connectObject and awaitObject are the shortcuts for one object argument.
These connections have the same lifetime as the typed ones.
Scene Connections¶
A scene can store a signal connection, and the .tscn file saves the target
function's name. A scene made with GDScript usually connects to a name such as
_on_body_entered, so give the Kotlin function that exact name:
@GodotName("_on_body_entered")
fun onBodyEntered(body: Node3D) {
body.hide()
}
Without @GodotName, the function is on_body_entered, and the saved
connection does not find it. To check every saved connection of a project
against your scripts, run this from a Kanama checkout:
python3 /path/to/kanama/scripts/scene_connection_lint.py /path/to/your-project
It reads each .tscn connection, finds the Kotlin script on the target node,
and reports a connection whose function the script does not have.
Signals on Instanced Scenes¶
The GDScript for Squash the Creeps connects each new mob to the score label:
mob.squashed.connect($UserInterface/ScoreLabel._on_mob_squashed)
In Kotlin, with both sides Kotlin scripts, connect the typed handle to a lambda that calls the label's function:
import net.multigesture.kanama.generated.squashed
@ScriptClass(attachTo = "CharacterBody3D")
class Mob(godotObject: GodotHandle) : KanamaScript<CharacterBody3D>(godotObject, ::CharacterBody3D) {
@Signal
fun squashed() = Unit
}
@ScriptClass(attachTo = "Label")
class ScoreLabel(godotObject: GodotHandle) : KanamaScript<Label>(godotObject, ::Label) {
private var score = 0L
internal fun onMobSquashed() {
score += 1
self.text = "Score: $score"
}
}
@ScriptClass(attachTo = "Node")
class Main(godotObject: GodotHandle) : KanamaScript<Node>(godotObject, ::Node) {
@Export
var mobScene: PackedScene? = null
private val scoreLabel by script<ScoreLabel>("UserInterface/ScoreLabel")
fun spawnMob() {
val mob = mobScene?.instantiateScript<Mob>() ?: return
mob.squashed.connect { scoreLabel.onMobSquashed() }
self.addChild(mob.self)
}
}
instantiateScript<Mob>() returns the Kotlin script on the new scene's root,
so you call its members directly. onMobSquashed is internal because only
Kotlin calls it. The lambda belongs to Main, and the
connection ends when Main or the mob is freed. When the receiver is a
GDScript, connect by name instead:
mob.squashed.connect(label, "_on_mob_squashed").
Hot Reload¶
Hot reload runs on desktop only. It loads the new build of your scripts while the old build's objects keep running until they are freed. The scene reload frees the scene's objects, and Kotlin autoloads are reset in place. A lambda connection belongs to the build that made it. Once the old build's last script object is gone, its lambda connections are disconnected on the next frame, even when the target is still alive, and Kanama prints one warning:
hot-reload: dropped 2 lambda connection(s) of build 1 whose script objects are gone (SceneTree.process_frame x1, Hud.score_changed x1); the new build's _ready connects again
So make lambda connections in @OnReady or later, and do not expect one to
outlive a hot reload: the new objects' @OnReady connects again, running the
new code. While some of the old build's objects are still alive, such as those
of a scene you did not reload, their connections stay and run the old code.
| Connection | GDScript after a reload | Kanama after a hot reload |
|---|---|---|
by name: connect(target, "on_hit"), a scene connection |
survives and calls the new function | survives and calls the new function once the target has the new build's object; a node of a scene you did not reload keeps the old one |
| a lambda | moves to the new code when the lambda is still in the source; otherwise it is skipped silently | dropped with its build, with one warning; @OnReady connects the new one |
A Kotlin function reference (::onHit) is dropped with its build like a
lambda. C# re-binds such a reference by object and method name after a
reload; Kanama does not, so connect by name when a connection must survive a
hot reload.
On Other Platforms¶
Signals, connections and await work the same on desktop, Android, iOS and
Web, with a few gaps: iOS does not deliver signal arguments of some container
types, and Web has no typed handle for two engine signals. Hot reload is
desktop only. Limitations lists each case with
its workaround.