Porting from GDScript¶
Move a Godot project from GDScript to Kotlin one script at a time; the script model itself is on Writing Scripts.
Porting Workflow¶
- Work in a branch or a copy of the original project.
- Add Kanama to it, as in Store Addon (Existing Project).
- Port one script at a time. Keep scene names, exported property names and signal connections as they are.
- Build your scripts and open the project in Godot, so imported assets and script metadata settle.
- Play the project and compare it with the original.
A port should behave like the original without changing its logic. If it only works with a workaround that Limitations does not list, please open an issue.
GDScript to Kotlin Mapping¶
The everyday script constructs, inside a KanamaScript<T> subclass (see
Writing Scripts for each one):
| GDScript | Kotlin |
|---|---|
extends CharacterBody3D |
@ScriptClass(attachTo = "CharacterBody3D") class Player(godotObject: GodotHandle) : KanamaScript<CharacterBody3D>(godotObject, ::CharacterBody3D) |
self.position |
self.position (this is the Kotlin script object) |
@onready var timer: Timer = $ScoreTimer |
private val timer by node<Timer>("ScoreTimer") |
@onready var skin: SophiaSkin = %SophiaSkin (script class) |
private val skin by script<SophiaSkin>("%SophiaSkin") |
$Path / get_node(path) used once |
self.requireAs<Timer>("Path") |
get_node_or_null(path) as Timer |
self.getNodeAs<Timer>("Path") |
x as Camera3D |
x.castOrNull<Camera3D>() |
var cam: Camera3D = x |
x.cast<Camera3D>() |
body is Player (script class) |
body.isScript<Player>() |
body as Player (script class) |
body.asScript<Player>() |
const BULLET = preload("res://bullet.tscn") |
private val bulletScene by preload<PackedScene>("res://bullet.tscn") |
var b: RigidBody3D = BULLET.instantiate() |
val b = bulletScene.instantiateAs<RigidBody3D>() |
var c: Coin = COIN.instantiate() (script root) |
val c = coinScene.instantiateScript<Coin>(), its node is c.self (coinScene preloaded as above) |
get_tree() / get_viewport() / get_parent() |
self.tree / self.viewport / self.parentNode |
await get_tree().create_timer(1.0).timeout |
launch { wait(1.0); ... } |
await get_tree().process_frame |
launch { nextFrame(); ... } |
await $Timer.timeout |
launch { timer.timeout.await(); ... } |
var body = await area.body_entered |
launch { val body = area.bodyEntered.await(); ... } |
area.body_entered.connect(func(body): ...) |
area.bodyEntered.connect { body -> ... } (body: Node3D, typed from Godot's API) |
timer.timeout.connect(_on_timeout, CONNECT_ONE_SHOT) |
timer.timeout.connect(GodotObject.ConnectFlags.ONE_SHOT) { onTimeout() } |
button.pressed.emit() |
button.pressed.emit() |
var label := Label.new(), var rng := RandomNumberGenerator.new() |
val label = Label.create(), val rng = RandomNumberGenerator.create() (any class GDScript can new; who frees it) |
func _ready(): |
@OnReady fun ready() |
func _input(event): |
@OnInput fun input(event: InputEvent) |
func show_message(text): |
fun showMessage(text: String) (every public function is registered) |
@export var speed := 5.0 |
@Export var speed = 5.0 |
Vector3(0, 1, 0), Vector3(speed, 0, 0), Color(1, 1, 1, 0.72) |
the same |
velocity.y += gravity * delta |
self.velocity = self.velocity.withY(self.velocity.y + gravity * delta) (value types are immutable; gravity is a property of your script) |
print(position) → (0.1, 0.2) |
GD.print(self.position) → (0.1, 0.2) |
var items: Array[String] = [] |
val items = mutableListOf<String>() (an Array is a List) |
var scores := {} |
val scores = mutableMapOf<String, Any?>() (a Dictionary is a Map; see Collections) |
v.is_equal_approx(w), v == w |
v.isEqualApprox(w), v == w (compares the stored components, as in GDScript) |
global_transform * Vector3.FORWARD, basis * other_basis, quat * dir |
the same operators |
2.0 * v |
the same, with import net.multigesture.kanama.types.*, which new scripts have |
Vector2i(4, 6) / 2, -color, a < b (vectors) |
the same |
x ** y |
x.pow(y) (kotlin.math) or GD.pow(x, y) (Godot's pow): Kotlin has no power operator |
Color.RED, Vector2i.LEFT, Vector3.MODEL_FRONT |
the same |
v.direction_to(t), rect.get_center(), Color.from_hsv(h, s, v) |
v.directionTo(t), rect.getCenter(), Color.fromHsv(h, s, v) |
path.get_extension(), name.to_snake_case() |
path.getExtension(), name.toSnakeCase(), with import net.multigesture.kanama.builtins.* |
String.num(x, 2) |
String.num(x, 2), same import |
text.begins_with("a") |
text.startsWith("a") (Kotlin's own; the list) |
", ".join(parts) |
parts.joinToString(", ") |
"%d" % n |
"$n" |
text.length(), text.find("x"), text.split(",") |
text.godotLength(), text.godotFind("x"), text.godotSplit(","): a name Kotlin already has gets a godot prefix |
"ff".hex_to_int(), "12abc".to_int() |
"ff".godotHexToInt(), "12abc".godotToInt() |
"{name}".format({"name": n}) |
"{name}".godotFormat(mapOf("name" to n)) (same package) |
bytes.decode_u32(0), bytes.get_string_from_utf8() |
bytes.decodeU32(0), bytes.getStringFromUtf8() (a ByteArray, same package) |
NodePath("a/b:x").get_name(1) |
NodePath("a/b:x").getName(1) |
Callable(obj, "m").call(1) |
GodotCallable(obj, "m").call(1) (no bind) |
Vector2(0.1, 0.2).x == 0.1 is false in Kotlin, as in GDScript. Every
decimal is a Double, and a vector, transform or color stores its components
as 32-bit floats, as Godot does, so equality, printing and arithmetic match the
GDScript you port. Compare with isEqualApprox. See
API Conventions.
A function that awaits in GDScript becomes a launch { } block: everything
after the first suspension runs on a later frame, and the block stops when the
script's object is freed.
Annotations and Declarations¶
Each GDScript annotation and declaration has one Kotlin form:
| GDScript | Kanama |
|---|---|
func f() (callable from Godot) |
a public fun f(); @GodotName("...") for another name |
@export var x |
@Export var x |
@export var area: Rect2, var pose: Transform3D = Transform3D.IDENTITY, func f(p: Plane) -> AABB, signal moved(t: Transform2D) |
the same types: every Godot value type (Vector4/4i, Rect2/2i, Plane, AABB, Quaternion, Basis, Transform2D/3D, Projection) is an export, parameter, return and signal type (Exports) |
@export_category / _group / _subgroup |
@ExportCategory / @ExportGroup / @ExportSubgroup |
@export_tool_button("Label") |
@ExportToolButton("Label") |
signal hit(damage) |
@Signal fun hit(damage: Long) = Unit; typed handle player.hit (hit.emit(5), player.hit.connect { damage -> }) |
@rpc(...) |
@Rpc(...) on a public function |
jump.rpc() / jump.rpc_id(id) on a call_local RPC |
PlayerRpcs.callLocalJump(this) / PlayerRpcs.rpcIdJump(this, id); this is the script object (Multiplayer) |
@tool |
@Tool |
class_name Player |
@GlobalClass |
func _ready(), _enter_tree, _exit_tree |
@OnReady, @OnEnterTree, @OnExitTree |
func _process(delta), _physics_process |
@OnProcess, @OnPhysicsProcess |
func _input(event), _unhandled_input, _shortcut_input, _unhandled_key_input |
@OnInput, @OnUnhandledInput, @OnShortcutInput, @OnUnhandledKeyInput (event: InputEvent) |
any other func _virtual() |
@OverrideVirtual fun _virtual() |
Porting Checklist¶
@Exportnames register assnake_casein Godot..tscnvalues must match:view_path = NodePath("../View"), notviewPath.- Remove
uid://...from scriptext_resourceentries when replacing a.gdscript with a.ktscript. Godot assigns new UIDs on first open. - Remove stale
node_paths=PackedStringArray(...)entries from node headers when they only described old GDScript exports. - Every public function is registered, like a GDScript
func:fun onCoinCollected()registers ason_coin_collected. Keep a.tscnconnection to_on_coin_collectedworking with@GodotName("_on_coin_collected"), or update the connection. Make functions Godot never callsprivate(orinternal). - GDScript's
func _ready(),_process,_input, … become a lifecycle annotation on a function of any name (@OnReady fun ready()); a function still named_processwithout one is a build error. Input handlers take the typed event:@OnInput fun input(event: InputEvent). - For instanced scenes, look a node up as the class Godot actually created
(
node<Node3D>(path)for an imported GLB root) unless the exact imported root class is known and stable. - Prefer
node<T>()/requireAs<T>()when the original scene requires a node to exist. UsegetNodeAs<T>()only when the original behavior was optional. - Preserve type checks:
if body is Playerisbody.isScript<Player>(), not ahasMethod(...)probe or a node-name test. - Keep
GodotObject.call(...)at true mixed-language boundaries, such as a GDScript autoload kept during an incremental port. Use typed wrappers and direct Kotlin calls for known Kanama scripts. - Godot enum constants become typed values:
Node.PROCESS_MODE_ALWAYSisNode.ProcessMode.ALWAYS,KEY_ESCAPEisKey.ESCAPE, a bitfield combines withorand tests within. An@export var mode: Node.ProcessModeports to@Export var mode: Node.ProcessMode = Node.ProcessMode.INHERIT; it stores the same Godot values, so the scene'smode = 3keeps working. A GDScriptintthat really holds an enum (var mode := 3) is worth typing during the port. See Godot Enums and Bitfields. - For
@Rpcmethods on Kanama scripts, use the generated*Rpcssenders instead of rawrpc("method_name")strings, and portjump.rpc()as a sender call, never asjump(): a direct call runs on this peer only. - For scenes with
MultiplayerSynchronizer, verify every replicated custom.:propertyis exposed with@Export.
When a typed lookup fails, check the actual runtime class before changing the
lookup. Godot often imports GLB scene roots as Node3D, with the mesh attached
as a descendant, even when the visual asset is conceptually a mesh.
For a multiplayer game, run the two multiplayer checks after the first working pass.
Common Porting Patterns¶
Mixed projects are valid while you migrate. A Kanama script can call a retained GDScript autoload through the normal Godot object API:
Autoloads.Audio.call("play", "res://sounds/coin.ogg") // GDScript: Audio.play("res://sounds/coin.ogg")
A Kotlin autoload is typed to its script class, so Autoloads.Settings.save()
needs no lookup or cast (see Scripts → Autoloads). A
script that extends another script class ports to a Kotlin subclass with no
forwarding overrides (see Scripts → Script Inheritance),
and each @export_* annotation has a typed twin
(Exports and Resources).
When the original exported a node (@export var target: Node3D), export it
as its class, @Export var target: Node3D? = null. When it exported a path on
purpose, keep the NodePath and look the node up with it:
@Export var targetPath: NodePath = NodePath(".")
private var target: Node3D? = null
@OnReady
fun ready() {
target = self.requireAs<Node3D>(targetPath)
}
Use @GodotName("saved_signal_name") when a .tscn file already has a
saved signal connection and you want to preserve the stored method name.
Example Ports¶
The public kanama-demos repository includes ports that can be used as examples for common migration areas:
| Project | Useful For |
|---|---|
| Godot 2D Dodge the Creeps | 2D movement, saved scene connections, signals, timers, Android |
| Godot 3D Squash the Creeps | instanced scenes, 3D physics, animation, signal wiring |
| GDQuest 3D Third Person Controller | camera/control logic and CharacterBody3D movement |
| Godot 4 3D Character Controller Tutorial | compact 3D movement and input |
| Godot TPS Demo | larger 3D scenes, threaded loading, RPC senders, multiplayer synchronizers, and scene reload cleanup |
| Kenney Starter Kit 3D Platformer | NodePath exports, GDScript autoload interop, typed callbacks, coroutine delays |
| Kenney Starter Kit Match-3 | UI, typed resource lists, textures, scene-authored data |
| Kenney Starter Kit City Builder | tile/grid workflows and larger scene data |
| Kenney Starter Kit FPS | input, weapons/resources, 3D gameplay structure |
For building, reloading and debugging while you port, see Edit, Build, Run.
On Other Platforms¶
A port runs on desktop, Android and iOS from the same source. Web needs a few
changes, such as driving movement from velocity and moveAndSlide() instead
of re-reading a position you just wrote; see
Limitations.