Lua API: Types

Values passed around: vectors, hits, events, options tables.

RaycastHit

Field	Type
hit	boolean	Whether the ray struck a physics shape
point_x	number	World X hit coordinate
point_y	number	World Y hit coordinate
normal_x	number	World surface normal X
normal_y	number	World surface normal Y
fraction	number	Hit fraction from 0.0 to 1.0 along ray length
node?	Node	Engine node attached to the struck body, if any

TextHolder

Nodes that show text (TextNode, UILabelNode, UIButtonNode).

TextHolder:set_text(text)

Sets the text of a TextNode (restarting its typewriter), UI label or button.

self.node:get_node("ScoreLabel"):set_text("Score: " .. self.score)

• text string

TextHolder:get_text()

Gets the text of a TextNode, UI label or button.

local text = self.node:get_node("ScoreLabel"):get_text()

Returns string

NavGrid

Nodes with a walkable grid (TileMapNode, LdtkLevelNode).

NavGrid:nav_find_path(x1, y1, x2, y2, opts)

A* path on this TileMap’s, LDtk level’s or NavigationRegion’s grid (TileMap: painted tiles are walls when the map is solid; LDtk: IntGrid cells whose collision rule is Solid; a region: what it baked). Waypoints from the start to the end, or nil when unreachable.

local level = Scene.find_node("Level"); local path = level:nav_find_path(x, y, tx, ty, {diagonal = false})

• x1 number
• y1 number
• x2 number
• y2 number
• opts? NavOptions

Returns number[][]? path { {x, y}, … }

NavGrid:nav_is_walkable(x, y, opts)

Whether the grid cell at a world position is walkable.

local level = Scene.find_node("Level"); if level:nav_is_walkable(tx, ty) then self.target = {tx, ty} end

• x number
• y number
• opts? NavOptions

Returns boolean

DialogueLine

Field	Type
speaker?	string
text	string	Rich text ([color=..] [size=..] [wave] [shake]), or a locale key when the box is localized
voice?	string	A sound played with the line (in Subtitles mode the line lasts as long)

NavOptions

Field	Type
diagonal?	boolean	8 directions (default true); no cutting past blocked corners
smooth?	boolean	Straighten where the line of sight is clear (default true)
walkable_painted?	boolean	TileMap: painted tiles are the floor (default: not solid)
radius?	number	Agent radius (px): the path keeps this far from walls (a goal too close to one moves to the nearest place that fits)

AsepriteTag

Field	Type
name	string
from	integer	First frame (0-based)
to	integer	Last frame
direction	"Forward"|"Reverse"|"Ping_Pong"|"Ping_Pong_Reverse"
repeats	integer	0 = loops (or once, with loop off)
user	AsepriteUserData

AsepriteUserData

Field	Type
text	string
color?	integer[]	{r, g, b, a} 0-255
properties	table<string,	any> Aseprite’s user properties (numbers, strings, booleans, points {x, y}, sizes {width, height}, rects, lists, maps)

AsepriteInfo

Field	Type
width	integer
height	integer
frames	integer[]	Each frame’s duration (ms)
tags	AsepriteTag[]
layers	string[]	Layer names, bottom first
user	AsepriteUserData	The sprite’s user data

AsepriteSlice

Field	Type
x	integer
y	integer
width	integer
height	integer
center?	{x:	integer, y: integer, width: integer, height: integer} 9-patch centre (relative to the slice)
pivot?	{x:	integer, y: integer} Relative to the slice’s origin
user	AsepriteUserData

SM_Change

Field	Type
from	string	The state left (“” when it started)
to	string	The state entered
time	number	Seconds the machine had run
why	string	“start”, “travel” or “transition N”

LdtkColor

Field	Type
r	integer
g	integer
b	integer
a	integer

LdtkTileRect

Field	Type
tileset_uid	integer
x	number
y	number
w	number
h	number

LdtkEntityRef

Field	Type
field	string	EntityRef field name
iid	string	Referenced entity iid
index	integer	Element of an array field (0 = single field)
level?	string	Level holding the target

LdtkEntity

