Exports and Resources¶
An exported property is a field the inspector can edit and a scene can save,
as with GDScript's @export. The snippets sit inside a script like the one in
Writing Scripts, which lists the imports.
Exported Properties¶
@ScriptClass(attachTo = "CharacterBody3D")
class Player(godotObject: GodotHandle) :
KanamaScript<CharacterBody3D>(godotObject, ::CharacterBody3D) {
@ExportCategory("Tuning")
@ExportGroup("Movement")
@ExportRange(0.0, 20.0, 0.1)
var speed: Double = 5.0
@ExportSubgroup("Jump")
@Export
var jumpVelocity: Double = 8.0
@Export(name = "hp")
@ExportRange(0.0, 100.0)
var health: Long = 100
}
@Export puts a property in the inspector under its snake_case name
(jump_velocity). A hint annotation such as @ExportRange exports the
property by itself, as in GDScript. Add @Export beside a hint only to set
name, which overrides the Godot name, or usage, which takes
PropertyUsage flags for unusual inspector behavior.
The initializer is the inspector's default, the value the revert arrow goes
back to, when the build can work it out: a literal, an enum value,
NodePath("..."), a named constant such as Vector3.UP, a value-type
constructor of those, or arithmetic on them (Mathf.PI / 3.0,
degToRad(90.0)). Any other initializer still sets the property, but the
inspector shows no default for it.
Values of the Wrong Type¶
@OnReady
fun ready() {
self.set("hp", "42") // a numeric String: stored as 42
self.set("hp", Vector2(1.0, 2.0)) // refused: hp keeps its value
}
A typed property follows GDScript's rule for a typed @export var when a
value comes from set() or from GDScript. A value of the declared type
is stored. A value Godot can convert to the declared type is converted: an
int for a Double and back, a numeric String for a number, a Vector2i
for a Vector2, a colour name for a Color. Anything else is refused: the
property keeps its value and Godot prints a script error such as
Expected int for property 'hp' but the Variant holds Vector2. iOS applies
this rule to value types, NodePath and Color only; see
Limitations.
Export Hints¶
Every GDScript @export_* annotation has a Kotlin twin that builds the same
hint, so the inspector shows a Kotlin property exactly as it shows the
GDScript one:
| GDScript | Kanama | Property types |
|---|---|---|
@export_range(0, 100, 1) |
@ExportRange(0.0, 100.0, 1.0) |
Long, Int, Double, Float |
@export_range(0, 100, 1, "or_greater", "suffix:m") |
@ExportRange(0.0, 100.0, 1.0, orGreater = true, suffix = "m") |
as above |
@export_enum("Warrior", "Magician:5") |
@ExportEnum("Warrior", "Magician:5") |
Long, Int, String, List<String> |
@export_flags("Fire", "Water:4") |
@ExportFlags("Fire", "Water:4") |
Long, Int |
@export_flags_2d_render / _2d_physics / _2d_navigation |
@ExportFlags2DRender / @ExportFlags2DPhysics / @ExportFlags2DNavigation |
Long, Int |
@export_flags_3d_render / _3d_physics / _3d_navigation |
@ExportFlags3DRender / @ExportFlags3DPhysics / @ExportFlags3DNavigation |
Long, Int |
@export_flags_avoidance |
@ExportFlagsAvoidance |
Long, Int |
@export_file("*.png", "*.jpg") |
@ExportFile("*.png", "*.jpg") |
String, List<String> |
@export_file_path("*.txt") |
@ExportFilePath("*.txt") |
String, List<String> |
@export_dir |
@ExportDir |
String, List<String> |
@export_global_file("*.cfg") / @export_global_dir |
@ExportGlobalFile("*.cfg") / @ExportGlobalDir |
String, List<String> |
@export_multiline("monospace", "no_wrap") |
@ExportMultiline(monospace = true, noWrap = true) |
String, List<String> |
@export_placeholder("Name") |
@ExportPlaceholder("Name") |
String, List<String> |
@export_exp_easing("attenuation", "positive_only") |
@ExportExpEasing(attenuation = true, positiveOnly = true) |
Double, Float |
@export_color_no_alpha |
@ExportColorNoAlpha |
Color |
@export_node_path("Button", "TouchScreenButton") |
@ExportNodePath("Button", "TouchScreenButton") |
NodePath |
@export_storage |
@ExportStorage |
any exportable type |
@export_custom(PROPERTY_HINT_PASSWORD, "") |
@ExportCustom(PropertyHint.PASSWORD) |
any exportable type |
@export_tool_button("Text", "Icon") |
@ExportToolButton("Text", "Icon") on a function |
see Inspector Buttons |
@ScriptClass(attachTo = "Node")
class Tuning(godotObject: GodotHandle) :
KanamaScript<Node>(godotObject, ::Node) {
@ExportRange(0.0, 100.0, 1.0, orGreater = true)
var health: Long = 100
@ExportFile("*.png", "*.jpg")
var icon: String = ""
@ExportMultiline
var description: String = ""
@ExportFlags3DPhysics
var hitLayers: Long = 1
@ExportColorNoAlpha
var tint: Color = Color(1.0, 0.5, 0.0)
@Export
var area: Rect2 = Rect2(Vector2.ZERO, Vector2(64.0, 32.0))
}
The arguments follow GDScript's rules, and a mistake is a build error: an
empty argument, a malformed @ExportFlags value, a hint on a type it does not
take, or two hint annotations on one property. On a List<String> the hint
applies to each element, as on a GDScript Array[String]. @ExportRange
without a step uses the editor's default: 1 for an integer. @ExportCustom takes any
PropertyHint value, for a hint no typed annotation covers.
Every Godot value type exports, as tint and area show. An enum needs no
hint: it shows as a dropdown on its own.
Exporting Enums¶
enum class Difficulty { EASY, NORMAL, HARD }
@ScriptClass(attachTo = "Node")
class GameRules(godotObject: GodotHandle) :
KanamaScript<Node>(godotObject, ::Node) {
@Export
var difficulty: Difficulty = Difficulty.NORMAL
@Export
var unlockedModes: List<Difficulty> = emptyList()
}
A Kotlin enum class property shows as a dropdown of its entry names, as a C#
enum export does. The scene stores the entry's position in the class, so
add new entries at the end: reordering or removing entries changes what
saved scenes mean. A stored number with no matching entry loads as a valid
entry instead of failing. A List of an enum shows the same dropdown for each
element; its default must be empty (emptyList()), and you fill it in the
inspector.
Godot Enums and Bitfields¶
@Export
var mode: Node.ProcessMode = Node.ProcessMode.PAUSABLE
@Export
var messages: Node.ProcessThreadMessages = Node.ProcessThreadMessages.MESSAGES // a bitfield
@Export
var allowedModes: List<Node.ProcessMode> = emptyList()
A property typed with one of Godot's own enums (see
Godot Enums and Bitfields) shows as
a dropdown, and a bitfield as flag checkboxes. The scene stores Godot's number
for the value, so a scene saved by a GDScript or C# version of the script loads
unchanged, and typed GDScript sees the property as a Node.ProcessMode. The
type is non-null, and a list default must be empty. How the inspector metadata
compares with GDScript's is in
API Conventions.
Exporting Dictionaries¶
@Export
var spawnCounts: Map<String, Long> = emptyMap()
@Export
var regionIcons: Map<Vector2i, Texture2D> = emptyMap()
A Map<K, V> exports as a typed Godot Dictionary, and the inspector offers
the matching key and value pickers. The default must be empty; fill it in the
inspector. A Map<String, Any?> is an untyped Dictionary.
- Keys can be
String,Long,Int,Double,Float,Boolean,Vector2,Vector2i,Vector3,Vector3i,Coloror anenum class. - Values can be any of those, a Godot resource or node class, or one of
your
@ScriptClassscripts. A resource value is kept alive while the dictionary holds it, as in aList<Texture2D>. Anenum classkey or value is stored by position, as in an enum export.
An entry whose key or value does not match the declared types, such as one in
a hand-edited scene, is skipped. A nil value is kept as null in a
Map<K, V?> and dropped from a Map<K, V>. An object value type cannot be
nullable: declare Map<String, Texture2D>, not Map<String, Texture2D?>.
Node References¶
@Export
var crosshair: TextureRect? = null
@Export
var viewPath: NodePath = NodePath("../View")
Export a node reference as its class when the GDScript original exported the
node. Use NodePath only when the original exported a path on purpose.
Resource Slots¶
@Export
var stream: AudioStream? = null
@Export
var icons: List<Texture2D> = emptyList()
An exported resource is nullable with a = null default. A slot of a base
class accepts its subclasses: an AudioStreamWAV or AudioStreamOggVorbis
goes into an AudioStream slot. The common resource classes, such as
PackedScene, Texture2D, Material, Mesh and AudioStream, and your own
custom resources can be exported; the full list is in
API Conventions. If you need
another one, please open an issue.
Do not use lateinit var for an export. It has no inspector default, and
reading it before the scene assigns it crashes. The build warns and suggests
the = null form.
Inspector Buttons¶
@ScriptClass(attachTo = "Node")
@Tool
class Spawner(godotObject: GodotHandle) :
KanamaScript<Node>(godotObject, ::Node) {
@Export
var seed: Long = 0
@ExportToolButton(text = "Randomize", icon = "RandomNumberGenerator")
fun randomize() {
seed = GD.randiRange(0, 9999)
notifyInspectorChanged()
}
}
@ExportToolButton on a function with no parameters shows a button in the
inspector, like GDScript's @export_tool_button. The script must be @Tool,
and the function runs in the editor, so guard editor-only work as in any tool
script.
Releasing Resources You Create¶
The rule is on Calling Godot APIs:
close() releases your reference. It never destroys an object someone else
still holds. The case you meet most is a resource you create and hand to the
engine:
private fun bindKeys(action: String, keys: List<Key>) {
InputMap.addAction(action)
for (key in keys) {
InputEventKey.create().use { inputKey -> // you own this reference
inputKey.keycode = key
InputMap.actionAddEvent(action, inputKey) // InputMap takes its own
} // use { } releases yours
}
}
The same code in GDScript or C# needs no cleanup, and it does not leak there either:
var input_key = InputEventKey.new()
input_key.keycode = keycode
InputMap.action_add_event(action, input_key)
# the reference is dropped when input_key leaves scope
var inputKey = new InputEventKey();
inputKey.Keycode = keycode;
InputMap.ActionAddEvent(action, inputKey);
// the reference is dropped when the garbage collector collects inputKey
GDScript drops your reference when the variable leaves scope. C# drops it when
the garbage collector collects the object. Kanama does both: use { } releases
your reference at once, as GDScript's scope exit does, and a wrapper you forget
is released after the garbage collector drops it, as in C#. So closing is about
when: use { } releases now, the collector releases later. The project
setting kanama/debug/log_gc_releases names each line whose wrapper the
collector had to release.
Custom Resources¶
@ScriptClass(attachTo = "Resource")
@GlobalClass
class Weapon(godotObject: GodotHandle) :
KanamaScript<Resource>(godotObject, ::Resource) {
@Export
var damage: Long = 10
@Export
var displayName: String = "Sword"
@Export
var swingSound: AudioStream? = null
}
A custom resource is a script attached to Resource, like GDScript's
extends Resource with a class_name. Extend KanamaScript<Resource>; the
Godot classes cannot be subclassed. Save the class in a file of the same name
(Weapon.kt), or it stays out of the editor's class list; the build warns when
they differ.
@GlobalClass makes Weapon a resource type the editor knows: it appears in
Create New Resource, its .tres files fit typed export slots, and GDScript
can type against it (@export var w: Weapon, w is Weapon). Another script
can export Weapon? or List<Weapon>, and the values, nested resources such as
swingSound included, are saved in .tscn and .tres files.
Keeping a Resource through Its Script¶
@ScriptClass(attachTo = "Node")
class WeaponSlot(godotObject: GodotHandle) :
KanamaScript<Node>(godotObject, ::Node) {
private var weapon: Weapon? = null
@OnReady
fun ready() {
// keep the script object; the loaded wrapper is closed at once
weapon = ResourceLoader.load("user://weapon.tres")?.use { it.kotlinScriptInstance<Weapon>() }
}
fun save() {
val weapon = weapon ?: return
ResourceSaver.save(weapon.self, "user://weapon.tres")
}
}
kotlinScriptInstance<T>() returns the Kotlin script object attached to a
Godot object, or null when it has none. Holding that script object keeps
the resource alive, as holding the resource does in GDScript, whatever
happened to the wrapper you reached it through. Drop your last reference to
the script object and the resource is released like any forgotten wrapper.
Saving Custom Resources¶
@ScriptClass(attachTo = "Node")
@Tool
class WeaponForge(godotObject: GodotHandle) :
KanamaScript<Node>(godotObject, ::Node) {
@Export
var weapon: Weapon? = null
@ExportToolButton(text = "Save Weapon")
fun saveWeapon() {
val weapon = weapon ?: return
ResourceSaver.save(weapon.self, "res://weapon.tres")
}
}
A custom resource script is not itself a Resource, so pass its self to an
API that takes one, such as ResourceSaver.save. self takes no reference of
its own, so there is nothing to close.
Calling the constructor yourself, Weapon(someNode.handle), does not
create a resource. It wraps the handle you pass, which gives a view of the
wrong object when that handle is not a Weapon resource.
Creating Custom Resources from Kotlin¶
@ScriptClass(attachTo = "Node")
@Tool
class Armory(godotObject: GodotHandle) :
KanamaScript<Node>(godotObject, ::Node) {
@ExportToolButton(text = "Make Excalibur")
fun makeExcalibur() {
newScriptInstance<Weapon>().use { owned ->
owned.instance.damage = 25
owned.instance.displayName = "Excalibur"
ResourceSaver.save(owned.resource, "res://excalibur.tres")
}
}
}
newScriptInstance<T>() is GDScript's Weapon.new(): it creates a Resource,
attaches the script and returns both, the script object as instance and the
resource as resource. It works in the game and in @Tool code, even when
the resource script is not @Tool. T must be
a @GlobalClass resource script in a file of the same name.
The result holds one reference to the new resource, as .new() does. Release
it with use { } or close() when you are done, also after you assign
owned.resource to a node or an exported slot: the engine takes its own
reference there.
ClassDB.instantiate("Weapon") returns null for a custom resource, even
though ClassDB.canInstantiate("Weapon") is true. This is Godot's behavior
for every script class, GDScript and C# included, because script classes are
not in ClassDB. Use newScriptInstance<Weapon>() from Kotlin. From GDScript,
attach the script to a new resource:
var r = Resource.new(); r.set_script(load("res://Weapon.kt")).
On Other Platforms¶
Exports and custom resources work the same way on desktop and Android. iOS
and Web cannot carry a few export types, and the build stops and names the
property when you use one. iOS converts a value of the wrong type only for
value types, NodePath and Color. iOS has no newScriptInstance, and on Web a custom
resource's script object does not keep its resource alive.
Limitations lists each case with its workaround.