Kotlin Style¶
These are the conventions Kanama's templates and demos follow. They keep scripts easy to read for anyone who knows Godot, and a few of them avoid real bugs. The snippets sit inside a script like the one in Writing Scripts, which lists the imports.
Packages¶
package com.mygame.scripts
Every script file declares a package, a reversed domain or a short project
name. A script without one cannot be used from other scripts, and a
@GlobalClass in it does not register.
Imports¶
import net.multigesture.kanama.annotations.OnReady
import net.multigesture.kanama.annotations.ScriptClass
import net.multigesture.kanama.api.Label
import net.multigesture.kanama.api.Node2D
import net.multigesture.kanama.types.*
The templates import annotations and Godot classes by name, which your IDE
does as you complete a name, and the value types with
net.multigesture.kanama.types.*. That wildcard also brings the operators
written as extensions, such as 2.0 * v. A wildcard
net.multigesture.kanama.api.*, as in Writing Scripts,
works as well.
Script Class Structure¶
@ScriptClass(attachTo = "CharacterBody3D")
@GlobalClass
class Player(godotObject: GodotHandle) :
KanamaScript<CharacterBody3D>(godotObject, ::CharacterBody3D) {
// 1. Exports
@ExportGroup("Movement")
@Export var speed: Double = 5.0
@Export var jumpVelocity: Double = 4.5
// 2. Cached views and node lookups
private val node3d = selfAs(::Node3D)
private val camera by node<Camera3D>("Camera")
// 3. Other state
private var isJumping = false
// 4. Lifecycle callbacks, roughly in the order Godot calls them
@OnReady
fun ready() { /* ... */ }
@OnPhysicsProcess
fun physicsProcess(delta: Double) { /* ... */ }
// 5. Public functions, which Godot can call
fun takeDamage(amount: Long) { /* ... */ }
// 6. Private functions
private fun applyGravity(delta: Double) { /* ... */ }
}
Declare a script's members in this order. Class annotations go top-down:
@ScriptClass, then @GlobalClass, then @Tool.
Naming¶
| Thing | Convention | Example |
|---|---|---|
| Class | PascalCase |
PlayerController |
| Function | camelCase |
physicsProcess |
| Property | camelCase |
jumpVelocity |
| Constant | UPPER_SNAKE_CASE |
MAX_SPEED |
| Package | lowercase.dotted |
com.mygame.scripts |
Lifecycle functions drop GDScript's leading underscore: fun ready(), not
fun _ready(). The annotation is what Godot looks for, not the name.
Name the constructor parameter godotObject, as the templates and the
Attach Script dialog do:
class Player(godotObject: GodotHandle) :
KanamaScript<CharacterBody3D>(godotObject, ::CharacterBody3D)
self and selfAs Caching¶
private val node3d = selfAs(::Node3D) // made once, with the script
@OnProcess
fun process(delta: Double) {
node3d.translate(Vector3(0.0, 0.0, delta))
}
self is the node as the class in KanamaScript<T>. Keep a second view from
selfAs in a property, not in a per-frame function: each call makes a new
wrapper, which is cheap but adds up every frame.
Exports and Properties¶
@ExportGroup("Combat")
@Export var damage: Double = 10.0
@Export var range: Double = 3.0
@ExportGroup annotates the first property of its group, on the line above
it; the properties after it join the group until the next one. GDScript's
@export_group line on its own has no Kotlin form, because a Kotlin
annotation needs a property to sit on.
Null Safety and Tool Scripts¶
@Export var label: Label? = null
private var score = 0L
@OnProcess
fun process(delta: Double) {
label?.text = score.toString()
}
An exported node or resource is nullable, and in a @Tool script it can still
be null while the editor runs your code. Use ?. instead of !! in
lifecycle functions: a !! on an unassigned export crashes the editor.
Decimals¶
@Export var gravity: Double = 980.0
@OnPhysicsProcess
fun physicsProcess(delta: Double) {
self.velocity = self.velocity.withY(self.velocity.y + gravity * delta)
}
- Write decimals as
Doubleliterals:Vector3(0.0, 1.0, 0.0),Color(1.0, 0.5, 0.0), with nofsuffix and no.toFloat()between components,deltaand other arguments. - Change one component with
withX(),withY()orwithZ(). - Compare decimals with
isEqualApprox, as in GDScript. Components are stored as 32-bit floats, soVector2(0.1, 0.2).x == 0.1isfalse.
Signals and Registered Functions¶
@GodotName("_on_body_entered")
fun onBodyEntered(body: Node3D) { /* ... */ }
private fun recalculate() { /* ... */ }
Every public function is visible to Godot, so make the functions Godot never
calls private, or internal when another script calls them. Use
@GodotName only to match a name a scene already saved. Prefer the generated
typed signal handles and Names constants to strings. See
Signals and Await.
Coroutines¶
@ScriptClass(attachTo = "Node2D")
class Door(godotObject: GodotHandle) : KanamaScript<Node2D>(godotObject, ::Node2D) {
fun openBriefly() {
launch {
self.show()
wait(0.4)
self.hide()
}
}
}
Every script has its own coroutine scope. Start a coroutine with launch { }
and suspend in it with wait(seconds), nextFrame() or a signal's await(),
the way a GDScript function uses await. Kanama cancels the scope when the
script's node is freed, so a coroutine never touches a freed node. Leaving the
tree does not stop it, as in GDScript; call cancelCoroutines(), in
@OnExitTree for example, when it should.
Use launch for work that belongs to the scene: gameplay loops, delayed
effects, warmup, polling, animation and cleanup. Keep the returned Job when a
later event should cancel one piece of work:
import kotlinx.coroutines.Job
private var warmupJob: Job? = null
fun startWarmup() {
warmupJob = launch {
nextFrame()
warmUp()
}
}
fun cancelWarmup() {
warmupJob?.cancel()
warmupJob = null
}
private fun warmUp() { /* load what the next scene needs */ }
scriptScope is the scope itself, for other kotlinx.coroutines builders such
as scriptScope.async { }.
Work that must outlive the node goes to MainThread instead. After unloading
the current scene, for example, the scene's scope is about to be cancelled:
fun quitToDesktop() {
val tree = self.tree
tree.unloadCurrentScene()
MainThread.postAfterFrames(2) {
tree.quit()
}
}
The rule is ownership: if the delayed code uses the scene, launch it from the
script; if it only touches global engine state, post it with
MainThread.post { } or MainThread.postAfterFrames(n) { }.
Godot-Owned Resources¶
close() releases your reference and never destroys an object someone else
still holds (Resource Ownership). A running
Tween is the exception: the scene tree runs it, so stop it through Godot
with kill() instead of closing it.
private var fadeTween: Tween? = null
fun fadeOut() {
fadeTween?.kill()
val tween = self.createTween()
fadeTween = tween
tween.tweenProperty(self, "modulate", Color.TRANSPARENT, 0.2).close()
tween.finished.connect(GodotObject.ConnectFlags.ONE_SHOT) {
if (fadeTween == tween) fadeTween = null
}
}
The Tweener that tweenProperty, tweenMethod and tweenCallback return is
a reference of your own, so close it once you have configured it, as above.
Every other resource you create or read back follows the ownership rule:
close() it, or use use { }, when you are done. After
meshInstance.setMesh(mesh) the node holds its own reference, and
mesh.close() releases only yours. A wrapper you forget is released later,
after the garbage collector drops it, so prefer use { } for big resources and
anything you make in a loop.
On Other Platforms¶
private var onFinished: (() -> Unit)? = null
fun finish() {
onFinished?.let { it() }
}
Call a function value directly, callback() or callback?.let { it() },
never with .invoke(): a .invoke() call does not compile for Android. See
Limitations.