Field	Type
identifier	string	Entity definition identifier (e.g. “Turret”)
iid	string	Unique instance id (EntityRef fields point to it)
x	number	X in level pixels (pivot point)
y	number	Y in level pixels (pivot point)
world_x	number	X in world coordinates
world_y	number	Y in world coordinates
cx	integer	Grid cell X
cy	integer	Grid cell Y
width	number
height	number
pivot_x	number
pivot_y	number
level	string	Level identifier
color	LdtkColor	Smart colour
tile?	LdtkTileRect	The entity’s LDtk tile
tags	string[]
fields	table<string,	any> Field values (arrays as Lua arrays; Point = {cx, cy}; Enum = value id; EntityRef = iid; Tile = LdtkTileRect)
enums	table<string,	string> Enum fields: field name -> enum name
refs	LdtkEntityRef[]	EntityRef values of its fields
node?	Node	The spawned node (while the level is built)

LdtkLevel

Field	Type
identifier	string
iid	string
uid	integer
world	string	World identifier
world_x	integer
world_y	integer
depth	integer	World depth
width	integer	Pixels
height	integer	Pixels
x	number	Level origin in world coordinates
y	number
bg_color	LdtkColor
fields	table<string,	any> Level fields
layers	string[]	Layer identifiers (top first)
neighbours	LdtkNeighbour[]

LdtkNeighbour

Field	Type
level	string	Level identifier
iid	string
dir	string	n s e w nw ne sw se < > o

LdtkWorld

Field	Type
identifier	string
iid	string
layout	string	Free, GridVania, LinearHorizontal, LinearVertical
grid_width	integer
grid_height	integer
levels	string[]

LdtkLayer

Field	Type
identifier	string
type	string	IntGrid, Entities, Tiles, AutoLayer
grid_size	integer
width	integer	Cells
height	integer	Cells
visible	boolean
opacity	number
parallax_x	number
parallax_y	number
parallax_scaling	boolean
offset_x	number
offset_y	number
entities	integer
tiles	integer

LdtkIntGridValue

Field	Type
value	integer
identifier	string
color	LdtkColor
collision	string	none, solid, one_way, trigger

LdtkTile

Field	Type
id	integer	Tile id in its tileset
tileset_uid	integer
flip_x	boolean
flip_y	boolean
custom_data	string	Tileset custom data of the tile
enums	string[]	Enum values tagging the tile

LdtkEnumValue

Field	Type
id	string
index	integer
color	LdtkColor
tile?	LdtkTileRect

LdtkEntityDef

Field	Type
identifier	string
width	number
height	number
color	LdtkColor
tags	string[]
fields	{identifier:	string, type: string, enum?: string}[]

LdtkLink

Field	Type
source	Node
target?	Node
field	string
source_iid	string
target_iid	string
index	integer

TweenOptions

Field	Type
delay?	number	Seconds before it starts (it starts from the value at that time)
loops?	integer	Extra runs (-1 = forever)
yoyo?	boolean	Every other run goes back
on_complete?	fun(node:	Node) Called when it finishes

AccessibilitySettings

Field	Type
ui_scale	number	0.5..3 - top-level UI elements grow around the screen corner / edge / centre they’re nearest to
colorblind	"none"|"protanopia"|"deuteranopia"|"tritanopia"	Colour filter (corrects the picture)
colorblind_strength	number	0..1
colorblind_simulate	boolean	Show how it looks with the deficiency instead (testing)
subtitles	boolean	Spoken lines on the subtitle track
captions	boolean	Sounds’ captions on the subtitle track
subtitle_scale	number	0.5..3
subtitle_background	number	Backdrop opacity 0..1
screen_shake	number	0..2 - scales every camera shake / trauma

SubtitleOptions

Field	Type
speaker?	string	Shown before the line
duration?	number	Seconds (default: its reading time)
caption?	boolean	A sound caption (shown when the player has captions on) instead of a spoken line
color?	Color

CrashReport

Field	Type
path	string	The report file
text	string	Its contents (version, platform, reason, stack, recent log lines)

InputBindingInfo

Field	Type
device	"key"|"mouse"|"button"|"axis"
name	string	The raw name (“SPACE”, “LEFT”, “RIGHT_FACE_DOWN”, “LEFT_X”)
key?	string
mouse?	string
button?	string
axis?	string
positive?	boolean	Axis direction
text	string	What to show the player (“Space”, “Left Shift”, “A”, “Left Stick Right”)

InputBindingSpec

Field	Type
key?	string	A keyboard key (“SPACE”, “W”, “LEFT_SHIFT”)
mouse?	string	A mouse button (“LEFT”, “RIGHT”, “MIDDLE”)
button?	string	A gamepad button (“RIGHT_FACE_DOWN” = A, “LEFT_TRIGGER_1” = LB, “MIDDLE_RIGHT” = Start)
axis?	string	A gamepad axis (“LEFT_X”, “LEFT_Y”, “RIGHT_X”, “RIGHT_Y”)
positive?	boolean	Axis direction (true: right / down)

