Upgrading from 0.4 to 0.5¶
Kanama 0.5 is a large step for a pre-1.0 preview. The generated Godot API now follows one set of rules on every platform, so some names, types and nullability changed, and a number of things that behaved differently on Web, iOS and desktop now behave the same. Before 1.0 such source breaks are allowed when they serve the API's long-term shape, but each one is announced in the changelog and, wherever a script can do it, fixed for you.
This page lists every announced source break and the behaviour changes that do not stop the build but change results, with the code you had in 0.4 and the code you write now.
Who needs this¶
- You have Kotlin scripts written against 0.4 (desktop, Android, iOS or Web): read it and follow the order below.
- You start a new project from a 0.5 release kit, store addon or starter template: you do not need it. The starters already use the 0.5 spellings.
- You maintain your own Kanama checkout or scripts that call Kanama's Gradle tasks: read Tooling, Gradle and the editor.
The order to do things in¶
- Commit your project. The migration scripts rewrite files in place.
- Bump the version.
- Source checkout: update the checkout to the 0.5 release (
git pull, or check out its tag), then rerun theinstallAddonJarcommand from Use a Source Checkout against your project. - Store addon: unzip the 0.5
kanama-store-addonzip at the root of your Godot project (it replacesaddons/kanamaandaddons/kanama_tools). Your rootbuild.gradle.ktsandsettings.gradle.ktsare yours; compare them withaddons/kanama/templates/release-kit. Three things changed: the JDK toolchain resolver insettings.gradle.kts(see Tooling); thekotlin("jvm")andcom.google.devtools.kspplugin versions inbuild.gradle.kts, now 2.4.21 and 2.3.12 (the 0.4 versions, 2.3.21 and 2.3.9, still build); and the Kanama Gradle plugin, which needs the template'spluginManagement { }block insettings.gradle.ktsandid("net.multigesture.kanama")inbuild.gradle.kts. Without the plugin, desktop builds still work, but Android export needs it. - Release kit: a kit is for new projects. Copy your
kotlin-srcinto a project made from the 0.5 kit, or apply the store-addon steps above. - Use the Godot 4.8 editor and export templates for the build: 4.8 stable
with release 0.5, 4.8 beta 2 with a checkout of
main(see Godot Version).
- Source checkout: update the checkout to the 0.5 release (
-
Run the migration scripts on your Kotlin sources, in this order. They are Python 3 files in the
scripts/folder of a Kanama checkout (the packaged kits do not carry them) and take your source folder as the argument:python3 scripts/migrate_script_annotations.py path/to/kotlin-src python3 scripts/migrate_export_hints.py path/to/kotlin-src python3 scripts/migrate_enum_constants.py path/to/kotlin-srcThe annotation script must run first: it turns
@ScriptPropertyinto@Export, which the hint script then splits into@ExportRangeand friends. Each script prints what it changed and what needs a human, and running one again on migrated sources changes nothing. Preview with--check(the first two) or--dry-run(the enum script) before letting them write. See Script annotations and export hints and Enums and bitfields. 4. Build and fix what the compiler still reports. Use the table below to find the section for each message. 5. Re-export. A Web game must be rebuilt and re-exported: the bridge is at protocol 39 and a page built with an older protocol refuses to run, so never mix builds. Rebuild iOS and Android scripts too: the generated registrars changed. 6. Read Silent changes to check. They compile and still change results.
| The compiler (or a script) says | Section |
|---|---|
Unresolved reference on Node.PROCESS_MODE_ALWAYS, Tween.TRANS_SINE, InputEventKey.KEY_W, GodotObject.CONNECT_DEFAULT |
Enums and bitfields |
Type mismatch: inferred type is Long, but Int/Double/GodotError was expected |
Enums, Integer widths, Signals |
Float expected where you pass Double, or the reverse, on a vector or color |
Decimal values are Double |
| Deprecated annotation with a message naming a replacement | Script annotations |
FileAccessHandle / DirAccessHandle, fileExistsAt, writeString |
FileAccess and DirAccess |
MemorySegment in a script constructor |
The script constructor handle |
Only safe (?.) or non-null asserted (!!.) calls are allowed after getTree(); Unnecessary safe call in a tween chain |
Node, SceneTree, Viewport and Resource, Tween |
Web: set("position:x", ...) stopped moving the node, a Web* import no longer resolves |
Web |
What changes at a glance¶
- A Web script and a desktop script now behave the same. Web compiles the
same
GD,Mathf, value types,GodotCallableand typed signals, follows the same ownership and freed-object rules, reports script exceptions to Godot's log, and uses Godot's random generator. - The Godot API is generated once. About twenty classes that were hand
written per platform (
Node,SceneTree,Tween,FileAccess,DirAccess,Engine, ...) are generated like the rest, so a member exists on every native platform or on none. iOS gained a lot (the fullTween,FileAccess,DirAccess,Engine,GD). - Every Godot enum and bitfield is a typed value class
(
Node.ProcessMode.ALWAYS,Key.W), andconnectreturns aGodotError. - Every decimal value is
Double, including vector and color components. - One annotation set, like GDScript's. Public functions are registered
automatically,
@Exporthas typed hints (@ExportRange), and input handlers take anInputEvent. close()is optional. ARefCountedyou forget is released after the garbage collector drops it, on every thread and platform.close()anduse { }release early.- New for scripts (nothing to migrate): typed engine and
@Signalsignals withawait(),node<T>()/script<T>()/preload<T>()delegates, checked casts, generatedAutoloads, script inheritance, all Godot value types as script types, Godot'sString,NodePathandPackedByteArraymethods.
The rest of this page is organised by area.
Kotlin API surface¶
The script constructor handle¶
GodotHandle was a typealias for java.lang.foreign.MemorySegment on desktop
and Android. It is a @JvmInline value class now, declared once for every native
backend, so no public signature names an FFM type and one script source compiles
everywhere.
A script written as the templates always showed compiles unchanged:
class Player(godotObject: GodotHandle) : KanamaScript<CharacterBody3D>(godotObject, ::CharacterBody3D)
What breaks is code that spelled the old type or reached through the handle:
// 0.4
import java.lang.foreign.MemorySegment
class Player(godotObject: MemorySegment) : KanamaScript<CharacterBody3D>(godotObject, ::CharacterBody3D)
val raw = body.handle.address()
// 0.5
import net.multigesture.kanama.api.GodotHandle
class Player(godotObject: GodotHandle) : KanamaScript<CharacterBody3D>(godotObject, ::CharacterBody3D)
val same = body.isSameInstance(other) // no raw pointer by design
Re-wrapping through another wrapper's handle (CharacterBody3D(body.handle),
selfAs(::Node3D)) is unchanged. Three desktop-only helpers keep a
MemorySegment parameter on purpose, because they take a native pointer:
GDExtensionManager.loadExtensionFromFunction,
OpenXRAPIExtension.transformFromPose and OpenXRAPIExtension.setCustomPlaySpace.
A script left on the old type fails with a message that spells out this
migration. No script fixes it.
Decimal values are Double¶
Vector, transform and color components are Double in every signature on every
platform, like GDScript's 64-bit float. In 0.4 they were real_t (Float in
the single-precision builds Kanama ships) and Color was Float. The value
types keep storing Godot's width internally (so node.position = v;
node.position == v is true), but you no longer see Float.
// 0.4
val v = Vector3(0f, 1f, 0f)
val c = Color(1f, 1f, 1f, alpha.toFloat())
val x: Double = v.x.toDouble()
val dim = c.copy(a = alpha.toFloat())
// 0.5
val v = Vector3(0.0, 1.0, 0.0)
val c = Color(1.0, 1.0, 1.0, alpha)
val x: Double = v.x
val dim = c.copy(a = alpha)
- Integer literals construct without boxing:
Vector3(0, 1, 0),Vector3(speed, 0, 0),Color(1, 1, 1, 0.72),v * 2,v.withX(0).Vector4,QuaternionandPlane(x, y, z, d)take all-Intor all-Doublearguments. - The classes are no longer
dataclasses.copy,componentN,equalsandhashCoderemain. - The typealias
real_tandGodotReal.fromNumber/fromDouble/fromFloatare removed;GodotRealSegment.readIndex/writeIndextake and returnDouble. Game code does not use them. - Your own
Floatfields that hold components or channels becomeDouble. - Compare decimals you wrote with the value you read back through
isEqualApprox, as in GDScript:Vector2(0.1, 0.2).x == 0.1isfalsein a float32 build.
Parameter names and one return type follow Godot's for the members that moved
into the generated value-type set (Vector3.reflect(line) is new); only calls that name the argument notice:
| Member | 0.4 | 0.5 |
|---|---|---|
Vector2.limitLength, Vector3.limitLength |
limitLength(maxLength) |
limitLength(length = 1.0) |
Vector3.bounce |
bounce(normal) |
bounce(n) |
Transform3D.interpolateWith |
interpolateWith(to, weight) |
interpolateWith(xform, weight) |
Vector3.maxAxisIndex() (iOS; desktop gains it) |
Int |
Long: compare with Vector3.Axis.X.value or a Long literal |
Script: none; fix by hand (the compiler lists every site).
FileAccess and DirAccess¶
FileAccess and DirAccess are RefCounted classes now, as in GDScript, on
every platform (iOS gained all of both). FileAccessHandle and
DirAccessHandle are gone, as are the 38 FileAccess and 23 DirAccess
helpers that took a path on every call. Open the file, use it, close it:
// 0.4
val h: FileAccessHandle? = FileAccess.open("user://save.txt", FileAccess.WRITE)
FileAccess.writeString("user://save.txt", text)
val first = FileAccess.getLineFor("user://save.txt")
val word = FileAccess.get32At("user://data.bin", 16L)
val exists = DirAccess.fileExistsAt("user://", "save.txt")
val all = DirAccess.getFilesAt("user://", includeHidden = true)
// 0.5
FileAccess.open("user://save.txt", FileAccess.ModeFlags.WRITE)?.use { it.storeString(text) }
val first = FileAccess.open("user://save.txt", FileAccess.ModeFlags.READ)?.use { it.getLine() }
val word = FileAccess.open("user://data.bin", FileAccess.ModeFlags.READ)?.use {
it.seek(16L)
it.get32()
}
val exists = DirAccess.open("user://")?.use { it.fileExists("save.txt") }
val all = DirAccess.open("user://")?.use { dir ->
dir.includeHidden = true
dir.getFiles()
}
FileAccess.openreturns an ownedFileAccess?(null, with the reason inFileAccess.getOpenError()); so doopenCompressed,openEncrypted,openEncryptedWithPass,createTemp, andDirAccess.open/createTemp. WriteFileAccess/DirAccesswhere you named the handle type, andFileAccess.fromHandle(h)forFileAccessHandle.fromHandle(h). There is no deprecated alias.- The forms that took a
positionbecomeit.seek(position)before the read;getPositionFromEnd(path, p)becomesit.seekEnd(p)thenit.getPosition(). Big-endian isit.bigEndian = truefirst; a resize opensREAD_WRITEand callsit.resize(n). - Whole-file reads keep Godot's statics:
FileAccess.getFileAsString(path)andgetFileAsBytes(path). Godot's directory statics stay too:getFilesAt(path),getDirectoriesAt(path),makeDirAbsolute,makeDirRecursiveAbsolute,removeAbsolute,copyAbsolute,renameAbsolute,dirExistsAbsolute,getDriveCount,getDriveName,getOpenError. A walk with "is directory" useslistDirBegin(),getNext(),currentIsDir(),listDirEnd()as in GDScript. FileAccess.close()closes the file and releases your reference (also on a borrowed view). Godot's ownclose()iscloseFile(), which closes the file and keeps your reference.DirAccess.close()only releases the reference.- Always
use { }a file you open. Unlike GDScript, a file you forget stays open, with its writes unflushed, until the garbage collector releases it (see Ownership). - Signatures follow Godot:
DirAccess.getDriveCount()returnsInt,getDriveName(idx: Int);FileAccess.get8()/get16()returnIntandstore8/store16takeInt; theFileAccessstatics name their pathfile(getModifiedTime,getSize,getUnixPermissions, ...);storeString(string).FileAccessis a class now, not an object:is FileAccesstests a file instance.
Script: none.
Node, SceneTree, Viewport and Resource¶
These classes were hand written on desktop and are generated now. The generated shape won, which changes integer widths, a few names and nullability. iOS sees almost none of this (it already had the generated shapes).
Node. Godot's int32 is Int:
// 0.4
val n: Long = node.getChildCount()
val last = node.getChild(n - 1)
node.setProcessPriority(5L)
val copy = node.duplicate(Node.DUPLICATE_SIGNALS or Node.DUPLICATE_GROUPS)
self.getTree().quit()
// 0.5
val n: Int = node.getChildCount()
val last = node.getChild(n - 1) // getChild(idx: Int)
node.setProcessPriority(5)
val copy = node.duplicate(
Node.DuplicateFlags.SIGNALS.value.toInt() or Node.DuplicateFlags.GROUPS.value.toInt()
)
self.getTree()?.quit() // or SceneTree.quit()
getChildCount,getIndex,getMultiplayerAuthority, the process and physics-process priorities and the thread group order areInt. ALong-typed counter fed from them needs.toLong(), and?: -1Lfallbacks become?: -1.duplicate(flags: Int = ...)takes anInt. The flag constants are typed values now, andDuplicateFlagsis an enum in Godot's API, not a bitfield, so combine their.values as above (the enum script rewrites the constants but leaves this call to you), or pass the default withduplicate().Node.getTree()isSceneTree?. Useself.treein a script (non-null, it throws if the node is outside the tree),getTree()?., or theSceneTreecompanion entry points (SceneTree.quit()), which resolve the running tree.createTween()stays a member ofNodeandSceneTreeand now returns a non-nullTween(it wasTween?); see Tween.- Parameter names follow the generator:
addChild(node, forceReadableName, internalValue)(wasinternalMode) andsetEditorDescription(editorDescription). Thirteen properties arrive (name,processMode,sceneFilePath, ...).
SceneTree. The old desktop object SceneTree, the placeholder
SceneTreeHandle and iOS's own class are one generated SceneTree : MainLoop.
Every old entry point survives on the companion, typed like the instance member
it calls, so SceneTree.quit(), SceneTree.delaySeconds(...),
SceneTree.unloadCurrentScene() and friends read as before. What changed:
| 0.4 | 0.5 |
|---|---|
getNodeCount(): Long, getNodeCountInGroup(name): Long |
Int |
quit(exitCode: Long = 0) |
quit(exitCode: Int = 0) |
notifyGroup(group, notification: Long) |
notification: Int |
getRoot(): GodotHandle |
getRoot(): Window (non-null) |
getCurrentScene(): GodotHandle, getFirstNodeInGroup(name): GodotHandle |
Node? |
setCurrentScene(nodeObject: GodotHandle) |
setCurrentScene(childNode: Node) |
queueDelete(nodeObject: GodotHandle) |
queueDelete(obj: GodotObject) |
changeSceneToPacked(h: GodotHandle): Long |
changeSceneToPacked(packedScene: PackedScene): GodotError |
changeSceneToNode(h: GodotHandle): Long |
changeSceneToNode(node: Node): GodotError |
changeSceneToFile(path): Long, reloadCurrentScene(): Long |
GodotError |
getMultiplayer(forPath: String = ""): GodotHandle |
getMultiplayer(forPath: NodePath): MultiplayerAPI on the instance; the companion keeps the default: getMultiplayer(forPath: NodePath = NodePath("")) |
A Java caller of the companion entry points writes SceneTree.Companion.quit().
SceneTree.delaySeconds waits in engine frames on every platform now, so it
honors pause and time scale (see iOS).
Viewport and Resource.
Viewport.pushInput/pushUnhandledInputtake a non-nullInputEvent.getCamera2D()/getCamera3D()stay.Resource.asObject()is gone:Resourceis aGodotObject, callsetMeta,connect,callDeferredon it directly.Resource.duplicate(deep: Boolean = false)(wassubresources) andduplicateDeep(deepSubresourcesMode: Resource.DeepDuplicateMode = ...).Resource.generateSceneUniqueId()loses@JvmStatic: a Java caller writesResource.Companion.generateSceneUniqueId().- The primary constructors of generated classes are public (
Resource(handle)is a borrowed view: neverclose()a wrapper you made over a handle).
RefCounted and GodotObject.
RefCounted.getReferenceCount()returnsInt(wasLongon desktop): write?: 0, not?: 0L. The constructor isinternaleverywhere; useRefCounted.fromHandle(handle)for a borrowed view.GodotObject.set(property, value)returnsUnitinstead of an always-zeroLong: dropval r = node.set("x", 1).GodotObject.fromHandleandRefCounted.fromHandleare public on every platform.
TabBar, AnimationPlayer, Button, LineEdit, Range, Slider. Twelve
desktop properties take the generator's names (the Godot property name), and the
accessor pairs underneath are untouched, so a script that called getMin() /
setMin() needs no edit:
| Class | 0.4 | 0.5 |
|---|---|---|
Button |
buttonIcon |
icon |
Button |
textAlignment |
alignment |
LineEdit |
horizontalAlignment |
alignment |
LineEdit |
placeholder |
placeholderText |
LineEdit |
expandToTextLengthEnabled |
expandToTextLength |
LineEdit |
caretBlinkEnabled |
caretBlink |
LineEdit |
caretMidGraphemeEnabled |
caretMidGrapheme |
Range |
min / max |
minValue / maxValue |
Range |
useRoundedValues |
rounded |
Range |
expRatio |
expEdit |
Slider |
ticks |
tickCount |
Also: Range.valueChanged(newValue) (it bound a private virtual, not the
signal) is gone, and Range.Signals.valueChanged is unchanged;
Range.setPage's parameter is pagesize; LineEdit.getMenu() returns
PopupMenu?; TabBar.addTab(title: String = "", icon: Texture2D?) has no
default for icon, so tabBar.addTab("Alpha") becomes tabBar.addTab("Alpha", null);
AnimationPlayer.Signals.animationFinished lives on its base class, write
AnimationMixer.Signals.animationFinished (same string).
Script: none for any of this; the compiler finds every site.
Tween and tweeners¶
// 0.4
val t: Tween? = self.createTween()
t?.setLoops(3L)
if ((t?.getLoopsLeft() ?: 0L) > 0L) { }
t?.tweenProperty(self, "position", target, 0.5)
?.setTrans(Tween.TRANS_BACK)
?.setEase(Tween.EASE_OUT)
// 0.5
val t = self.createTween() // Tween, never null
t.setLoops(3) // loops: Int
if (t.getLoopsLeft() > 0) { } // getLoopsLeft(): Int
t.tweenProperty(self, "position", target, 0.5)
.setTrans(Tween.TransitionType.BACK)
.setEase(Tween.EaseType.OUT) // non-null chain
createTween()andgetProcessedTweens()are members ofNodeandSceneTreeon every platform. If your code importsnet.multigesture.kanama.api.createTween,...getProcessedTweensor (iOS)...setExclude(only builds ofmainbetween 0.4 and 0.5 needed them), delete the import: the calls resolve to the members, includingPhysicsRayQueryParameters3D.setExclude(List<RID>).Tween.setLoops(loops: Int = 0)andgetLoopsLeft(): IntuseInt;tweenSubtween(subtween: Tween)takes a non-nullTween.- The
Tweenerfamily is generated once. The fluent setters and the builder methods return non-null types (Godot marks them required; a null from the engine throws), so?.in a chain compiles with a warning: change it to.. - iOS
Tween.tweenProperty(target, property, finalValue, duration)takes any Variant value (aDoublerotation, aVector3, a typed enum); it used to tween everything but aVector2orColortoVector2(0, 0).Tweener.setTrans/setEaselive onPropertyTweenerandMethodTweener(where Godot declares them);tweenMethodreturnsMethodTweener.
Script: migrate_enum_constants.py rewrites the Tween.TRANS_* / EASE_*
constants; the rest is by hand.
Engine, BoxMesh, AudioStreamPlayer, ResourceLoader and other classes generated once¶
Twenty classes that were written per platform are generated once now
(ConfigFile, ENetMultiplayerPeer, InputEventKey, InputEventMouseMotion,
LightmapGI, MeshDataTool, NoiseTexture2D, SceneMultiplayer,
ShaderMaterial, SurfaceTool, ImageTexture, ParticleProcessMaterial,
ProceduralSkyMaterial, ProjectSettings, BoxMesh, BoxShape3D,
AudioStreamPlayer, ResourceLoader, Engine, ...). The desktop names,
overloads and factories are kept. What breaks:
// 0.4
Engine.registerSingleton("Settings", obj.handle)
val sub: Long = boxMesh.subdivideWidth
player.maxPolyphony = n.toLong()
ResourceLoader.addResourceFormatLoader(loaderOrNull)
// 0.5
Engine.registerSingleton("Settings", obj) // the object, not its handle
val sub: Int = boxMesh.subdivideWidth // BoxMesh.subdivide*, AudioStreamPlayer.maxPolyphony: Int
player.maxPolyphony = n.toInt()
ResourceLoader.addResourceFormatLoader(loader) // non-null ResourceFormatLoader
Engine.registerSingletonstill rejects aRefCountedinstance, now with anIllegalArgumentExceptionon every platform (desktop threwIllegalStateException).ResourceLoader.ThreadLoadStatus, the data class, isResourceLoader.ThreadLoadProgress(status, progress):ThreadLoadStatusis Godot's enum name now.loadThreadedRequestreturnsGodotError.- iOS compile errors:
Engine.getMainLoop()returnsMainLoop?(it returned aGodotHandle; useEngine.getMainLoop()?.handle);fromResource(value)ofShaderMaterial,ParticleProcessMaterialandProceduralSkyMaterialtakes a non-nullResource(res?.let { ShaderMaterial.fromResource(it) }); the iOS-onlyLongoverload ofShapeCast3D.getCollisionPointis gone (pass anInt:getCollisionPoint(Int), andgetCollisionCount()returnsInt);PhysicsRayQueryParameters3D.create(from, to)returnsPhysicsRayQueryParameters3D?there too (add?: returnor!!). - iOS, calls compile unchanged:
AudioStreamPlayer.play(fromPosition: Double = 0.0)andsetStreamFromPath(path)(it gains desktop'scacheMode);NoiseTexture2D.setGenerateMipmaps(generate);ProjectSettings.getSettingDouble(name, defaultValue = 0.0);SurfaceTool.commit(existing: ArrayMesh? = null, flags: Long = 0)is one function with defaults, so only a function referenceSurfaceTool::commitchanges. - Renamed parameters matter only to a call that names its arguments:
AudioStreamPlayer.setBus(bus)/setPitchScale(pitchScale)/setVolumeDb(volumeDb)/setStreamPaused(paused)on iOS.
Script: none.
GD and Mathf¶
GD is generated once from Godot's utility functions (all 114, the same on every
platform, including Web), and Mathf is common code.
// 0.4
GD.typeString(type.toInt())
GD.errorString(err.toInt())
GD.randfn() // had defaults
val a = Mathf.inverseLerp(from = 0.0, to = 10.0, value = x) // named argument, iOS
// 0.5
GD.typeString(type) // Long
GD.errorString(err) // Long
GD.randfn(0.0, 1.0) // Godot's randfn has no defaults
val a = Mathf.inverseLerp(from = 0.0, to = 10.0, weight = x)
- Parameters are named as Godot names them (
GD.sin(angleRad),GD.degToRad(deg),GD.seed(base),GD.typeOf(variable),GD.hash(variable)), which matters only to a call that names its arguments. GD.typeStringandGD.errorStringtake aLong(a literal still compiles).GD.isInstanceValidtakesGodotObject?on every platform (desktop 0.4.0 tookAny?); for an instance id useGD.isInstanceIdValid(id). iOS:GD.degToRad/radToDegname their parameterdeg/rad.- Web, in builds of
mainbetween 0.4 and 0.5 (0.4.0's preview had noGD.printand aMathfwith onlyabsandlog):GD.print(message)isGD.print(vararg values);Mathf.pow(x, y),Mathf.PI/Mathf.TAUareconst; see Web.
Script: none.
InputEventMouseButton¶
One shared class on every platform. On iOS it now extends InputEventMouse (it
extended InputEvent), so every member compiles everywhere.
InputEventMouseButton.from(event) returns null for an InputEventScreenTouch
on iOS; before, it wrapped the touch as a mouse button. A touch reaches
mouse-button code through Godot's
input_devices/pointing/emulate_mouse_from_touch setting (on by default), as on
every other platform. Code that wants the touch itself reads
event.castOrNull<InputEventScreenTouch>(); InputEventScreenTouch.create() and
InputEventScreenTouch.from(event) are new.
Script: none.
Coroutines: KanamaCoroutineOwner¶
KanamaCoroutineOwner is removed and KanamaScope is internal, on every
platform: a script's coroutines live on its KanamaScript scope, which freeing
the script cancels.
// 0.4
class Hud(godotObject: GodotHandle) :
KanamaScript<CanvasLayer>(godotObject, ::CanvasLayer), KanamaCoroutineOwner {
override val kanamaScope = KanamaScope()
fun flash() { kanamaScope.launch { SceneTree.delaySeconds(1.0); self.hide() } }
}
// 0.5
class Hud(godotObject: GodotHandle) : KanamaScript<CanvasLayer>(godotObject, ::CanvasLayer) {
fun flash() { launch { wait(1.0); self.hide() } }
}
kanamaScope.launch(...) with arguments is scriptScope.launch(...), and
kanamaScope.cancel() is cancelCoroutines() (the scope stays usable). The
generated registrar no longer cancels the scope on _exit_tree; leaving the tree
does not stop a coroutine (as in GDScript), freeing does. KanamaScript itself
moved into common code with unchanged members: a script does not notice.
Script: none; the change is mechanical (kanamaScope.launch becomes launch).
Changes that need no edit¶
Announced because the signature snapshots record them; your code compiles as is.
- Web classes
Texture2D,AudioStream,PackedScene,InputEventKey,InputEventMouseButton,Mesh,Material,ButtonGroup,ConfigFile,FastNoiseLite,MeshLibrary,KinematicCollision3DandScriptResourceno longer declareclose()andAutoCloseablethemselves; both come fromRefCounted. - The typed signal classes
TypedSignal,Signal0...Signal5were reshaped only against an unreleased first version (TypedSignal.ownerisemitter; the nullability of a few signal arguments follows a scan of Godot's source). 0.4 had none of these declarations. kanamaIosRuntimeReleaseCallableandkanamaIosRuntimeDispatchCallableare entry points of the iOS C shim, not for scripts.- On Web
KanamaScript.selfis public, as on the other platforms, so shared code can reach an autoload's node (Autoloads.Events.self). - The per-platform
kotlinScriptInstance<T>()extension on nodes is now the commonGodotObject.kotlinScriptInstance<T>(); calls compile unchanged. GodotSignal's default arguments became overloads (connect(target, method)plusconnect(target, method, flags), and so on): positional, trailing-lambda and named-argument calls compile unchanged. A script compiled against an oldkanama.jarcalls the removed$defaultmethods: recompile the scripts (the normal build does).
Enums and bitfields¶
Every Godot enum and bitfield is a @JvmInline value class wrapping its Long:
764 class enums, 22 global enums and the value-type enums, 793 in all. A class
enum nests in its class (Node.ProcessMode, Tween.TransitionType,
GodotObject.ConnectFlags, Vector3.Axis); a global enum is top-level in
net.multigesture.kanama.api under Godot's name. Every parameter, return and
property Godot types as an enum or bitfield uses the class. There are no
deprecated aliases: the old const val values are gone.
// 0.4
self.setProcessMode(Node.PROCESS_MODE_ALWAYS)
tween.setTrans(Tween.TRANS_SINE)
if (event is InputEventKey && event.keycode == InputEventKey.KEY_W) { }
button.mouseFilter = Control.MOUSE_FILTER_IGNORE
val err = node.connect("tree_exiting", target, "on_exit", GodotObject.CONNECT_DEFAULT)
if (err != 0L) { }
ResourceLoader.loadThreadedRequest(path, "", false, ResourceLoader.CACHE_MODE_REUSE)
// 0.5
self.setProcessMode(Node.ProcessMode.ALWAYS)
tween.setTrans(Tween.TransitionType.SINE)
if (event is InputEventKey && event.keycode == Key.W) { }
button.mouseFilter = Control.MouseFilter.IGNORE
val err = node.connect("tree_exiting", target, "on_exit", GodotObject.ConnectFlags(0L))
if (err != GodotError.OK) { }
ResourceLoader.loadThreadedRequest(path, "", false, ResourceLoader.CacheMode.REUSE)
- Four global enums carry a Kanama name because Godot's name collides with
Kotlin or with Kanama:
ErrorisGodotError,PropertyHintisGodotPropertyHint(Kanama's annotation constantsannotations.PropertyHintstay as they are),Variant.TypeisVariantType,Variant.OperatorisVariantOperator. 0.4 had no typed global enums, so you meet these names in the return type ofconnectand in values such asGodotError.OK. - Value names drop the enum's common prefix, by the rule Godot's C# bindings
use, keeping SCREAMING_CASE:
PROCESS_MODE_ALWAYSisALWAYS,TRANS_SINEisSINE,KEY_WisW. A name that would start with a digit keeps a word (Key.KEY_0); enums with no common prefix keep Godot's names (GodotError.ERR_FILE_NOT_FOUND). The prefix of each enum is frozen, so a later Godot adding a value never renames its siblings. The full old to new table is Enum Constant Migration. - The hand-written subsets move to the real enums:
InputEventKey.KEY_*isKey.*,InputEventMouseButton.MOUSE_BUTTON_*isMouseButton.*,PhysicsBody3D.BODY_AXIS_*isPhysicsServer3D.BodyAxis.*, and Kanama's ownGodotObject.CONNECT_DEFAULTisGodotObject.ConnectFlags(0L)(Godot names no zero flag). Non-enum class constants (Node.NOTIFICATION_READY) stayconst val. - Raw values stay reachable:
Node.ProcessMode(3L)builds any value,.valuereads theLong. Bitfields addor,and,xor,inv()andin(contains); the empty set isX(0L). - Dynamic calls take the typed values. Every enum class implements
GodotEnumValue, andcall,set,callDeferred,emitSignal,ConfigFile.setValueand Array/Dictionary elements pass it as the INT it stands for. What comes back from a dynamic path (get,call, Variant returns) is still aLong. GodotObject.connect,GodotSignal.connectand the lambda overloads takeflags: GodotObject.ConnectFlagsand returnGodotError;SignalConnection.erroris aGodotError(compare withGodotError.OK, not0L). The KSP signal helpersconnect<Signal>(instance, target, flags = ...)andrpc<Method>/rpcId<Method>follow.ResourceLoader.loadThreadedGetStatusreturnsResourceLoader.ThreadLoadStatus, the enum, and thecacheModeparameters takeResourceLoader.CacheMode.- The 38 object returns Godot marks required are non-null (
Node.createTween(),SceneTree.createTween()/createTimer()/getRoot()/getMultiplayer(),CanvasItem.makeInputLocal,InputEvent.xformedBy, everyTweenbuilder and fluent setter, ...). A chain uses.instead of?.. A null from the engine is an engine bug and throwsIllegalStateException("Godot returned null from required <Class>.<method>"). - Web has the same types and names. Removed on Web: the hand subsets, the enum
const vals (Window.MODE_*,DisplayServer.VSYNC_*, ...) and the Web-only top-levelBodyAxis(usePhysicsServer3D.BodyAxis).SceneTree.getRoot()on Web returnsWindow(it was a rawGodotHandle). - A Godot enum class is also an
@Exporttype and a@Signal/@Rpcargument type; see Exporting Enums. An engine virtual you override with@OverrideVirtualtakes the value class where Godot types it as an enum: an override still declaringLongfails the build naming the type to use.
Script: migrate_enum_constants.py path/to/kotlin-src rewrites Owner.OLD to
Owner.Enum.NEW (and the hand subsets), adds the imports a file needs, and lists
what a human must fix. It cannot fix a raw number passed where an enum is now
required (setProcessMode(3L) becomes setProcessMode(Node.ProcessMode.ALWAYS)),
a == 0L error check, or a List<Long> settings table compared with the stored
numbers; those show up as compile errors.
Script annotations and export hints¶
One annotation per concept¶
The aliases are removed with no deprecation period. Each leftover is kept as a tombstone annotation that fails to compile with a message naming its replacement, and the KSP processor reports it at its declaration.
| Removed | Use |
|---|---|
@RegisterFunction, @Method |
nothing: public functions are registered automatically; @GodotName("...") for another Godot name |
@ScriptProperty, @RegisterProperty |
@Export (name, usage) |
@ClassName |
@GlobalClass |
@ToolButton |
@ExportToolButton |
@Ready, @EnterTree, @ExitTree |
@OnReady, @OnEnterTree, @OnExitTree |
@Process, @PhysicsProcess |
@OnProcess, @OnPhysicsProcess |
@Input, @UnhandledInput, @ShortcutInput, @UnhandledKeyInput |
@OnInput, @OnUnhandledInput, @OnShortcutInput, @OnUnhandledKeyInput |
// 0.4
@ScriptClass(attachTo = "Node2D")
@ClassName
class Player(godotObject: GodotHandle) : KanamaScript<Node2D>(godotObject, ::Node2D) {
@Ready fun ready() { }
@Process fun process(delta: Double) { }
@RegisterFunction(name = "_on_start_pressed") fun onStartPressed() { }
@Input fun input(event: GodotObject) { val e = InputEvent(event.handle) }
}
// 0.5
@ScriptClass(attachTo = "Node2D")
@GlobalClass
class Player(godotObject: GodotHandle) : KanamaScript<Node2D>(godotObject, ::Node2D) {
@OnReady fun ready() { }
@OnProcess fun process(delta: Double) { }
@GodotName("_on_start_pressed") fun onStartPressed() { }
@OnInput fun input(event: InputEvent) { val e = event }
}
Public functions are registered automatically¶
Every public function of a script class is registered with Godot under its
snake_case name (fun showMessage() is show_message), as GDScript exposes
every func; @RegisterClass types follow the same rule. private,
protected and internal functions stay Kotlin-only, and so do suspend,
extension and generic functions and an override of a non-script member such as
toString(). Keep a name a .tscn connection saved with @GodotName. New
build errors, each naming the fix:
- a public function whose parameter or return type Godot cannot carry: make it
internalorprivate; - a public function whose snake_case name is an engine method of the attached
class (
fun queueFree()would shadowqueue_free): rename it, make it Kotlin-only, or confirm with@GodotName("queue_free"); - a
varargpublic function, an empty@GodotName(""), two functions on one Godot name (on a@RegisterClass, including theget_x/set_xaccessors of@Export var x); - a Kanama annotation on a non-public function (it used to be ignored silently);
- a function named like an engine virtual without an annotation
(
fun _process(delta: Double)never ran; the error names@OnProcessor@OverrideVirtual); - an input handler still taking
GodotObject.
Input handlers take InputEvent¶
@OnInput, @OnUnhandledInput, @OnShortcutInput and @OnUnhandledKeyInput
functions are fun input(event: InputEvent) on every platform, so the
InputEvent(event.handle) rewrap goes.
Typed export hints¶
@Export loses its hint and hintString parameters (@Export(name, usage)
remains). Each GDScript @export_* annotation has a typed twin that exports the
property by itself and builds the hint string the way GDScript does:
| 0.4 | 0.5 |
|---|---|
@ScriptProperty(hint = PropertyHint.RANGE, hintString = "0,100,1") |
@ExportRange(0.0, 100.0, 1.0) |
@ScriptProperty(hint = PropertyHint.RANGE, hintString = "0,1,0.01,or_greater") |
@ExportRange(0.0, 1.0, 0.01, orGreater = true) |
@ScriptProperty(hint = PropertyHint.ENUM, hintString = "A,B") |
@ExportEnum("A", "B") |
@ScriptProperty(hint = PropertyHint.FILE, hintString = "*.png") |
@ExportFile("*.png") |
@ScriptProperty(hint = PropertyHint.MULTILINE_TEXT) |
@ExportMultiline |
@ScriptProperty(name = "x", hint = <other>, hintString = "s") |
@Export(name = "x") @ExportCustom(<other>, "s") |
A range hint string now reads like GDScript's ("0.0,100.0,1.0" where the old
raw string was "0,100,1"); the inspector behaves the same. @Export next to a
typed hint sets only name and usage. The full set also has @ExportFlags,
@ExportDir, @ExportGlobalFile, @ExportGlobalDir, @ExportPlaceholder,
@ExportExpEasing, @ExportNodePath, @ExportStorage, @ExportColorNoAlpha
and the 2D/3D render, physics and navigation flag variants; see
Export Hints.
Inheritance and generated autoloads (behaviour change)¶
A script class that extends another class of the same build now has all of the
base's members: exports, signals, lifecycle handlers, @OverrideVirtuals and
registered functions, with no forwarding overrides. The most derived declaration
is the one Godot calls; two functions of the chain on one Godot name are build
errors. Before, a subclass registered only its own declarations, and an
unannotated override fun ready() registered a public method ready. The
processor also generates net.multigesture.kanama.generated.Autoloads from the
[autoload] section of project.godot (see
Autoloads).
Script: python3 scripts/migrate_script_annotations.py <kotlin-src> renames the
removed annotations and their imports, deletes @RegisterFunction / @Method
(a custom name becomes @GodotName), retypes input handlers and drops their
rewraps, then lists what needs a human. With --report-registered it also lists
each public function that was not registered before and now is (mark it
internal or private to keep it Kotlin-only).
python3 scripts/migrate_export_hints.py <kotlin-src> rewrites the hint
parameters to the typed annotations (a hint string it cannot parse is kept as
@ExportCustom). Run the annotation script first.
Ownership and close()¶
close() means "release my reference", and 0.5 makes the rule the same
everywhere. See Resource Ownership.
- A forgotten
close()is a late release, not a leak. An ownedRefCountedwrapper you never close is released on the main thread at the next frame after the garbage collector drops it, for wrappers made on any thread, on desktop, Android and iOS, and on Web through the browser's collector.close()anduse { }still release at once. Close big resources (meshes, textures, audio) and anything you make in a loop yourself: native memory is invisible to the collector.kanama/debug/log_gc_releaseslogs each collector release with the creation site. @ManualGodotLifetimeApiis deprecated and no longer applied.close()carried aRequiresOptInwarning in 0.4. Delete@OptIn(ManualGodotLifetimeApi::class); it still compiles with a deprecation warning, and nothing replaces it.- Getters are owned. Every
RefCounted-typed return, plain getters and theTweeneratweenProperty(...)returns included, is a reference you mayclose(); so is eachRefCountedelement of a returned typedArray, and thefrom*downcasts and checked casts to aRefCountedclass (res.cast<Texture2D>()) take a reference of their own. A wrapper you mint yourself over a handle (fromHandle, a wrapper constructor) is a borrowed view:close()on it releases nothing (debug builds warn); before, it released a reference the view never took. - A script object keeps its resource alive, as in GDScript: holding the Kotlin object of a resource script keeps the resource alive after the wrapper it came from is closed or collected.
- A script property's references belong to its resource or node, not to the Kotlin object.
- Elements of an
Object.callcontainer result are owned.node.call(...)(andcallv,callDeferred,GodotCallable.call) returning anArrayorDictionaryofRefCountedobjects hands back owning wrappers; close them or let the collector release them. Elements of acall()made off the main thread get no collector fallback: close them yourself. - Wrappers made off the main thread register the same fallback; see Threads.
- Open files. A file closes when its last reference goes, so
use { }everyFileAccess(see FileAccess and DirAccess).
Script: none. use { } and close() are unchanged; you only gain permission to
forget one.
Signals, callables and await¶
Typed engine signals are an addition, but the supporting changes touch existing code:
GodotObject.connect(signal, target, method, flags)takesGodotObject.ConnectFlagsand returnsGodotError, andSignalConnection.erroris aGodotError(see Enums).- Every engine signal is a typed property:
area.bodyEntered.connect { body -> ... }inside aKanamaScriptbinds the lambda to the script's object, as a GDScript lambda is bound to its script;connect(flags) { }takesGodotObject.ConnectFlags.ONE_SHOT/DEFERRED;await()suspends insidelaunch { }. Declared@Signals get typed handles too. See Signals and Callbacks. - The untyped
connect(target, argumentCount) { args -> }no longer rejects more than three arguments. - A
StringNameread through the generic decode (call,get, an untyped signal lambda'sList<Any?>) is its text, notnull. GodotCallable(call, callv, callDeferred, isValid, getObject, getArgumentCount, rpc, rpcId) andGodotSignal.isConnected/getConnections/hasConnectionsexist on every platform, Web included.- Hot reload (desktop): a lambda connection belongs to the build that made it.
Once that build's last script object is freed, every lambda connection it made
is disconnected on the next frame, with one warning, even when its target
outlived the script (the scene tree, a GDScript autoload). Make lambda
connections in
_ready, so the new build's objects connect again with the new code. By-name connections are Godot's and survive a reload. See Hot reload.
Script: none; migrate_enum_constants.py rewrites the CONNECT_* constants, and
the == 0L result checks are by hand.
Web¶
Web is the area that changed most toward the other platforms. Rebuild and re-export every Web game (bridge protocol 39 ). See the Web export guide.
A 0.4.0 Web project used the preview API. 0.4.0 shipped Web as a two-demo
preview (a small set of hand-written wrappers): it had no GodotObject.set,
call or callDeferred, no Basis, no GD.print, and a Mathf with only abs
and log. Most of what follows describes the change from builds of main
between 0.4 and 0.5, where Web had grown those members. If your Web code is
still the 0.4.0 preview, follow the compiler and the
enum script: for example GodotObject.CONNECT_ONE_SHOT
becomes GodotObject.ConnectFlags.ONE_SHOT, GodotSignal.connect returns a
GodotError (it returned Long), and InputEventMouseButton.getButtonIndex()
returns a MouseButton (it returned Long).
// builds of main between 0.4 and 0.5 (Web)
import net.multigesture.kanama.api.call // top-level extension
node.set("position:x", 5.0)
node.call("play", "walk") // queued, returned Unit
val col = basis.getColumn(0)
val b = Basis.fromAxisAngle(Vector3.UP, angle)
GD.print("hello")
val d = Mathf.pow(value = 2.0, exponent = 3.0)
// 0.5 (Web, as on desktop)
node.setIndexed("position:x", 5.0) // set(...) is Object.set: a path changes nothing
node.call("play", "walk") // immediate, returns the result (Any?); no import
val col = basis.x
val b = Basis.IDENTITY.rotated(Vector3.UP, angle)
GD.print("hello") // GD.print(vararg values)
val d = Mathf.pow(x = 2.0, y = 3.0)
The notes below are written against those main builds.
GodotObject.setisObject.setas on desktop. A property path such as"position:x"names no property and changes nothing;setIndexed(path, value)is the path form.set(property: String, value: Any?)replaces the typed overloads forDouble,Long,String,Vector2andGodotEnumValue, so a call that names the first argument writesproperty =. A name without a:writes the same property as before.call/callDeferred. The typed overloads (call(method, String),call(method, Vector3, Vector3),callDeferred(method, GodotObject), ...) and the top-levelGodotObject.call/callDeferredextensions are removed. The Variantcall(method, vararg args): Any?andcallDeferred(method, vararg args): Any?take those calls and run immediately, as on desktop.GD,Mathf,GodotCallableare the shared classes.GDhas all 114 utility functions,Mathf.isEqualApproxuses Godot's tolerance instead of1e-6, and the Web-only spellings sources import by name (net.multigesture.kanama.api.radToDeg,randf,randi,randomize,pushError,Basis) are kept.- Value types are the shared classes (0.4.0's preview had only
Vector2,Vector2i,Rect2and aFloatColor):Basis.getColumn(i)andBasis.fromAxisAngleare gone, and parameter names follow desktop (Basis(x, y, z),withX(value),lookingAt(target, up, useModelFront),interpolateWith(xform, weight),withBasis(value),bounce(n),times(scale)).Vector4,Vector4i,AABB,Transform2DandProjectionnow exist on Web. - Wrappers follow Godot's argument names and
int32asInt, as on desktop. A call that passed aLongwhere Godot has anint32needs.toInt(). The import-compat extensions keepimport net.multigesture.kanama.api.setProcessstyle imports resolving. Windowis a generatedViewportsubclass,Node.getWindow()returns the root window (null outside the tree), andSceneTree.getRoot()returnsWindow.- Ownership and lifetime now follow desktop (see Silent changes):
a second
close()does nothing,close()ends only that wrapper's reference, andResourceLoader.loadThreadedGetremoves the finished load. KanamaScript.selfis public. Layer and collision masks take all 32 bits.- Ray queries and RIDs take desktop's API. A
RIDis the same value class as on desktop (body.getRid()), the query'sexcludeis aList<RID>,getWorld3d()anddirectSpaceStateare nullable, andintersectRayanswers desktop'sMap(empty on a miss) instead of aRayHit?:
// builds of main between 0.4 and 0.5 (Web)
val query = PhysicsRayQueryParameters3D.create(from, to, 0xffffffffL, listOf(self))!!
val hit = self.getWorld3d().directSpaceState.intersectRay(query)
if (hit != null) target = hit.position
springArm.addExcludedObject(body)
// 0.5 (Web, as on desktop)
val query = PhysicsRayQueryParameters3D.create(from, to, 0xffffffffL, listOf(self.getRid()))!!
val hit = self.getWorld3d()?.directSpaceState?.intersectRay(query) ?: emptyMap()
if (hit.isNotEmpty()) target = hit["position"] as Vector3
springArm.addExcludedObject(body.getRid())
A ray is still one engine crossing on Web. RayCast3D.addExceptionRid,
getColliderRid and the query flags (collideWithAreas, hitFromInside, ...)
are new there.
- Texture2D.close() and friends come from RefCounted (nothing to migrate).
Script: none; the compiler lists the sites. The enum script's rewrites apply to Web sources too.
iOS¶
- iOS exports from the macOS release kit or the store addon. Run
./gradlew buildIosScriptsin the project on a Mac, then export from Godot; a source checkout is no longer needed. See Export for iOS. The runtime-onlykanama-mobile-addon-ioszip is gone. - Exports require iOS 15.0, Godot 4.7.2's default
application/min_ios_version(Xcode 27 refuses a lower deployment target). Set it in your export preset. - A
Mapwith non-String keys no longer converts to a generic GodotDictionaryon iOS. A script method returning aMap<Int, V>(or aListholding one), or aMapargument with such keys tocall/callv/set, used to reach Godot with the keys turned into Strings ("1"); it now fails withUnsupported Dictionary key type: <class>, as on desktop. Return aMap<String, V>, or declare the property as a typed@ExportMap<K, V>, which keeps its keys. - A script method iOS cannot dispatch now fails the iOS build instead of
warning and silently never running: a registered function or virtual with a
parameter type the iOS call path does not pass (
Map,List,Packed*Array), an@OverrideVirtualwhose return type iOS does not marshal, or an exported property iOS cannot deliver (aRID;Mapexports are delivered). The error names the method, the parameter and the supported types; change the type, or build with-PkanamaIosAllowSkips=trueto accept the skip (a warning again).RIDandAny?parameters, andNodePathand every value type as an@OverrideVirtualreturn, are dispatched now. - Removed, replaced or retyped on iOS (compile errors):
GodotObject(handle: Long)is gone, useGodotObject.fromHandle(handle)or aGodotHandle; theemitSignal(name, Int | Long | Vector2i): Intoverloads are gone,emitSignal(name, vararg args)returnsUnit;connect/disconnectname the parametersignal(wassignalName);connectBound/disconnectBoundare internal;RefCounted's constructor is internal;GodotObjectis no longerAutoCloseable(0.4.0 iOS had a no-opclose()), soclose()oruse { }on a wrapper that is not aRefCountedno longer compiles (like desktop:RefCountedstill ownsclose()); building aGodotObjectover a NULL handle now throws instead of yielding a wrapper withinstanceId == 0; see also the iOS items under Kotlin API surface. toString()is an engine call on iOS (Object.to_string,<Node2D#123>), as on desktop. Calling it on a wrapper whose object was freed (a string template, a log line) dereferences a dangling pointer: checkinstanceId/GD.isInstanceValidfirst.GD.printand the other print functions write to Godot's logger, not stdout. On a device that is the system log; read it in Xcode's console or Console.app.GD.seed(n)reproduces GDScript's sequence on the phone.- Script errors name the Kotlin file and line in debug builds
(
at: Player.ready (res://kotlin-src/Player.kt:42)) when the app keeps its symbol table: build Godot's exported Xcode project. Godot's.ipaexport and one-click deploy strip the app, so there a report names the callback with line 0. System.getenvreads the process environment (it returnednull).- iOS gained the full
Tween,FileAccess,DirAccess,Engine,ProjectSettings,ResourceLoader,AudioStreamPlayerandGD; see Kotlin API surface.SceneTree.delaySecondswaits in engine frames (pause and time scale apply).Mathf.clampno longer throws whenmin > max. - The runtime self-tests no longer run or ship in users' builds: they compile in
only with
-PkanamaIosSelfTest=true.
Script: none.
Android¶
- The Android runtime uses PanamaPort
0.1.5-kanama-r8.1(it was0.1.3-kanama-r8.4), rebased for the Android 17 September update (apps built on the old fork aborted at startup on that update). The coordinate is the default of-PkanamaPanamaPortCore; nothing to change unless you pinned the old one. - The class-token tables behind
castOrNull,requireAsandnode<T>()keep every wrapper class's constructor reachable, so R8 can no longer drop unused wrapper classes: expect a larger minified release build. - Android exports from a release kit or the store addon. Run
./gradlew buildAndroidScriptsin the project, then export from Godot; a source checkout is no longer needed. See Export for Android. - Android 13 is now the minimum, for debug and release builds. Set Min
SDK to
33under Gradle Build in your Android export preset; an export with a lower or empty Min SDK stops with a message that says so.
Script: none.
Tooling, Gradle and the editor¶
- JDK. The build pins
jvmToolchain(25). The release-kitsettings.gradle.ktsnow applies the foojay toolchain resolver, so a machine with only another JDK downloads JDK 25 once; add the sameplugins { id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0" }block to your ownsettings.gradle.ktsif you copied one. The editor picks the JDK itself (thekanama/build/jdk_patheditor setting, thenJAVA_HOME, then the usual install locations), and aJAVA_HOMEolder than 25 is skipped. See JDK Selection. addons/kanama/kanama.versionnames the addon's Kanama version. The Gradle build takes the Kanama libraries and the Kanama Gradle plugin from it,buildScriptsstampskanama-scripts.jarwith it, and the editor offers Sync Addon when your scripts were built for another version.addons/kanama/kanama-project.gradle.ktsgains the KSP inputs that makeAutoloadsregenerate whenproject.godotchanges. It ships inside the addon, so the new addon brings it; a copy you edited by hand needs the same block.- Export guard. The Kanama Tools plugin checks, when an export begins, that
every
.ktscript the exported scenes attach is bound. When one is not, it printsKanama: Export stopped:with the script, the reason and the fix, and a command-line export ends the editor process with a non-zero exit status. Opt out withkanama/tools/export_guard_enabled. - Build on save is on, and is an editor setting. The Kanama Tools plugin builds
your scripts when you save a
.ktfile, and a status light in its toolbar row shows the result. Turn it off in Editor > Editor Settings > Kanama > Build > Build On Save (kanama/build/build_on_save). The project settingkanama/tools/auto_build_on_saveis no longer read; delete its line fromproject.godot. See Edit, Build, Run. - JVM options for desktop games:
kanama-jvm-options.txtnext tokanama.jar, thekanama/jvm/optionsproject setting, andKANAMA_JVM_OPTIONS. See Export for Desktop → JVM Options. - Source checkout and contributors. Kanama is one Kotlin Multiplatform module;
:ios-runtimeno longer exists. Task names:compileKotliniscompileKotlinJvm,testisjvmTest,jarisjvmJar,kspKotliniskspKotlinJvm, and every:ios-runtime:XisX(linkDebugStaticIosArm64, ...).installAddonJar,syncExampleAddonJar,publishKanamaToMavenLocal, thepackage*tasks, the xcframework tasks andktfmtCheck/ktfmtFormatkeep their names. Sources moved:src/main/kotlintosrc/jvmMain/kotlin,src/testtosrc/jvmTest, andios-runtime/src/iosMain/kotlintosrc/iosMain/kotlin. The Godot API wrapper tree is common code insrc/commonMain/kotlin/net/multigesture/kanama/api. - Documentation moved (no redirects):
contributing/android-internals.mdiscontributing/backends/android.md,web-internals.mdiscontributing/backends/web.md, the iOS backend page iscontributing/backends/ios.md, and the generated reports (api-coverage,wrapper-generator-report,gates,ios-backend-handwritten) are underreference/generated/.
Script: none.
Silent changes to check¶
These compile and still change results. Check each against your project.
Properties and values
- A property set to a value of the wrong type is refused. A script property of
type
Boolean,Long,Double,String,NodePath, a vector or value type,Color,List<T>orMap<K, V>that received a Variant of another type (null, aVector2for aVector3, ...) used to becomefalse,0,"", the zero vector or an empty collection. Now Godot's conversion rules apply (anintfor afloat, aVector2ifor aVector2, ... are converted) and anything else fails withExpected Vector3 for property 'velocity' but the Variant holds Vector2, naming the property, and the property keeps its value. A registered function's argument of a value type (Quaternion,Basis,Rect2,Transform3D, ...) that received a Variant of another type fails the call with the same message instead of becoming zero or identity. On iOS the same rule covers only the value-type andNodePathproperties, where it replaces a bareClassCastException(or a droppednull);Boolean,Long,Double,String,ListandMapproperties are unchanged on iOS. GD.clamp(value, min, max)withmin > maxmatches GDScript:valueis set tominif it is less, then tomaxif it is greater, soGD.clamp(0.0, 3.0, 1.0)is1.0. 0.4.0 had noGD.clamp(onlyclampfandclampi, andMathf.clampon top of them), and those gave3.0; builds ofmainbetween 0.4 and 0.5 had aGD.clampthat did too.clampfandclampikeep Godot's typed result.- Value types print and compare like Godot.
toString()is GDScript'sstr(v)((0.1, 0.2), notVector2(x=0.1, y=0.2));==compares the stored components; basic arithmetic gives Godot's results bit for bit. Quaternion.inverse()on desktop and Android is the engine's (the conjugate), where the old local body divided by the squared length and returnedIDENTITYfor a zero quaternion. Unit quaternions agree.- Range hint strings read
"0.0,100.0,1.0", as GDScript's do; the inspector behaves the same. StringNamevalues in generic decodes arrive as text, notnull(desktop, Android, iOS). On iOS, script properties now report their initializer as the default value, so a scene packed at runtime stores only what differs.- Typed resource loaders check the class.
ResourceLoader.loadTexture2D,loadPackedScene,loadAudioStream,loadLightmapGIDataandloadThreadedGetPackedScenereturnnulland callpushError('path' is a Texture2D, not a PackedScene) when the resource is of another class; they used to wrap it as the requested type. On iOSloadThreadedGetnow really calls Godot'sload_threaded_get: it consumes the load, and returnsnullwith an error when nothing was requested for the path.loadThreadedGetStatusWithProgressfails loudly when Godot returns no progress value instead of reporting 0 (desktop throwsIllegalStateException, iOS reportsINVALID_RESOURCE).
Random numbers and math (Web)
GD.randf,randi,randiRange,randfRange,randfn,seed,randomizeandrandFromSeeduse Godot's global generator on every platform, soGD.seed(n)reproduces GDScript's sequence everywhere. Web's own generator is gone. Each draw is one bridge call.Mathf.inverseLerp(a, a, x)answers Godot's NaN or infinity (Web answered 0), andMathf.roundToIntrounds halves away from zero (Web rounded to even); both compare builds ofmainbetween 0.4 and 0.5, since 0.4.0's WebMathfhad onlyabsandlog.GD.randiRange/randfRangeno longer throw forfrom > to(they did in 0.4.0).
Ownership and lifetime
- Two wrappers of one object are equal on desktop, Android and iOS.
equalsandhashCode(nowfinal) compare the instance id, whatever the wrapper class (NodevsNode3D), sonode == otheristrue, andList.contains,SetandMapkeys treat them as one. 0.4.0's desktopGodotObjecthad noequals, so two wrappers were two keys. Check anySet<Node>,Map<Node, ...>orindexOfyou relied on being identity-based. - A call through a freed wrapper throws on desktop, Android and iOS, in debug
builds (the editor and debug exports):
IllegalStateException: Invalid access to previously freed instance (Node3D, instance id ...), contained and reported like any script error. Before, the call read freed memory (wrong values, or a native crash). Comparing such a wrapper,GD.isInstanceValidandtoString()stay silent, and a release export does not check, so keepGD.isInstanceValid(node)before using an object that may be gone. The Web rule is the next bullet. - Web: a node or plain object you hold is valid until the engine frees it,
whichever script got it, and a node you
queueFree()stays usable to the end of the frame. A handler argument can be kept (lastHit = body) andbody == playeristruefor the same node. Using an object the engine freed throwsIllegalStateException: Invalid access to previously freed instancefor every call that returns a value (before, a bridge message), and a call that returns nothing is skipped and reported once as the same script error. A secondclose()does nothing (it threw "Unknown or already released");close()ends only that wrapper's reference;ResourceLoader.loadThreadedGetremoves the finished load (a laterloadThreadedGetStatusanswersINVALID_RESOURCE, it stayedLOADED). At most 4096RefCountedarguments that only Kotlin holds stay alive on Web; copy the values you need instead of keeping thousands of events. - Web script exceptions are reported once through Godot's error log
(
SCRIPT ERROR: <type>: <message>,at: <Script>.<callback>) and contained: the call returns its default and the game goes on. Before, an exception ended the page with a failure banner. Only an exception thrown by your code is contained. - Desktop and Android: a
@RegisterClassmethod returning aRefCountedhands Godot a reference of its own; before, GDScript dropping the result could destroy a resource the Kotlin object still held. - iOS: setting a
Nodeinto a script property no longer corrupts it, and a no-arg getter returning aStringor an array no longer runs the Godot method twice (FileAccess.getLine()skipped every other line). DirAccessandFileAccesswrites stay unflushed until the file is closed (see FileAccess and DirAccess).
Scripts and signals
- A Kotlin exception is a Godot script error on desktop, Android and iOS
(Web: see "Web script exceptions" above). It is reported as
SCRIPT ERROR: <type>: <message>withat: Player.ready (res://kotlin-src/.../Player.kt:42), as GDScript reports a runtime error, and it shows in the editor's Errors tab. The failed call returnsnullwithCALL_OK(it wasINVALID_METHOD, so Godot also added a misleading "method not found"): a caller that tested for that error now gets a normalnullresult. On iOS the exception is contained; it used to cross the native boundary and end the app. - Public functions are registered and subclasses inherit the base's members (see Script annotations); a public helper that was Kotlin-only is now callable from GDScript, and the build fails when Godot cannot carry its types.
- Lambda connections do not survive a hot reload when their script's build is retired (see Signals).
- Web: a
@Signalor engine signal delivers every argument, not one, and anawait()is cancelled when the emitter is freed first (it never resumed).
Build and export
- iOS script builds fail for a method the platform cannot dispatch, and an
export fails when a
.ktscript does not bind (the export guard). A command-line export ends non-zero and writes no artifact; an export from the Export dialog is only marked Failed and its files stay written as Godot wrote them. - A failing headless export of a project without
.godot/exits 1, not 134 (an unknown preset, an unwritable folder, an export plugin that stops the export), as a GDScript project does. A CI step that expected 134 needs 1. A project that does not enable the Kanama Tools plugin can still crash this way. - R8-minified Android builds are larger (see Android).
- An export built with an older Web protocol refuses to run: re-export.
Godot 4.8¶
Kanama 0.5 moves from Godot 4.7.2 to Godot 4.8. Open your project in the 4.8 editor, let it re-import, and install the 4.8 export templates.
- Android: replace the build template. Godot 4.8 refuses an Android export
whose
res://android/buildcame from another Godot version ("Unable to set up Android build directory"). Deleteres://android/buildand let Godot install it again. Avoid Editor Settings > Export > Android > Build > Automatically Delete Build Directory for this: it deletes everything inres://android, Kanama's Android plugin inres://android/pluginstoo. If it already did, run./gradlew buildAndroidScriptsagain before you export. - Rebuild your scripts after updating Kanama. Where Godot 4.8 added a
parameter with a default at the end of a method (
DisplayServer.getDisplaySafeArea,Skeleton3D.resetBonePose,Skeleton3D.resetBonePoses), your calls compile unchanged, but the compiled method is a different one. A scripts jar built against the older Kanama still calls the old method and fails withNoSuchMethodErroron desktop and Android. The normal build rebuilds it. - Android: R8 has a preset option now. Gradle Build > Minification turns it on; see Release Builds.
- Methods Godot changed:
Image.compressandImage.compressFromChannelstakeprofile: Image.CompressProfileinstead ofastcFormat:ASTC_4x4isImage.CompressProfile.MAX_QUALITY,ASTC_8x8isImage.CompressProfile.MAX_COMPRESSION.DisplayServer.orientationChangedemits aDisplayServer.SensorOrientationinstead of aLong.GDScriptTextDocument.codeLens,colorPresentationandfoldingRangeand theirMethodNameconstants are gone, and so isPropertyName.triangles.ScriptEditorextendsEditorDock, notPanelContainer.
- GDScript cannot extend a Kanama class. It never could. Godot 4.8 says so
when it analyzes the script:
Global class X is not a GDScript.See Limitations.
Checklist: every announced source break¶
The 0.5 changelog announces each source break with a - **Source break:** line
under ## Unreleased. The table maps each of those lines, in changelog order, to
the section of this page that covers it. Entries before the marker gate existed carry
no marker lines; their breaks are covered in the sections named in the second
table.
| # | Changelog entry | Owner named by the marker | Guide section |
|---|---|---|---|
| 1 | Web ray queries and RIDs use desktop's API | Web RayHit, PhysicsDirectSpaceState3D, PhysicsRayQueryParameters3D, World3D, SpringArm3D, top-level |
Web |
| 2 | Web set("position:x", ...) does what it does on desktop: nothing |
GodotObject.set (Web) |
Web |
| 3 | Web: a RefCounted lives while Kotlin holds it, and every RefCounted has close() |
Web Texture2D, AudioStream, PackedScene, ... close() |
Changes that need no edit |
| 4 | iOS: a lambda connection's closure lives as long as any Callable of it | top-level kanamaIosRuntimeReleaseCallable |
Changes that need no edit |
| 5 | GodotObject.set returns Unit |
GodotObject.set |
Node, SceneTree, Viewport and Resource |
| 6 | Web compiles the shared GD, Mathf and GodotCallable |
GD, Mathf (Web) |
Web |
| 7 | Web compiles the shared GD, Mathf and GodotCallable |
GodotObject and top-level call / callDeferred (Web) |
Web |
| 8 | FileAccess and DirAccess are RefCounted classes |
FileAccessHandle, DirAccessHandle |
FileAccess and DirAccess |
| 9 | FileAccess and DirAccess are RefCounted classes |
the 38 FileAccess path helpers |
FileAccess and DirAccess |
| 10 | FileAccess and DirAccess are RefCounted classes |
the 23 DirAccess per-call helpers |
FileAccess and DirAccess |
| 11 | FileAccess and DirAccess are RefCounted classes |
generated FileAccess / DirAccess signatures |
FileAccess and DirAccess |
| 12 | FileAccess and DirAccess are RefCounted classes |
iOS ShapeCast3D.getCollisionPoint, PhysicsRayQueryParameters3D.create |
Engine, BoxMesh, ... generated once |
| 13 | FileAccess and DirAccess are RefCounted classes |
top-level kotlinScriptInstance<T>() |
Changes that need no edit (a call on a node compiles unchanged) |
| 14 | 20 more per-platform classes generated once | Engine |
Engine, BoxMesh, ... generated once |
| 15 | 20 more per-platform classes generated once | BoxMesh, AudioStreamPlayer |
Engine, BoxMesh, ... generated once |
| 16 | 20 more per-platform classes generated once | ResourceLoader |
Engine, BoxMesh, ... generated once |
| 17 | 20 more per-platform classes generated once | ShaderMaterial, ParticleProcessMaterial, ProceduralSkyMaterial (iOS) |
Engine, BoxMesh, ... generated once |
| 18 | 20 more per-platform classes generated once | NoiseTexture2D, ProjectSettings, SurfaceTool (iOS) |
Engine, BoxMesh, ... generated once |
| 19 | iOS: no silent method skips; script errors name the Kotlin line | iOS builds | iOS |
| 20 | GD generated once, Mathf written once |
GD |
GD and Mathf |
| 21 | GD generated once, Mathf written once |
Mathf (iOS) |
GD and Mathf |
| 22 | Tween and InputEventMouseButton generated once |
InputEventMouseButton |
InputEventMouseButton |
| 23 | Tween and InputEventMouseButton generated once |
top-level createTween, getProcessedTweens, setExclude |
Tween and tweeners |
| 24 | Tween and InputEventMouseButton generated once |
Tween |
Tween and tweeners |
| 25 | Web parity for signals and value types | Basis, Transform3D, Vector2, Vector3 (Web) |
Web |
| 26 | Typed engine signals | TypedSignal, Signal0 ... Signal5, Area2D, ... |
Changes that need no edit |
| 27 | StringName values decoded as nil | top-level kanamaIosRuntimeDispatchCallable |
Changes that need no edit |
| 28 | Typed export hints, generated autoloads, script inheritance | Export |
Script annotations and export hints |
| 29 | Typed export hints, generated autoloads, script inheritance | KanamaScript.self (Web) |
Changes that need no edit |
| 30 | Value-type methods follow Godot exactly | Vector3.maxAxisIndex() |
Decimal values are Double |
| 31 | Value-type methods follow Godot exactly | Vector2, Vector3, Transform3D parameter names |
Decimal values are Double |
| 32 | Removed: KanamaCoroutineOwner |
KanamaCoroutineOwner, KanamaScope |
Coroutines |
| 33 | Removed: KanamaCoroutineOwner |
KanamaScript moved to common code |
Coroutines |
| 34 | Every decimal value is Double |
Vector2, Vector3, Vector4, Quaternion, Plane, Color |
Decimal values are Double |
| 35 | One annotation set, public functions registered automatically, typed input handlers | script annotations and lifecycle input handlers | Script annotations and export hints |
Breaking entries that predate the marker gate (no Source break line, covered
here as well):
| Changelog entry | Guide section |
|---|---|
| Typed Godot enums and required returns (BREAKING) | Enums and bitfields |
| Typed export hints, one annotation set (BREAKING) | Script annotations and export hints |
GodotHandle replaces MemorySegment in every public signature |
The script constructor handle |
Desktop GD.isInstanceValid(Any?) takes GodotObject? |
GD and Mathf |
iOS GodotObject is no longer AutoCloseable |
iOS |
| The roots written once (desktop and iOS source breaks) | Node, SceneTree, Viewport and Resource, iOS |
Node, SceneTree generated once; SceneTreeHandle retired |
Node, SceneTree, Viewport and Resource |
Viewport, Resource, Button, LineEdit, Range, Slider, TabBar, AnimationPlayer generated once |
Node, SceneTree, Viewport and Resource |
The Tweener family is generated once |
Tween and tweeners |
| The API tree is common code (defaults became overloads) | Changes that need no edit |
| Web wrappers generated from the call contract | Web |
One resource-ownership rule; a forgotten close() is a late release |
Ownership and close() |
| iOS exports require iOS 15.0; Godot 4.8 baseline | iOS, The order to do things in |
| Kanama is one Kotlin Multiplatform module; docs pages moved | Tooling, Gradle and the editor |