API Conventions¶
This page lists the rules the Kotlin Godot API follows: how a Godot name, type,
enum or default becomes Kotlin. The classes are in net.multigesture.kanama.api,
such as Node, Input and StandardMaterial3D, and every one of them follows
these rules. Calling Godot APIs is the short
version; this page is the full reference.
The rules cover desktop, Android and iOS, which compile the same API.
Platform Parity lists where Web differs. The annotations
you write scripts with are on Writing Scripts,
including how your own fun showMessage() becomes Godot's show_message.
Kanama is pre-1.0, so a rule can still change when a Godot upgrade or the long-term design of the API needs it. Every change that can stop your code from compiling is listed in the CHANGELOG as a "Source break", with the old and new spelling and how to migrate.
| Area | Rule |
|---|---|
| Names | Godot names, lowerCamel members, Value suffix on keywords |
| Properties | getter + setter = var, getter only = val |
| Integers | int32 meta = Int, other int = Long |
| Decimals | every decimal value Double, value-type and Color components included; packed bulk data keeps 32-bit storage |
| Enums and Bitfields | typed value classes, frozen value names |
| Nullability | meta: "required" returns non-null, other object returns nullable |
| Ownership | close() / use { } releases a RefCounted early; a forgotten one is released after the garbage collector drops it |
| Statics and Singletons | statics on the companion, singletons are objects |
| Defaults and Overloads | Godot defaults where Kotlin can express them |
| Collections | List, Map<String, Any?>, ByteArray |
| Handles and Factories | GodotHandle, fromHandle, create() |
| Names as Constants | X.Signals.<name> |
| Platform Parity | one API for desktop, Android and iOS; Web separate |
The snippets on this page are parts of a script like the one in Writing Scripts, which lists the imports.
1. Names¶
val label = self.getNodeOrNull("Hud/Label") // get_node_or_null
val child = itemScene.instantiateAs<Node>() // itemScene: a preloaded PackedScene
self.addChild(child, internalValue = Node.InternalMode.FRONT) // `internal` is a Kotlin keyword
ENetMultiplayerPeer.create().use { peer ->
peer.closeConnection() // MultiplayerPeer.close()
}
- Classes keep Godot's name. Godot's
ObjectisGodotObject, and global enums are renamed only when Godot's name would collide (see Enums). - Methods are Godot's
snake_caseinlowerCamelCase:get_node_or_nullisgetNodeOrNull. A leading underscore is dropped. A few methods whose Godot name Kanama or Java already uses are renamed: Godot'sclose()becomescloseConnection(),closeArchive()orcloseDock(), becauseclose()releases aRefCounted(see Ownership), andwait()becomeswaitBlocking(), because every Java object already has a finalwait(). - Parameters are
lowerCamelCasetoo. A parameter named like a Kotlin keyword gets the suffixValue: Godot'sinternalisinternalValue. A handful are renamed for readability, such as those of theTimemethods. Parameter names are part of the API, because Kotlin callers can name arguments. - Properties are the Godot property name in
lowerCamelCase. The exceptions pair with renamed accessors:Curve3D.closediscurveClosed(setCurveClosed),OccluderPolygon2D.closedispolygonClosed.
2. Properties¶
self.processMode = Node.ProcessMode.ALWAYS
val material = StandardMaterial3D.create()
material.albedoTexture = preloadedTexture // preloadedTexture: a Texture2D you loaded
val light = self.requireAs<OmniLight3D>("Lamp")
light.lightEnergy = 2.0
A Godot property becomes a Kotlin property when Godot has a getter for it:
- getter and setter of the same Kotlin type:
var; - getter only, or a setter whose type differs from the getter's:
val; - setter only: no property, the setter method alone.
The accessor methods stay callable (getProcessMode() / setProcessMode(...)).
An indexed property, one Godot backs with a shared accessor and an index, is a
property too, with the index bound: BaseMaterial3D.albedoTexture calls
getTexture with the albedo index, Light3D.lightEnergy calls getParam.
3. Integers¶
val n: Int = self.getChildCount()
val id: Long = self.getInstanceId()
val ready: Long = Node.NOTIFICATION_READY // a class constant: const val, Long
Godot's int is Int when Godot declares it as an 8-, 16- or 32-bit value
(meta int8, int16, int32, char32, uint8 or uint16 in Godot's API
description), and Long otherwise: the Kotlin type follows the width Godot
declares, so a value that fits an Int never makes you convert. Under the hood
every scalar integer argument or return crosses to the engine in an 8-byte
cell, whatever its declared width; the components of a Vector2i or Rect2i
and the elements of a PackedInt32Array stay 4 bytes each. Class integer constants that are not enum values are
const val NAME: Long on the companion, under Godot's name.
4. Decimals¶
Every decimal value a script reads or writes is a Double, on every platform,
as in GDScript, where float is 64-bit. That covers float arguments, returns
and properties, and the components of the value types (Vector2, Vector3,
Vector4, Quaternion, Plane, Basis, Transform2D/3D, Rect2, AABB,
Projection) and of Color.
A value type stores its components at Godot's width, exactly as Godot, GDScript
and C# do: 32-bit floats for the vectors, transforms and Color. A constructor
or copy rounds each component to that width, and a property reads it back as
a Double. So Kotlin behaves like GDScript:
node.position = v; node.position == vistrue: the stored value reaches Godot unchanged.==andhashCodecompare the stored values with Godot's==(-0.0 == 0.0;NaNequals itself only, to keep Kotlin'sequalsrules).toString()prints what GDScript'sstr(v)prints:(0.1, 0.2),(1.0, 2.0, 3.0), Quaternion(0, 0, 0, 1), Color(1.0, 0.5, 0.0, 1.0)(at most four decimals), Plane[N: (0.0, 1.0, 0.0), D: 0], Basis and Transform columns[X: …, Y: …, Z: …, O: …].- Arithmetic gives Godot's result bit for bit:
+,-,*,/and unary-are computed on the stored values and rounded to the storage width, and a scalar operand is rounded first, asVector2 * floatdoes in Godot.dot,length,distanceTo,cross,normalized,Quaternion * Quaternion,Basis * Vector3,Transform3D * Vector3, every other operator Godot declares, and the short component-wise methods (abs,floor,round,sign,min/max,clampf,directionTo,Color.toHtml, ...) use Godot's own formulas. Methods the engine computes (lerp,rotated,slerp,angle, ...) return the engine's result.
The same caveat as GDScript applies: v.x = 0.1 stores the 32-bit float
nearest to 0.1, so v.x == 0.1 is false, while v == Vector2(0.1, 0.2) is
true, because both sides are stored. Compare decimals with isEqualApprox.
Values exact in 32 bits (0.5, 1.25, small integers) compare equal either
way.
Integer components construct without boxing, as in GDScript: Vector3(0, 1, 0),
Vector3(speed, 0, 0), Color(1, 1, 1), Color(1, 1, 1, 0.72),
Plane(Vector3.UP, 0). Vector2 and Vector3 accept any mix of Int and
Double, Color adds (Int, Int, Int, Double), and Vector4, Quaternion
and Plane(x, y, z, d) take all-Int or all-Double. The operators take
Int, Long, Double and Float scalars.
Packed bulk data keeps compact 32-bit storage: PackedFloat32Array is
List<Float>, PackedFloat64Array is List<Double>. The elements of
PackedVector2/3/4Array and PackedColorArray, and of mesh arrays, are the
ordinary value types.
Kanama works with Godot's standard single-precision builds only; see Limitations.
Operators, Methods and Edge Cases¶
- Operators are Kotlin operators with GDScript's meaning:
a + b,v * 2.0,2.0 * v,-v,transform * point,basis * otherBasis,quaternion * vector,Vector2i(3, 4) * 2,Vector2i(3, 4) * 0.5(aVector2, as in GDScript),color * 0.5,transform * points(aList<Vector3>), and</>on vectors, component by component, as Godot compares.point * transformis Godot's inverse transform.2.0 * vandpoints * transformneedimport net.multigesture.kanama.types.times, which the IDE offers, ornet.multigesture.kanama.types.*. - Methods are camelCase (
v.directionTo(target),v.snapped(step),basis.getEuler(),Projection.createPerspective(...),Color.fromHsv(h, s, v));aabb.intersectsRay(from, dir)isnullwhere GDScript returnsnull. Getters keepget(rect.getCenter(),transform.getRotation()), exceptTransform2D.get_origin(), which is theoriginproperty. Constants are the ones Godot declares (Vector2i.LEFT,Vector3.MODEL_FRONT,Basis.FLIP_X,Plane.PLANE_XY,Vector3.INF, every named color), and the enums are nested (Vector3.Axis.X). - Speed. Operators and every method that is plain arithmetic in Godot
(
abs,floor,round,min/max,clampf,lerp,moveToward,slide/bounce/reflect,project,limitLength,Rect2/Rect2i/AABBhasPoint/intersects/encloses/merge/grow*,Plane.project,Transform2D.inverse/translated,Color.lerp, ...) run in Kotlin and cost no engine call. Every other method (angle,rotated,slerp,Basis.getEuler,Color.lightened, ...) is computed by the engine, about as fast as the same call from GDScript.
Differences from GDScript¶
- Integer division or
%by zero (Vector2i(1, 1) / 0) throwsArithmeticException; GDScript reports a division-by-zero error. - Godot's debug build checks some arguments and returns a default instead of
computing:
slide,bounceandreflectwith a non-normalized normal, andquaternion * vectorandvector * quaternionwith a non-normalized quaternion. Kotlin computes the formula without the check, which is what an exported release game does. Engine-computed methods (slerp,rotated, ...) report the same error as GDScript, and so doBasis.inverseof a singular basis,Basis.getRotationQuaternionof a basis that is not a rotation andTransform3D.affineInverseof a singular one. - Comparing vectors with a NaN component: Godot answers
falseto all of<,<=,>and>=. Kotlin sorts a NaN component last, so<and<=arefalsebut>and>=aretrue. - A float that becomes an integer, such as
Color.toHtmlon a channel of NaN, ±INF or beyond theintrange: Godot's result differs by CPU, x86 or arm64. Kotlin gives 0 for NaN and clamps out-of-range values, which matches Godot on arm64 (Apple silicon, phones). For finite channels every platform agrees.
5. Enums and Bitfields¶
self.setProcessMode(Node.ProcessMode.ALWAYS)
val flags = Control.SizeFlags.EXPAND or Control.SizeFlags.FILL
if (Control.SizeFlags.FILL in flags) { /* ... */ }
val scene = PackedScene.create()
val err: GodotError = ResourceSaver.save(scene, "user://level.tscn")
self.set("process_mode", Node.ProcessMode.ALWAYS) // dynamic call: typed value accepted
Every Godot enum and bitfield is a Kotlin value class wrapping the Long Godot
uses, and every parameter, return and property Godot types with that enum uses
it.
- Placement. A class enum nests in its class (
Node.ProcessMode,BaseMaterial3D.Flags); a global (@GlobalScope) enum is top-level (Key,MouseButton). A global enum is renamed only when Godot's name would collide:ErrorisGodotError,PropertyHintisGodotPropertyHint, andVariant.Type/Variant.OperatorareVariantType/VariantOperator. - Value names drop the enum's common prefix and keep Godot's
SCREAMING_CASE, the rule Godot's C# bindings use:
PROCESS_MODE_ALWAYSisNode.ProcessMode.ALWAYS. A value that would start with a digit keeps a word (Key.KEY_0); an enum without a common prefix keeps full names (GodotError.ERR_FILE_NOT_FOUND). - Frozen names. Each enum's prefix is fixed. A value a later Godot adds that does not fit the prefix keeps its full Godot name, and the existing names do not change.
- Raw values.
.valueis theLong, and the public constructor builds any value, including one Kanama does not name, such as a value a newer Godot adds:Node.ProcessMode(3L).toString()printsProcessMode(value=3). - Bitfields have
or,and,xor,inv()andin; the result keeps the type. Where Godot names no zero value,X(0L)is the empty set. - Defaults are the named value equal to Godot's default.
- Dynamic calls.
call,set,callDeferred,emitSignalandArray/Dictionaryelements accept the typed values and pass the integer they stand for. What a dynamic call returns (get,call) is aLong; wrap it withNode.ProcessMode(raw as Long)when you need the type. - Engine virtuals, the
_-prefixed engine methods you override with@OverrideVirtual, take the value class where Godot uses an enum (@OverrideVirtual fun _get_shader_mode(): Shader.Mode); aLongthere fails the build and names the type. - Script members typed with a Godot enum (
@Exportproperties, public functions,@Signal,@Rpc) are covered in Exports and Resources.
Enum Exports in the Inspector¶
An @Export of a Godot enum looks like the engine's own properties (what
Node.process_mode shows), not like GDScript's: an int with
PROPERTY_HINT_ENUM, or PROPERTY_HINT_FLAGS for a bitfield, and a hint
string of the value names as Godot capitalizes them, with the values spelled
out (Inherit:0,Pausable:1,When Paused:2,Always:3,Disabled:4,
Messages:1,Messages Physics:2,Messages All:3). GDScript's
@export var mode: Node.ProcessMode uses the full names
(Process Mode Inherit:0,...) and exports a bitfield as a dropdown of single
flags. The stored int is the same, so scenes are interchangeable.
Whether a type is a bitfield is Godot's call: BaseMaterial3D.Flags is an enum
of flag indices and exports as a dropdown. As in GDScript, the property's
class_name is Godot's qualified name (Node.ProcessMode) and its usage
includes PROPERTY_USAGE_CLASS_IS_ENUM; a bitfield uses Godot's
PROPERTY_USAGE_CLASS_IS_BITFIELD, so assigning a combination of flags from
GDScript does not warn. The default may be a value, the raw form
(Node.ProcessMode(3L)) or an or of bitfield values. A
List<Node.ProcessMode> is a typed int array. A value the hint does not list,
from a newer Godot or an extension, is kept, not clamped. On Web the export
carries the hint and hint string only, without class_name.
Every @Export* hint string is built the way GDScript's parser builds it, so
get_property_list() reports the same hint and hint string for a Kotlin script
and its GDScript twin. @ExportRange writes its extra flags in GDScript's
order: or_greater, or_less, exp, radians_as_degrees, degrees,
prefer_slider, hide_control, suffix:<unit>. Build errors follow
GDScript's argument rules: an empty argument, or one with a comma (except
placeholder text), a malformed @ExportFlags value, an @ExportNodePath
class that is not a Node (an engine class or a @GlobalClass script), a hint
on a type it does not take, two hints on one property.
Use the VariantType in net.multigesture.kanama.api; the one in
net.multigesture.kanama.binding.runtime is internal. If you are moving 0.4
code to the typed enums, see Upgrading from
0.4 and
Enum Constant Migration.
6. Nullability¶
val tree = self.getTree() ?: return // not marked required: SceneTree?
val sameTree = self.tree // non-null accessor: throws outside the tree
val root: Window = tree.getRoot() // required: Window, not Window?
val tween = self.createTween()
val tweener = tween.tweenProperty(self, "modulate", Color(1, 1, 1, 0), 0.5)
tweener.setTrans(Tween.TransitionType.SINE).setEase(Tween.EaseType.OUT) // required fluent returns chain with `.`
Object returns are nullable (X?): Godot promises nothing about them. The
exception is a return Godot marks meta: "required": it is non-null, and a
null from the engine throws
IllegalStateException("Godot returned null from required <Class>.<method>").
A Callable return is GodotCallable?.
Object parameters follow one decision, in this order:
- Godot marks it
meta: "required": non-null, always. - A
Resourceor otherRefCountedtype: nullable, so you can passnullto clear it. - Godot's source accepts
nullfor it, such asNode.setOwner: nullable. Kanama keeps a short list of these. - Otherwise non-null.
val meshInstance = self.requireAs<MeshInstance3D>("Body")
meshInstance.setMesh(null) // Resource-derived: nullable
val child = itemScene.instantiateAs<Node>() // itemScene: a preloaded PackedScene
child.setOwner(null) // Godot accepts null here
self.addChild(child) // Node, not marked required, not listed: non-null
X.fromHandle(handle) returns X?, except Resource.fromHandle, which is
non-null because a @ScriptClass(attachTo = "Resource") script uses it as its
constructor reference.
7. Ownership¶
The full statement is Resource Ownership. In short:
- A
RefCountedvalue a typed method returns (getMesh(),X.create(),ResourceLoader.load…, aTweener) is owned: it carries a reference that is yours.close()it oruse { }it. - So is every element of a returned typed
ArrayofRefCounted(getMaterials(),getProcessedTweens(), ...) on desktop, Android and iOS: close each element. An element of an untypedArray[Object]that isRefCountedcomes back as aRefCountedwrapper, so it can be closed.ArrayandDictionaryelements read through a dynamic call stay borrowed. close()releases your reference; it destroys the object only if that was the last one. Calling a member on a closed wrapper throwsIllegalStateExceptioninstead of reaching freed memory.- A fluent method that returns its own receiver (
tweener.setTrans(...)) returns the same wrapper, not a second owned one, so a chain needs no extraclose(). - Values read through a dynamic call (
call,get,getMeta, ...) are borrowed views: never close them. Nodes and plainObjects have noclose(); free nodes withqueueFree(). - A lambda signal connection is released by Godot when the receiver or the
emitter is freed, a one-shot connection fires, or it is disconnected, on every
platform.
SignalConnection.close()is only needed to disconnect early. See Signals and Await. - A forgotten
close()is a late release, not a leak, on desktop, Android, iOS and Web: once the garbage collector drops the wrapper, the reference is released on the main thread at the next frame.close()releases it at once, and only once. At shutdown a collection runs before Godot's leak report. The project settingkanama/debug/log_gc_releaseslogs each such release once per place in your code that created the object. Wrappers made on any thread get this fallback; the release still runs on the main thread. - A
from*downcast (Mesh.fromObject(obj)) takes a reference of its own, so a downcast kept in a field keeps the object alive whatever happens to the wrapper it came from.fromHandleand wrapper constructors are borrowed views;close()on one releases nothing, and debug builds warn. - A script on a
RefCountedowner, such as a custom resource, keeps its owner alive, as in GDScript and C#, on desktop, Android and iOS. See Keeping a Resource through Its Script. - Exported resource slots are a fixed list, because Kanama keeps each one
alive while the script holds it:
PackedScene,Texture,Texture2D,NoiseTexture2D,Material,ShaderMaterial,Curve,FastNoiseLite,ButtonGroup,LightmapGIData,AudioStream,Mesh,Shape2D,Shape3D,Font,Animation,StyleBox, and any@GlobalClasscustom resource script.
Errors in Callbacks¶
An exception thrown from a script callback is reported as a Godot script error,
and the call returns null. In a debug build on desktop, Android and iOS the
error names the Kotlin file and line; an Android minified release build and an
iOS release build cannot (see Limitations → Android
and Limitations → iOS). This covers lifecycle callbacks,
public functions, signal lambdas, property accessors, MainThread tasks and
coroutines started with launch; the full stack trace goes to the console. The
reported line is the first one in your own code, as a res:// path when the
file is in the project, else the bare file name. A wrapper of a freed object
handed to Godot as a value (an export, a return, a dynamic-call argument) is
silently null, as in GDScript. On Web the error reaches the Godot log without
the Kotlin line; see Limitations → Web.
The Full Ownership Table¶
| Category | What it covers | What to do |
|---|---|---|
| Owned | X.create(), ResourceLoader.load…, every RefCounted value a method returns including plain getters, every element of a returned typed Array of RefCounted (getMaterials(), actionGetEvents(), getProcessedTweens(), …), every RefCounted element of an Array/Dictionary that call(...) (or callv, callDeferred, callThreadSafe, ClassDB.classCallStatic, GodotCallable.call/callv) returns, the from* downcasts (Mesh.fromObject(...), ArrayMesh.fromResource(...)), the checked casts to a RefCounted class (res.cast<Texture2D>(), castOrNull), and @Export reads of resource-typed fields and collections |
close() it, or use { }, to release it early; for a list, each element (list.forEach { it.close() }). Forgotten, it is released after the garbage collector drops the wrapper |
| Borrowed view | A wrapper you build over a handle you already have: Resource.fromHandle(...), a wrapper constructor (Mesh(other.handle)), a script's own self, and the RefCounted elements of an Array or Dictionary that arrives as an argument of a signal lambda or a script function: the caller holds them for the call, so do not close() them or keep them past it |
Keep the wrapper you got the handle from while you use the view, because the view takes no reference. close() on it releases nothing (debug builds warn) |
| Engine-owned, live | A running Tween (from createTween() or an element of getProcessedTweens()), anything living in the scene tree |
Stop it the Godot way (kill(), queueFree()); close() never stops it. Your wrapper of a tween still owns a reference; close it when you stop using that wrapper |
Nodes and plain Objects |
Anything not RefCounted: there is no reference count, and GodotObject has no close() |
Node.queueFree() |
- Tweens. The
SceneTreeholds its own reference to every tween it processes, so a tween runs until it finishes or is killed, whatever your wrappers do.close()on a tween wrapper releases only your reference; it never stops the tween, and a closed wrapper cannot be called again. So:kill()to stop a tween;close(), afterkill()or once you no longer call it, to release your wrapper; and close each element ofSceneTree.getProcessedTweens()when you are done reading it, which does not affect the tweens. - Handing a value to Godot. Passing an owned wrapper to a method that
stores it (
setMesh,setStream,ResourceSaver.save) does not hand it over: Godot takes its own reference, and yours is still yours to close. @Exportreads. When the engine sets a property (a scene or.tresloads, the inspector,set("prop", value)), each resource value it holds, alone or in anArrayorDictionary, is kept alive the way GDScript keeps it, until the engine sets the property again or frees the script. A copy you keep elsewhere (cached = res) stays valid after the property changes. Assigning the property from Kotlin, or removing an element from aMutableListproperty, does not release the old value at once: it is released at the next engine set of that property or when the script is freed.- Received objects. A Godot object a script receives (a signal or callback
argument, a lookup, a call's result) is valid while the object lives, on every
platform, also after the script that obtained it is freed: a node another
script stored in a
companion object, or one a top-level initializer made, keeps working.
8. Statics and Singletons¶
val image = Image.create(64, 64, false, Image.Format.RGBA8)
if (Input.isActionPressed("jump")) { /* ... */ }
- A Godot static method is a member of the class's companion:
Image.create(...). - An engine singleton is a Kotlin
object:Input.isActionPressed("jump"),Time.getTicksMsec(). The singletons are the ones Godot lists. A singleton'sfromHandlereturns the object itself.
GD holds Godot's utility functions, one member per function, the same on
desktop, Android and iOS:
- Names are Godot's in camelCase (
deg_to_radisdegToRad), exceptprintErr,printS,printT,printRaw,typeOf(typeofis a Kotlin keyword) andisNaN. Parameter names are Godot's.floatisDouble,intisLong, aVariantisAny?. - The generic
abs,sign,floor,ceil,round,lerp,clamp,wrap,snapped,maxandminhave typed overloads:Doublefor all, andLongandIntwhere Godot has an int form (abs,sign,max,min,clamp,wrap). They call the typed functions (maxf,wrapi, ...), exceptclamp, which is GDScript'sclamp: it sets the value tominif it is less, then tomaxif it is greater, soGD.clamp(0.0, 3.0, 1.0)is1.0as in GDScript.clampfandclampikeep Godot's typed result,3.0, whenminis greater thanmax. Vectors, mixed types and three or more values take theAny?form, which returns what Godot returns (GD.abs(Vector3(-1.0, 2.0, -3.0))is aVector3, as anAny?). print,printErr,printS,printT,printRaw,printRich,printVerbose,pushError,pushWarningandstrtake any number of values. Godot formatsnull, strings, booleans and numbers itself; any other value is passed as itstoString().- Every other
Any?parameter (typeOf,hash,isSame,varToStr,varToBytes,weakref,typeConvert, theAny?forms ofmax,lerp,clamp, ...) needs a value Godot can hold:null,Boolean, the numbers,String,NodePath, the value types,RID, aGodotObject, aByteArray, or aListorMapof those. Any other Kotlin object throws (Unsupported Variant value typeon desktop,unsupported Variant argument typeon iOS); Kanama does not turn it into a string behind your back. isInstanceValidtakes aGodotObject?and is safe on a wrapper whose object was freed.isInstanceIdValidtakes a raw id.- The random functions use Godot's one global generator on every platform,
like GDScript and C#, so
seed()from GDScript or Kotlin gives the same sequence. For strict determinism use aRandomNumberGeneratorwith its own seed, because anything else can draw from the global generator.
Mathf is the C#-style math object, the same on every platform: lerp,
clamp, wrap, snapped, moveToward, smoothStep, pingPong, degToRad,
PI, TAU, ... Where Godot's function is plain arithmetic, Mathf computes it
in Kotlin with no engine call and returns the same double as GDScript, bit for
bit; the transcendental functions (sin, pow, exp, ...) and the
float-to-int conversions (roundToInt, floorToInt) call GD. Each member
also has a Float overload that computes in Double.
9. Defaults and Overloads¶
- A Godot default argument is a Kotlin default argument when Kotlin can express
it, including a few composite ones such as
Node3D.lookAt(target, up = Vector3.UP). - A default Kotlin cannot express makes the parameter required:
CanvasItem.drawTexture(texture, position, modulate)needs theColorGodot defaults to white. Every such parameter is listed under "Godot Defaults Not Expressed" in the generator report. When a later Kanama gives one a default, your code still compiles. - When Godot adds a parameter with a default at the end of a method, Kanama adds
it the same way and your calls still compile, so it is not listed as a source
break. A method you can override is the exception, because your override
would stop matching: an
openorabstractmethod, and every method of an interface. So is a method that ended in a lambda or avararg. Your source compiles unchanged, but the compiled call does not: rebuild your scripts after updating Kanama, as a scripts jar built against the old method fails withNoSuchMethodErroron desktop and Android. GodotSignal.connectand the other members Kanama writes by hand per platform have overloads instead of default arguments:signal.connect(target, method)andconnect(target, method, flags).- Godot has no overloads. Kanama adds a few: a
Stringoverload beside eachNodePathlookup onNode(getNodeOrNull("Hud/Label")) and onGodotObject(setIndexed,getIndexed). Godot's vararg methods are Kotlinvararg(call(method, vararg args),rpc,emitSignal).
10. Collections¶
val area = self.requireAs<Area3D>("Hitbox")
val bodies: List<Node3D> = area.getOverlappingBodies()
val groups: List<String> = self.getGroups()
| Godot type | Kotlin type |
|---|---|
Array |
List<Any?> |
Array[T] (typed) |
List<T>, for example List<Node3D>, List<String> |
Dictionary |
Map<String, Any?> (String keys) |
PackedStringArray |
List<String> |
PackedByteArray |
ByteArray |
PackedInt32Array / PackedInt64Array |
List<Int> / List<Long> |
PackedFloat32Array / PackedFloat64Array |
List<Float> / List<Double> |
PackedVector2Array, PackedVector3Array, PackedVector4Array, PackedColorArray |
List<Vector2>, List<Vector3>, List<Vector4>, List<Color> |
String, StringName |
String |
NodePath |
NodePath (plus String overloads on Node) |
Callable |
GodotCallable(target, method) |
Signal |
GodotSignal |
Variant |
Any? |
A method whose combination of types Kanama cannot pass is left out rather than given a looser type; the Wrapper Generator Report lists each one with the reason.
Godot's own methods of the types Kotlin represents itself are there too:
String's and PackedByteArray's as extension functions on String and
ByteArray in net.multigesture.kanama.builtins, NodePath's as NodePath
members, and Callable's and Signal's as GodotCallable and GodotSignal
members; see
Strings, Node Paths and Bytes.
A List<String> script property exports as Array[String] and reads back as
Kotlin strings, including a PackedStringArray value set in a scene.
String, NodePath, ByteArray and Callable Methods¶
- Godot's semantics. Each String function runs Godot's implementation in
the engine, so it answers what GDScript answers: positions and lengths
(
godotFind,substr,unicodeAt,left,godotLength) count Unicode characters like GDScript, where Kotlin'sindexOfandlengthcount UTF-16 units. They differ only for characters such as emoji. Each call is one engine call that converts the text both ways, so in a per-frame loop over many strings Kotlin's own functions are cheaper. A lone UTF-16 surrogate arrives as?, and an embedded NUL ends the text. More examples:"res://levels".pathJoin("one.tscn"),String.num(3.14159, 2)("3.14"),"7".padZeros(3),text.isValidFloat(),"{0} has {1} HP".godotFormat(listOf("Bob", 3)). - The
godotprefix. Importing the package must never change an existing Kotlin call, so a Godot method whose name Kotlin'sStringalready has is namedgodot+ the name:godotLength(),godotFind(...),godotCount(...),godotSplit(...),godotFormat(...),godotIndent(...),godotCapitalize(),godotHexToInt(),godotToInt()andgodotToFloat(). The last two parse leniently, like GDScript:"12abc"is 12. The methods Kotlin answers identically are not repeated:isEmpty(),contains(...),startsWith(...)(begins_with),endsWith(...),replace(...),repeat(n),parts.joinToString(sep)(join) andremovePrefix/removeSuffix(trim_prefix/trim_suffix). NodePathmembers follow Godot's own parsing:NodePath("Arm/Hand:position:x").getName(1)is"Hand",getSubname(1)is"x", plusgetNameCount(),getConcatenatedNames(),getConcatenatedSubnames(),isAbsolute(),isEmpty(),slice(begin, end),getAsPropertyPath()andhash(). As in Godot, an invalid path ("a::b") is the empty NodePath and an index out of range answers"", each with Godot's error printed. The error prints when a member first reads the path, where GDScript prints it when the NodePath is built.ByteArraygets the PackedByteArray methods Kotlin arrays lack:decodeU8...decodeS64,decodeHalf/decodeFloat/decodeDouble, theencode*twins,bswap16/32/64,hexEncode(),toInt32Array()...toColorArray(),getStringFromUtf8()/Utf16/Utf32/Ascii/Wchar,compress(mode),decompress(size, mode),decompressDynamic(max, mode),decodeVar(offset)anddecodeVarSize/hasEncodedVar. Where Godot prints an error and returns 0 or an empty array, the Kotlin function throws:IndexOutOfBoundsExceptionfor an offset outside the array,IllegalArgumentExceptionfor ato*Array()of a size that is not a multiple of the element and for abswap*count past the end. Forencode_var,GD.varToBytes(value).copyInto(bytes, offset)is the same encoding. The other packed arrays'to_byte_arrayistoByteArray()on their list types (listOf(1, 2).toByteArray()).GodotCallable(target, "method")has Godot's Callable methods for an object and a method name:call(...),callv(list),callDeferred(...),isValid(),getObject(),getObjectId(),getArgumentCount(),rpc(...)andrpcId(peer, ...).rpcon a target that is not aNodeis a call error, as in Godot.getObjectId()answers the id after the target is freed, as Godot's does. AGodotCallablecarries no extra bound arguments, sobind/unbindand the bound-argument queries are not offered. AGodotSignal(node.signal("name"), or a typed signal's handle) addsisConnected(target, "method"),getConnections(),hasConnections(),getObject()andgetObjectId()toconnect/disconnect/emit.
11. Handles and Factories¶
val material = StandardMaterial3D.create() // owned: close() it when done
val resource = ResourceLoader.load("res://mesh.tres")
val mesh = resource?.let { ArrayMesh.fromResource(it) } // null if it is not an ArrayMesh
val collider: GodotObject = self.requireAs<Node>("Collider")
val body = collider.castOrNull<Node3D>() ?: return
GodotHandleis the identity of a Godot object. Every class has a public constructor from it, but that constructor does not check the class:CharacterBody3D(body.handle)callsCharacterBody3Dmethods on whateverbodyreally is.- Checked casts re-type a wrapper safely:
body.castOrNull<CharacterBody3D>()asks Godot and returnsnullwhen the object is another class,cast<T>()throws aClassCastException, andNode.requireAs<T>(path)/getNodeAs<T>(path)check the node they find. The untypedrequireAs(path, ::Label)andgetAsOrNull(path, ::Label)do not check the class. ARefCountedresult is a new wrapper with a reference of its own, like thefrom*downcasts: close it or let the garbage collector release it; the original is unaffected. Checked casts need no reflection, so they survive R8, Android's release shrinker. Web does not have them; see Limitations. X.fromHandle(handle)wraps an existing object as a borrowed view (Nullability has its return type).X.create()makes a new object, GDScript'sX.new(). Every class Godot can instantiate that is aNodeor aRefCountedhas one; a plainObjectclass does not, since Kotlin has nofree()for it. Thefrom*downcasts (ArrayMesh.fromResource(res),Mesh.fromObject(obj)) returnnullwhen the object is not that class.
12. Names as Constants¶
val timer = self.requireAs<Timer>("Timer")
timer.connect(Timer.Signals.timeout, self, "onTimeout")
Every class with signals has X.Signals, one const val per signal holding
Godot's name: Timer.Signals.timeout == "timeout",
Node.Signals.treeExited == "tree_exited". On Web each class carries the same
constants, and typed handles for the signals it declares. The engine-wide
MethodName, PropertyName and SignalName objects hold every method,
property and signal name on desktop, Android and iOS; Web scripts use string
literals or X.Signals.
13. Platform Parity¶
Desktop, Android and iOS compile one API from one source, so a member exists on all three or on none, and the compiler tells you. The exceptions are listed:
- members available on desktop and Android only, because iOS cannot pass their types: listed on iOS Shape Gap;
- iOS-only conveniences, such as a form of
PhysicsDirectSpaceState3D.intersectRaythat takes nullable arguments.
Web has its own API, with the members the Web build supports rather than
every Godot method. It uses the same enum types and value names as native, the
same meta: "required" rule for returns, and Double for decimals including
value-type components. It differs from the native API in places, for example:
- a parameter named like a Kotlin keyword gets a different name:
internalisinternalModeon Web andinternalValuenatively; - some object parameters differ in nullability, for example
Node.removeChild(node: Node?)on Web; - a few returns are non-null on Web where native is nullable:
Node.getTree()isSceneTreeon Web and throws outside a tree.
Code that must compile for Web and native should not rely on parameter names
where they differ, and should treat getTree() as nullable.
A difference is a compile error, never a different result.
GodotObject.set(property, value) is Godot's Object.set everywhere, like
GDScript's set: a path such as "position:x" names no property, so it changes
nothing; setIndexed("position:x", value) is the path form. A few of Web's own
GodotObject members differ from native, such as the missing
get(property): Any? and a setDeferred that takes only a Boolean; code
that uses them fails the Web build.