InputListenOptions

Field	Type
slot?	integer	Which binding to replace (1-based); default: the first one of the same device kind, else a new one
device?	"any"|"keyboard"|"gamepad"	Which inputs count (default any)
conflicts?	"clear"|"swap"|"allow"	Another action using it loses it (clear, default), gets this one’s old binding (swap), or keeps it (allow)
cancel?	string	The key that cancels (default “ESCAPE”)
on_done?	fun(result:	“bound”|“cancelled”, text: string) Called when it’s bound or cancelled

CameraTargetOptions

Field	Type
weight?	number	Pull of this target on the framing (default 1)
weight_x?	number	Horizontal pull (default: weight)
weight_y?	number	Vertical pull (default: weight)
radius?	number	Space kept around it when auto-zooming (default 50)
offset_x?	number
offset_y?	number
priority?	integer

SceneTransition

Field	Type
transition?	TransitionKind	Default “fade”
duration?	number	Seconds for each half (cover, uncover); default 0.4
color?	number[]	{r, g, b} 0..1; default black
loading?	SceneName|ScenePath	A loading screen scene shown while the scene loads in the background
min_time?	number	Seconds the loading screen stays at least (default 0.5)

Vec2

A 2D vector: v.x, v.y (also v[1]…); + - * / with a vector or a number.

Field	Type
x	number
y	number

Vec2:length()

Returns the vector’s length (magnitude).

local speed = self.velocity:length()

Returns number

Vec2:length_squared()

Returns the squared length, cheaper than length() for comparisons.

if (target - pos):length_squared() < 16 * 16 then self.arrived = true end

Returns number

Vec2:normalized()

A vector of length 1 in the same direction (zero stays zero).

local dir = (target - pos):normalized()

Returns Vec2

Vec2:dot(other)

Returns the dot product with another vector.

local facing = forward:dot((target - pos):normalized())

• other Vec2

Returns number

Vec2:distance(other)

Returns the distance to another vector.

local d = pos:distance(target)

• other Vec2

Returns number

Vec2:lerp(other, t)

Returns the vector interpolated toward other by t (0 = this, 1 = other).

local mid = a:lerp(b, 0.5)

• other Vec2
• t number 0..1

Returns Vec2

Vec2:copy()

Returns a new vector with the same components.

local start = pos:copy()

Returns Vec2

Vec2:unpack()

The components as values: local x, y = v:unpack().

local x, y = Vec2(3, 4):unpack()

Returns number …

Vec2:angle()

The angle of the vector in degrees (0 = right, 90 = down).

local deg = (target - pos):angle(); self.node:set_rotation(deg)

Returns number

Vec2:rotated(degrees)

The vector rotated by degrees (clockwise on screen).

local spread = Vec2.RIGHT:rotated(15) * 300

• degrees number

Returns Vec2

Vec3

A 3D vector: v.x, v.y, v.z (also v[1]…); + - * / with a vector or a number.

Field	Type
x	number
y	number
z	number

Vec3:length()

Returns the vector’s length (magnitude).

local len = Vec3(1, 2, 2):length()

Returns number

Vec3:length_squared()

Returns the squared length, cheaper than length() for comparisons.

local len2 = Vec3(1, 2, 3):length_squared()

Returns number

Vec3:normalized()

A vector of length 1 in the same direction (zero stays zero).

local axis = Vec3(1, 2, 3):normalized()

Returns Vec3

Vec3:dot(other)

Returns the dot product with another vector.

local d = Vec3(1, 0, 0):dot(Vec3(0, 1, 0))

• other Vec3

Returns number

Vec3:distance(other)

Returns the distance to another vector.

local d = Vec3(0, 0, 0):distance(Vec3(1, 2, 2))

• other Vec3

Returns number

Vec3:lerp(other, t)

Returns the vector interpolated toward other by t (0 = this, 1 = other).

local mid = Vec3(0, 0, 0):lerp(Vec3(10, 20, 30), 0.5)

• other Vec3
• t number 0..1

Returns Vec3

Vec3:copy()

Returns a new vector with the same components.

local backup = Vec3(1, 2, 3):copy()

Returns Vec3

Vec3:unpack()

The components as values: local x, y = v:unpack().

local x, y, z = Vec3(1, 2, 3):unpack()

Returns number …

Vec4

A 4D vector: v.x, v.y, v.z, v.w (also v[1]…); + - * / with a vector or a number.

Field	Type
x	number
y	number
z	number
w	number

Vec4:length()

Returns the vector’s length (magnitude).

local len = Vec4(1, 1, 1, 1):length()

Returns number

Vec4:length_squared()

Returns the squared length, cheaper than length() for comparisons.

local len2 = Vec4(1, 2, 3, 4):length_squared()

Returns number

Vec4:normalized()

A vector of length 1 in the same direction (zero stays zero).

local q = Vec4(0, 0, 1, 1):normalized()

Returns Vec4

Vec4:dot(other)

Returns the dot product with another vector.

local d = Vec4(1, 0, 0, 0):dot(Vec4(0.5, 0.5, 0, 0))

• other Vec4

Returns number

Vec4:distance(other)

Returns the distance to another vector.

local d = Vec4(1, 0, 0, 1):distance(Vec4(0, 1, 0, 1))

• other Vec4

Returns number

Vec4:lerp(other, t)

Returns the vector interpolated toward other by t (0 = this, 1 = other).

local c = Vec4(1, 0, 0, 1):lerp(Vec4(0, 0, 1, 1), t)

• other Vec4
• t number 0..1

Returns Vec4

Vec4:copy()

Returns a new vector with the same components.

local backup = Vec4(1, 2, 3, 4):copy()

Returns Vec4

Vec4:unpack()

The components as values: local x, y = v:unpack().

local x, y, z, w = Vec4(1, 0, 0, 1):unpack()

Returns number …

Vec2Constructor

Makes a Vec2: Vec2(3, 4); constants Vec2.ZERO, ONE, UP, DOWN, LEFT, RIGHT.

Field	Type
ZERO	Vec2
ONE	Vec2
UP	Vec2
DOWN	Vec2
LEFT	Vec2
RIGHT	Vec2
new	fun(x?:	number, y?: number): Vec2

Vec3Constructor

Makes a Vec3: Vec3(1, 2, 3).

Field	Type
new	fun(x?:	number, y?: number, z?: number): Vec3

Vec4Constructor

Makes a Vec4: Vec4(1, 2, 3, 4).

Field	Type
new	fun(x?:	number, y?: number, z?: number, w?: number): Vec4

ScriptInstanceBase

Field	Type
node	Node	The node this script is attached to.
properties	table<string,	any> Custom exported script properties table.
ready?	fun(self:	self) Lifecycle callback invoked when the node enters the scene.
update?	fun(self:	self, dt: number) Lifecycle callback invoked each frame with delta time in seconds.
on_destroy?	fun(self:	self) Lifecycle callback invoked when the node is destroyed.
on_entered_tree?	fun(self:	self) Event: the node joined the scene.
on_exited_tree?	fun(self:	self) Event: the node is being removed.
on_child_added?	fun(self:	self, child: Node) Event: a child was added.
on_child_removed?	fun(self:	self, child: Node) Event: a child was removed.
on_timeout?	fun(self:	self) Event (TimerNode): the duration elapsed.
on_tick?	fun(self:	self, elapsed: number) Event (TimerNode): each frame while running.
on_body_entered?	fun(self:	self, other: Node) Event (AreaNode): a body entered.
on_body_exited?	fun(self:	self, other: Node?) Event (AreaNode): a body left.
on_collision_started?	fun(self:	self, other: Node) Event (bodies): contact began.
on_collision_ended?	fun(self:	self, other: Node) Event (bodies): contact ended.
on_hit_started?	fun(self:	self, other: Node) Event (RaycastNode): the ray hit a node.
on_hit_ended?	fun(self:	self, other: Node) Event (RaycastNode): the ray stopped hitting it.
on_animation_finished?	fun(self:	self, name: string?) Event: a non-looping animation ended.
on_state_changed?	fun(self:	self, state: string) Event (StateMachineNode): entered a state.
on_finished?	fun(self:	self) Event (Sound/Music): playback ended.
on_clicked?	fun(self:	self) Event (UIButtonNode): clicked.
on_value_changed?	fun(self:	self, value: any) Event (UI inputs): the value changed.
on_submitted?	fun(self:	self, text: string) Event (UITextInputNode): Enter pressed.
on_selected?	fun(self:	self, index: integer) Event (UI lists): selection changed.
on_gamepad_connected?	fun(self:	self, player: integer, name: string) Event (every script): a player’s gamepad was plugged in.
on_gamepad_disconnected?	fun(self:	self, player: integer) Event (every script): a player’s gamepad was unplugged.