Lua API¶

This section is a reference guide for the Lua scripting interface in IOLITE.

Note

The Lua API in IOLITE is provided via a native C++ plugin and is freely available in our GitHub repository. Have a look at the plugin to inspect the underlying implementation of the exposed functions or to customize/extend the implementation.

IOLITE Lua API header file¶

The IOLITE Lua API header file can be used to add auto-completion to the code editor of your choice. This has been tested in Visual Studio Code using the latest version of the Lua extension.

Click the following link to download the latest version of the header file and drop it somewhere close to your scripts:

iolite_api.lua

Utils¶

Various utility functions.

Utils.execute(script)¶

Params:

script (string) - The Lua script source to execute.

Returns:

value (any) - The result of the executed script.

Executes the provided string as a Lua script.

Utils.load(script_name)¶

Params:

script_name (string) - The name of the script to load as a module (without the file extension).

Returns:

value (any) - The result of the executed script.

Executes the script with the given name.

Utils.require(script_name)¶

Params:

script_name (string) - The name of the script to execute (without the file extension).

Returns:

value (any) - The result of the executed script.

Executes the script with the given name. Executed once for each script. Successive calls return the cached script result.

Globals¶

Provides various global functions and types.

InvalidRef()¶

Returns:

value (Ref) - The invalid ref.

Creates an invalid ref.

Vec2(x)¶

Params:

x (number) - The scalar value to set the components to.

Returns:

value (Vec2) - The new vector.

Initializes a new Vec2.

Vec2(vec)¶

Params:

vec (Vec2) - The vector to copy from.

Returns:

value (Vec2) - The new vector.

Initializes a new Vec2.

Vec2(x, y)¶

Params:

x (number) - First component.
y (number) - Second component.

Returns:

value (Vec2) - The new vector.

Initializes a new Vec2.

UVec2(x)¶

Params:

x (number) - The scalar value to set the components to.

Returns:

value (UVec2) - The new vector.

Initializes a new UVec2.

UVec2(vec)¶

Params:

vec (UVec2) - The vector to copy from.

Returns:

value (UVec2) - The new vector.

Initializes a new UVec2.

UVec2(x, y)¶

Params:

x (number) - First component.
y (number) - Second component.

Returns:

value (UVec2) - The new vector.

Initializes a new UVec2.

IVec2(x)¶

Params:

x (number) - The scalar value to set the components to.

Returns:

value (IVec2) - The new vector.

Initializes a new IVec2.

IVec2(vec)¶

Params:

vec (IVec2) - The vector to copy from.

Returns:

value (IVec2) - The new vector.

Initializes a new IVec2.

IVec2(x, y)¶

Params:

x (number) - First component.
y (number) - Second component.

Returns:

value (IVec2) - The new vector.

Initializes a new IVec2.

Vec3(x)¶

Params:

x (number) - The scalar value to set the components to.

Returns:

value (Vec3) - The new vector.

Initializes a new Vec3.

Vec3(vec)¶

Params:

vec (Vec3) - The vector to copy from.

Returns:

value (Vec3) - The new vector.

Initializes a new Vec3.

Vec3(x, y, z)¶

Params:

x (number) - First component.
y (number) - Second component.
z (number) - Third component.

Returns:

value (Vec3) - The new vector.

Initializes a new Vec3.

UVec3(x)¶

Params:

x (number) - The scalar value to set the components to.

Returns:

value (UVec3) - The new vector.

Initializes a new UVec3.

UVec3(vec)¶

Params:

vec (UVec3) - The vector to copy from.

Returns:

value (UVec3) - The new vector.

Initializes a new UVec3.

UVec3(x, y, z)¶

Params:

x (number) - First component.
y (number) - Second component.
z (number) - Third component.

Returns:

value (UVec3) - The new vector.

Initializes a new UVec3.

U16Vec3(x)¶

Params:

x (number) - The scalar value to set the components to.

Returns:

value (U16Vec3) - The new vector.

Initializes a new U16Vec3.

U16Vec3(vec)¶

Params:

vec (U16Vec3) - The vector to copy from.

Returns:

value (U16Vec3) - The new vector.

Initializes a new U16Vec3.

U16Vec3(x, y, z)¶

Params:

x (number) - First component.
y (number) - Second component.
z (number) - Third component.

Returns:

value (U16Vec3) - The new vector.

Initializes a new U16Vec3.

U8Vec3(x)¶

Params:

x (number) - The scalar value to set the components to.

Returns:

value (U8Vec3) - The new vector.

Initializes a new U8Vec3.

U8Vec3(vec)¶

Params:

vec (U8Vec3) - The vector to copy from.

Returns:

value (U8Vec3) - The new vector.

Initializes a new U8Vec3.

U8Vec3(x, y, z)¶

Params:

x (number) - First component.
y (number) - Second component.
z (number) - Third component.

Returns:

value (U8Vec3) - The new vector.

Initializes a new U8Vec3.

IVec3(x)¶

Params:

x (number) - The scalar value to set the components to.

Returns:

value (IVec3) - The new vector.

Initializes a new IVec3.

IVec3(vec)¶

Params:

vec (IVec3) - The vector to copy from.

Returns:

value (IVec3) - The new vector.

Initializes a new IVec3.

IVec3(x, y, z)¶

Params:

x (number) - First component.
y (number) - Second component.
z (number) - Third component.

Returns:

value (IVec3) - The new vector.

Initializes a new IVec3.

Vec4(x)¶

Params:

x (number) - The scalar value to set the components to.

Returns:

value (Vec4) - The new vector.

Initializes a new Vec4.

Vec4(vec)¶

Params:

vec (Vec4) - The vector to copy from.

Returns:

value (Vec4) - The new vector.

Initializes a new Vec4.

Vec4(x, y, z, w)¶

Params:

x (number) - First component.
y (number) - Second component.
z (number) - Third component.
w (number) - Fourth component.

Returns:

value (Vec4) - The new vector.

Initializes a new Vec4.

UVec4(x)¶

Params:

x (number) - The scalar value to set the components to.

Returns:

value (UVec4) - The new vector.

Initializes a new UVec4.

UVec4(vec)¶

Params:

vec (UVec4) - The vector to copy from.

Returns:

value (UVec4) - The new vector.

Initializes a new UVec4.

UVec4(x, y, z, w)¶

Params:

x (number) - First component.
y (number) - Second component.
z (number) - Third component.
w (number) - Fourth component.

Returns:

value (UVec4) - The new vector.

Initializes a new UVec4.

IVec4(x)¶

Params:

x (number) - The scalar value to set the components to.

Returns:

value (IVec4) - The new vector.

Initializes a new IVec4.

IVec4(vec)¶

Params:

vec (IVec4) - The vector to copy from.

Returns:

value (IVec4) - The new vector.

Initializes a new IVec4.

IVec4(x, y, z, w)¶

Params:

x (number) - First component.
y (number) - Second component.
z (number) - Third component.
w (number) - Fourth component.

Returns:

value (IVec4) - The new vector.

Initializes a new IVec4.

Quat(x)¶

Params:

x (number) - The scalar value to set the first component to.

Returns:

value (Quat) - The new quaternion.

Initializes a new Quat.

Quat(quat)¶

Params:

quat (Quat) - The quaternion to copy from.

Returns:

value (Quat) - The new quaternion.

Initializes a new Quat.

Quat(w, x, y, z)¶

Params:

w (number) - First component.
x (number) - Second component.
y (number) - Third component.
z (number) - Fourth component.

Returns:

value (Quat) - The new quaternion.

Initializes a new Quat.

Sphere(center, radius)¶

Params:

center (Vec3) - The center of the sphere.
radius (number) - The radius of the sphere.

Returns:

value (Sphere) - The new sphere.

Initializes a new Sphere.

AABB(center, half_extent)¶

Params:

center (Vec3) - The center of the AABB.
half_extent (Vec3) - The half extent of the AABB.

Returns:

value (AABB) - The new AABB.

Initializes a new AABB (axis aligned bounding box).

UIAnchor(anchor, offset)¶

Params:

anchor (number) - The position in [0, 1] relative to the parent transform.
offset (number) - The absolute offset (in px).

Returns:

value (UIAnchor) - The new anchor.

Initializes a new UI anchor.

UIAnchorOffsets(left, right, top, bottom)¶

Params:

left (number) - Absolute offset (in px) to the left anchor.
right (number) - Absolute offset (in px) to the right anchor.
top (number) - Absolute offset (in px) to the top anchor.
bottom (number) - Absolute offset (in px) to the bottom anchor.

Returns:

value (UIAnchor) - The new set of anchor offsets.

Initializes a new set of UI anchor offsets.

class Handle¶: Handles are used to reference elements of the various subsystems.

class PropertyDesc¶

Variables:

name (string)
type (string)

Description of a property.

class Ref¶: Reference to entities, components and resources.

class Variant¶: Special data type that can contain different types of data.

class Vec2¶

Variables:

x (number)
y (number)

A vector storing two floating point components.

class UVec2¶

Variables:

x (number)
y (number)

A vector storing two unsigned integer components.

class IVec2¶

Variables:

x (number)
y (number)

A vector storing two signed integer components.

class Vec3¶

Variables:

x (number)
y (number)
z (number)

A vector storing three floating point components.

class UVec3¶

Variables:

x (number)
y (number)
z (number)

A vector storing three unsigned integer components.

class U16Vec3¶

Variables:

x (number)
y (number)
z (number)

A vector storing three unsigned integer components.

class U8Vec3¶

Variables:

x (number)
y (number)
z (number)

A vector storing three unsigned integer components.

class IVec3¶

Variables:

x (number)
y (number)
z (number)

A vector storing three signed integer components.

class Vec4¶

Variables:

x (number)
y (number)
z (number)
w (number)

A vector storing four floating point components.

class UVec4¶

Variables:

x (number)
y (number)
z (number)
w (number)

A vector storing four unsigned integer components.

class IVec4¶

Variables:

x (number)
y (number)
z (number)
w (number)

A vector storing four signed integer components.

class Quat¶

Variables:

w (number)
x (number)
y (number)
z (number)

A quaternion with four floating point components.

class Sphere¶

Variables:

center (Vec3)
radius (number)

A sphere defined by a center and radius.

class AABB¶

Variables:

center (Vec3)
half_extent (Vec3)

A axis aligned bounding box (AABB) defined by a center and half extent.

class HeightmapPixel¶: A single pixel used for generating heightmaps.

class PathSettings¶

Variables:

capsule_radius (number) – The radius of the agent’s capsule.
capsule_half_height (number) – The half height of the agent’s capsule.
step_height (number) – The maximum step height an agent can take.
cell_size (number) – The size of the cells used for the voxelization.

Settings used when calculating paths via the Pathfinding related functions.

class AnimationDesc¶

Variables:

animation_name (string) – The name of the animation to play.
play_speed (number) – The play speed factor (defaults to 1).
blend_weight (number) – The blend weight (defaults to 1).
blend_in_out_duration (number) – The duration (in seconds) to blend in and out.
priority (number) – The priority. Animations with a higher priority are applied on top.
delay (number) – The delay (in seconds) before the animation starts playing.
looping (boolean) – Set to the if the animation should loop
restore_when_finished (boolean) – Set to the true to restore the initial node transforms when the animation is finished.

Describes the animation to play via the animation system.

class PhysicsContactEvent¶

Variables:

type (string) – The type name.
data (PhysicsContactEventData) – The data of the contact event.

Physics event fired when contacts between two shapes are detected.

class PhysicsContactEventData¶

Variables:

entity0 (Ref) – The first entity in contact.
entity1 (Ref) – The second entity in contact.
pos (Vec3) – The position of the contact.
impulse (Vec3) – The impulse of the contact.
type (string) – The type of the contact. Either “touch_found”, “touch_lost”, “trigger_touch_found”, or “trigger_touch_lost”.

The data for a single physics contact event.

class UserEvent¶

Variables:

type (string) – The type name.
data (UserEventData) – The data of this event.

Custom user event fired via the Event table interface.

class UserEventData¶

Variables:

source_entity (Ref) – The source entity of this event.
variants (table) – The variant payload of this event.

The data for a single user event.

class UIAnchor¶: Defines an anchor used for creating (rectangle) transforms in the UI system.

class UIAnchorOffsets¶: Defines a set of anchor offsets used for creating (rectangle) transforms in the UI system.

class UIRect¶

Variables:

pos (Vec2)
extent (Vec2)

A rectangle defined by a position and extent.

class KeyState¶

Variables:

kReleased (number) – The key is released.
kPressed (number) – The key is pressed.
kClicked (number) – The key has been clicked (pressed and released).

The different states a key can have.

class Key¶

Variables:

kUp (number)
kDown (number)
kLeft (number)
kRight (number)
kA (number)
kB (number)
kC (number)
kD (number)
kE (number)
kF (number)
kG (number)
kH (number)
kI (number)
kJ (number)
kK (number)
kL (number)
kM (number)
kN (number)
kO (number)
kP (number)
kQ (number)
kR (number)
kS (number)
kT (number)
kU (number)
kV (number)
kW (number)
kX (number)
kY (number)
kZ (number)
k0 (number)
k1 (number)
k2 (number)
k3 (number)
k4 (number)
k5 (number)
k6 (number)
k7 (number)
k8 (number)
k9 (number)
kF1 (number)
kF2 (number)
kF3 (number)
kF4 (number)
kF5 (number)
kF6 (number)
kF7 (number)
kF8 (number)
kF9 (number)
kF10 (number)
kF11 (number)
kF12 (number)
kDel (number)
kBackspace (number)
kTab (number)
kMouseLeft (number)
kMouseRight (number)
kMouseMiddle (number)
kShift (number)
kAlt (number)
kCtrl (number)
kSpace (number)
kEscape (number)
kReturn (number)
kNumPlus (number)
kNumMinus (number)
kNum0 (number)
kNum1 (number)
kNum2 (number)
kNum3 (number)
kNum4 (number)
kNum5 (number)
kNum6 (number)
kNum7 (number)
kNum8 (number)
kNum9 (number)
kControllerButtonA (number)
kControllerButtonY (number)
kControllerButtonB (number)
kControllerButtonX (number)
kAny (number)

The different keys available.

class Axis¶

Variables:

kLeftX (number) – Left stick x-axis.
kLeftY (number) – Left stick y-axis.
kRightX (number) – Right stick x-axis.
kRightY (number) – Right stick y-axis.
kTriggerLeft (number) – Left trigger.
kTriggerRight (number) – Right trigger.

The different axes for controller input handling.

Ref¶

Functions to interact with refs.

Ref.get_type_id(ref)¶

Params:

ref (Ref) - The ref.

Returns:

value (number) - The ID of the type referenced.

Returns the ID of the type referenced.

Ref.is_valid(ref)¶

Params:

ref (Ref) - The ref.

Returns:

value (boolean) - True if the given ref is valid.

Returns the ID of the type referenced.

Ref.get_id(ref)¶

Params:

ref (Ref) - The ref.

Returns:

value (number) - The ID of the referenced resource.

Returns the unique ID of the referenced resource.

Variant¶

Functions to interact with variants.

Variant.from_float(value)¶

Params:

value (number) - The floating point value to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing a single floating point value.

Variant.from_int(value)¶

Params:

value (number) - The integer value to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing a single integer value.

Variant.from_uint(value)¶

Params:

value (number) - The unsigned integer value to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing a single unsigned integer value.

Variant.from_uint8(value)¶

Params:

value (number) - The unsigned integer value to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing a single 8-bit unsigned integer value.

Variant.from_uint16(value)¶

Params:

value (number) - The unsigned integer value to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing a single 16-bit unsigned integer value.

Variant.from_string(value)¶

Params:

value (string) - The string to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing a string.

Variant.from_vec2(value)¶

Params:

value (Vec2) - The vector to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing a vector with two components.

Variant.from_vec3(value)¶

Params:

value (Vec3) - The vector to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing a vector with three components.

Variant.from_vec4(value)¶

Params:

value (Vec4) - The vector to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing a vector with four components.

Variant.from_quat(value)¶

Params:

value (Quat) - The quternion to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing a quaternion with four components.

Variant.from_ivec2(value)¶

Params:

value (IVec2) - The vector to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing an integer vector with two components.

Variant.from_ivec3(value)¶

Params:

value (IVec3) - The vector to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing an integer vector with three components.

Variant.from_ivec4(value)¶

Params:

value (IVec4) - The vector to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing an integer vector with fours components.

Variant.from_uvec2(value)¶

Params:

value (UVec2) - The vector to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing an unsigned integer vector with two components.

Variant.from_uvec3(value)¶

Params:

value (UVec3) - The vector to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing an unsigned integer vector with three components.

Variant.from_u8vec3(value)¶

Params:

value (U8Vec3) - The vector to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing an 8-bit unsigned integer vector with three components.

Variant.from_u16vec3(value)¶

Params:

value (U16Vec3) - The vector to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing an 16-bit unsigned integer vector with three components.

Variant.from_uvec4(value)¶

Params:

value (UVec4) - The vector to set.

Returns:

value (Variant) - The new variant.

Creates a new variant storing an unsigned integer vector with fours components.

Variant.get_float(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (number) - The floating point value.

Returns the underlying floating point value.

Variant.get_int(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (number) - The integer value.

Returns the underlying integer value.

Variant.get_uint(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (number) - The unsigned integer value.

Returns the underlying unsigned integer value.

Variant.get_uint8(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (number) - The unsigned integer value.

Returns the underlying 8-bit unsigned integer value.

Variant.get_uint16(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (number) - The unsigned integer value.

Returns the underlying 16-bit unsigned integer value.

Variant.get_string(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (number) - The string.

Returns the underlying string.

Variant.get_vec2(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (Vec2) - The vector.

Returns the underlying two-component vector.

Variant.get_vec3(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (Vec3) - The vector.

Returns the underlying three-component vector.

Variant.get_vec4(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (Vec4) - The vector.

Returns the underlying four-component vector.

Variant.get_quat(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (Quat) - The quaternion.

Returns the underlying four-component quaternion.

Variant.get_ivec2(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (IVec2) - The vector.

Returns the underlying two-component integer vector.

Variant.get_ivec3(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (IVec3) - The vector.

Returns the underlying three-component integer vector.

Variant.get_ivec4(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (IVec4) - The vector.

Returns the underlying four-component integer vector.

Variant.get_uvec2(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (UVec2) - The vector.

Returns the underlying two-component unsigned integer vector.

Variant.get_uvec3(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (UVec3) - The vector.

Returns the underlying three-component unsigned integer vector.

Variant.get_u8vec3(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (U8Vec3) - The vector.

Returns the underlying three-component 8-bit unsigned integer vector.

Variant.get_u16vec3(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (U16Vec3) - The vector.

Returns the underlying three-component 16-bit unsigned integer vector.

Variant.get_uvec4(variant)¶

Params:

variant (Variant) - The variant to retrieve from.

Returns:

value (UVec4) - The vector.

Returns the underlying four-component unsigned integer vector.

Math Constants¶

Provides various useful constants.

class Math¶

Variables:

pi (number) – Pi
half_pi (number) – Pi / 2
two_pi (number) – Pi * 2

Various math related constants.

Math General¶

General math related functions.

Math.load()¶: Loads all functions and types for this scripting interface.

Math.pow(x, y)¶

Params:

x (number) - The base.
y (number) - The exponent.

Returns:

value (number) - The result of x raised to power y.

Calculates x raised to the power y.

Math.sqrt(x)¶

Params:

x (number) - The input value.

Returns:

value (number) - The square root of x.

Calculates the square root of x.

Math.exp(x)¶

Params:

x (number) - The exponent.

Returns:

value (number) - The result of e raised to the power x.

Calculates e (Euler’s number) raised to the power x.

Math.abs(x)¶

Params:

x (number) - The input value.

Returns:

value (number) - The absolute value of x.

Calculates the absolute value of x.

Math.clamp(x, min, max)¶

Params:

x (number) - The value to clamp.
min (number) - The minimum.
max (number) - The maximum.

Returns:

value (number) - The result of x clamped to [min, max].

Clamps x to the provided minimum and maximum.

Math.min(x, y)¶

Params:

x (number) - The first input value.
y (number) - The second input value.

Returns:

value (number) - The minimum of x and y.

Calculates the minimum of x and y.

Math.max(x, y)¶

Params:

x (number) - The first input value.
y (number) - The second input value.

Returns:

value (number) - The maximum of x and y.

Calculates the maximum of x and y.

Math.floor(x)¶

Params:

x (number) - The input value.

Returns:

value (number) - The largest integer value not greater than x.

Calculates the largest integer number to greater than x.

Math.ceil(x)¶

Params:

x (number) - The input value.

Returns:

value (number) - The smallest integer value not less than x.

Calculates the smallest integer number not less than x.

Math.round(x)¶

Params:

x (number) - The input value.

Returns:

value (number) - The rounded value.

Calculates the nearest integer value to x, rounding halfway cases away from zero.

Math.fract(x)¶

Params:

x (number) - The input value.

Returns:

value (number) - The fractional part of x.

Returns the fractional part of x, calculated as x - floor(x).

Math.trunc(x)¶

Params:

x (number) - The input value.

Returns:

value (number) - The truncated value.

Calculates a value equal to the nearest integer to x whose absolute value is not larger than the absolute value of x.

Math Trigonometry¶

Trigonometric math functions.

Math.radians(x)¶

Params:

x (number) - Input value in degrees.

Returns:

value (number) - Input value converted to radians.

Convers the provided value in degrees to radians.

Math.degrees(angle)¶

Params:

angle (number) - Input value in radians.

Returns:

value (number) - Input value converted to degrees.

Convers the provided value in radians to degrees.

Math.sin(angle)¶

Params:

angle (number) - The input angle (in radians).

Returns:

value (number) - The sine of angle.

Calculates the sine of angle.

Math.asin(x)¶

Params:

x (number) - The input value.

Returns:

value (number) - The arc sine of x (in radians).

Calculates the arc sine of x.

Math.cos(angle)¶

Params:

angle (number) - The input angle.

Returns:

value (number) - The cosine of angle.

Calculates the cosine of angle.

Math.acos(x)¶

Params:

x (number) - The input value.

Returns:

value (number) - The arc cosine of x (in radians).

Calculates the arc cosine of x.

Math.tan(angle)¶

Params:

angle (number) - The input angle.

Returns:

value (number) - The tangent of angle.

Calculates the tangent of angle.

Math.atan(x)¶

Params:

x (number) - The input value.

Returns:

value (number) - The arc tangent of x.

Calculates the arc tangent of x.

Math.atan(y, x)¶

Params:

y (number) - The first input value.
x (number) - The second input value.

Returns:

value (number) - The arc tangent of y over x.

Calculates the arc tangent of y over x.

Math Interpolation¶

Collection of functions to interpolate values.

Math.lerp(x, y, a)¶

Params:

x (number or Vec2 or Vec3 or Vec4) - The first input value.
y (number or Vec2 or Vec3 or Vec4) - The second input value.
a (number) - The value to use to interpolate between x and y.

Returns:

value (number or Vec2 or Vec3 or Vec4) - The interpolated value.

Linearly interpolates between x and y.

Math.slerp(x, y, a)¶

Params:

x (Quat) - The first input value.
y (Quat) - The second input value.
a (number) - The value to use to interpolate between x and y.

Returns:

value (Quat) - The interpolated value.

Spherically linearly interpolates between x and y.

Math Vectors¶

Collection of functions to work with vectors.

Math.vec_get_component(x, idx)¶

Params:

x (Vec2 or Vec3 or Vec4) - The input value.
idx (number) - The index of the component to retrieve.

Returns:

value (number) - The select4ed component of x.

Selects the component of the vector using the provided index.

Math.vec_mul(x, y)¶

Params:

x (Vec2 or Vec3 or Vec4) - The first input value.
y (Vec2 or Vec3 or Vec4) - The second input value.

Returns:

value (Vec2 or Vec3 or Vec4) - The result of x * y.

Multiplies the provided vectors.

Math.vec_scale(s, x)¶

Params:

s (number) - The scalar value.
x (Vec2 or Vec3 or Vec4) - The vector to scale.

Returns:

value (Vec2 or Vec3 or Vec4) - The result of s*x.

Scales the vector by the given scalar

Math.vec_div(x, y)¶

Params:

x (Vec2 or Vec3 or Vec4) - The first input value.
y (Vec2 or Vec3 or Vec4) - The second input value.

Returns:

value (Vec2 or Vec3 or Vec4) - The result of x/y.

Divides the first vector by the second.

Math.vec_add(x, y)¶

Params:

x (Vec2 or Vec3 or Vec4) - The first input value.
y (Vec2 or Vec3 or Vec4) - The second input value.

Returns:

value (Vec2 or Vec3 or Vec4) - The result of x+y.

Adds the provided vectors.

Math.vec_sub(x, y)¶

Params:

x (Vec2 or Vec3 or Vec4) - The first input value.
y (Vec2 or Vec3 or Vec4) - The second input value.

Returns:

value (Vec2 or Vec3 or Vec4) - The result of x-y.

Subtracts the provided vectors.

Math.vec_length(x)¶

Params:

x (Vec2 or Vec3 or Vec4) - The input value.

Returns:

value (number) - The length of the vector, calculated as sqrt(x.x*x.x + x.y*x.y + x.z*x.z).

Calculates the length of the provided vector

Math.vec_length2(x)¶

Params:

x (Vec2 or Vec3 or Vec4) - The input value.

Returns:

value (number) - The length of the vector, calculated as x.x*x.x + x.y*x.y + x.z*x.z.

Calculates the squared length of the provided vector

Math.vec_distance(x, y)¶

Params:

x (Vec2 or Vec3 or Vec4) - The first input value.
y (Vec2 or Vec3 or Vec4) - The second input value.

Returns:

value (number) - The distance between the vectors, calculated as vec_length(vec_sub(y, x)).

Calculates the distance between the provided vectors.

Math.vec_distance2(x, y)¶

Params:

x (Vec2 or Vec3 or Vec4) - The first input value.
y (Vec2 or Vec3 or Vec4) - The second input value.

Returns:

value (number) - The distance between the vectors, calculated as vec_length2(vec_sub(y, x)).

Calculates the squared distance between the provided vectors.

Math.vec_normalize(x)¶

Params:

x (Vec2 or Vec3 or Vec4) - The input value.

Returns:

value (Vec2 or Vec3 or Vec4) - The normalized vector of x, calculate as vec_scale(1.0 / vec_length(x), x).

Normalizes the provided vector.

Math.vec_dot(x, y)¶

Params:

x (Vec2 or Vec3 or Vec4) - The first input value.
y (Vec2 or Vec3 or Vec4) - The second input value.

Returns:

value (number) - The dot product of x and y.

Calculates the dot product of the provided vectors.

Math.vec_cross(x, y)¶

Params:

x (Vec3) - The first input value.
y (Vec3) - The second input value.

Returns:

value (Vec3) - The cross product of x and y.

Calculates the cross product of the provided vectors.

Math Quaternions¶

Collection of functions to work with quaternions.

Math.quat_mul(x, y)¶

Params:

x (Quat) - The first input value.
y (Quat) - The second input value.

Returns:

value (Quat) - The result of x*y.

Multiplies the provided quaternions

Math.quat_rotate(x, y)¶

Params:

x (Quat) - The quaternion to rotate by.
y (Vec3) - The vector to rotate.

Returns:

value (Vec3) - The rotated vector.

Rotates the provided vector by the given quaternion.

Math.quat_inverse(x)¶

Params:

x (Quat) - The quaternion to invert.

Returns:

value (Quat) - The inverse of the quaternion.

Calculate the inverse of the provided quaternion.

Math.quat_normalize(x)¶

Params:

x (Quat) - The quaternion to normalize.

Returns:

value (Quat) - The normalized quaternion.

Normalizes the provided quaternion.

Math.quat_look_at(dir, up)¶

Params:

dir (Vec3) - The direction to look into.
up (Vec3) - The up vector to use.

Returns:

value (Quat) - Quaternion “looking” into the provided direction.

Calculates a quaternion “looking” into a specific direction.

Math.quat_from_angle_axis(angle, axis)¶

Params:

angle (number) - The angle.
axis (Vec3) - The axis of the rotation.

Returns:

value (Quat) - Quaternion rotating angle around axis.

Calculates a quaternion from the angle and axis.

Math.quat_to_euler_angles(x)¶

Params:

x (Quat) - The quaternion to convert.

Returns:

value (Vec3) - The Euler angles, pitch, yaw, and roll derived from the given Quaternion in radians.

Converts the provided quaternion to Euler angles.

Math.quat_from_euler_angles(angles)¶

Params:

angles (Vec3) - The Euler angles (in radians) to convert.

Returns:

value (Quat) - The quaternion constructed from the provided Euler angles.

Converts the provided Euler angles to a quaternion.

Math.quat_rotation(x, y)¶

Params:

x (Vec3) - The first vector.
y (Vec3) - The second vector.

Returns:

value (Quat) - Quaternion transforming vector to vector.y

Calculates a quaternion that transforms vector x to vector y.

Settings¶

Functions to interact with the global settings.

Settings.load()¶: Loads all functions and types for this scripting interface.

Settings.set_bool(name, value)¶

Params:

name (string) - The name of the setting.
value (boolean) - The value to set.

Sets the given setting to the provided boolean value.

Settings.set_uint(name, value)¶

Params:

name (string) - The name of the setting.
value (number) - The value to set.

Sets the given setting to the provided unsigned integer value.

Settings.set_float(name, value)¶

Params:

name (string) - The name of the setting.
value (number) - The value to set.

Sets the given setting to the provided floating point value.

Settings.get_bool(name)¶

Params:

name (string) - The name of the setting to retrieve.

Returns:

value (boolean) - The value of the setting.

Retrieves the given boolean setting.

Settings.get_uint(name)¶

Params:

name (string) - The name of the setting to retrieve.

Returns:

value (number) - The value of the setting.

Retrieves the given (unsigned) integer setting.

Settings.get_float(name)¶

Params:

name (string) - The name of the setting to retrieve.

Returns:

value (number) - The value of the setting.

Retrieves the given floating point setting.

Log¶

Functions to log to the console and log file.

Log.load()¶: Loads all functions and types for this scripting interface.

Log.log_info(s)¶

Params:

s (string) - The string to log.

Logs the given string as info.

Log.log_warning(s)¶

Params:

s (string) - The string to log.

Logs the given string as a warning.

Log.log_error(s)¶

Params:

s (string) - The string to log.

Logs the given string as an error.

Events¶

Functions for listening for custom user events and sending them with and without payloads.

Events.load()¶: Loads all functions and types for this scripting interface.

Events.register_event_listener(target_entity, event_type)¶

Params:

target_entity (Ref) - The target entity that should listen for events.
event_type (string) - The type of events to listen for.

Events.unregister_event_listener(target_entity, event_type)¶

Params:

target_entity (Ref) - The target entity listening for events.
event_type (string) - The type of events to stop listening for.

Unregister the given entity as a listener for the given event type.

Events.post_event(source_entity, event_type)¶

Params:

source_entity (Ref) - The entity the event is originating from.
event_type (string) - The type of the event to post.

Posts the given event type from the given source entity.

Events.post_event(source_entity, event_type, target_entities)¶

Params:

source_entity (Ref) - The entity the event is originating from.
event_type (string) - The type of the event to post.
target_entities (table) - List of target entities this event should be delivered to

Posts the given event type from the given source entity.

Events.post_event_with_payload(source_entity, event_type, variants)¶

Params:

source_entity (Ref) - The entity the event is originating from.
event_type (string) - The type of the event to post.
variants (table) - Array of variants serving as the payload for the event.

Posts the given event type from the given source entity with the provided payload of variants.

Events.post_event_with_payload(source_entity, event_type, variants, target_entities)¶

Params:

source_entity (Ref) - The entity the event is originating from.
event_type (string) - The type of the event to post.
variants (table) - Array of variants serving as the payload for the event.
target_entities (table) - List of target entities this event should be delivered to

Posts the given event type from the given source entity with the provided payload of variants.

UI¶

Functions to interact with the UI system.

UI.load()¶: Loads all functions and types for this scripting interface.

UI.draw_rect(color)¶

Params:

color (Vec4) - The color of the rectangle.

Draws a rectangle.

UI.draw_direct(color)¶

Params:

color (Vec4) - The color of the circle.

Draws a circle.

UI.draw_ngon(color, num_sides)¶

Params:

color (Vec4) - The color of the n-sided polygon.
num_sides (number) - The number of sided.

Draws a n-sided polygon.

UI.draw_image(name, tint)¶

Params:

name (string) - The name of the image to draw.
tint (Vec4) - The tint of the image.

Draws the image with the given name.

UI.get_image_size(name)¶

Params:

name (string) - The name of the image.

Returns:

value (Vec2) - The size of the image (in px).

Gets the size of the image (in px).

UI.draw_text(text, align_horizontal, align_vertical, flags)¶

Params:

text (string) - The text to draw.
align_horizontal (number) - The horizontal alignment.
align_vertical (number) - The vertical alignment.
flags (number) - The text flags.

Draws the text with the given options.

UI.calc_text_bounds(text, align_horizontal, align_vertical, flags)¶

Params:

text (string) - The text to compute the bounds for.
align_horizontal (number) - The horizontal alignment.
align_vertical (number) - The vertical alignment.
flags (number) - The text flags.

Returns:

value (Vec2) - The bounds for the text.

Calculates the bounds for the given text and options.

UI.get_last_text_bounds()¶

Returns:

value (Vec2) - The bounds for the text.

Returns the bounds of the text that was drawn last.

UI.push_transform(left, right, top, bottom, rotation)¶

Params:

left (UIAnchor) - Left anchor.
right (UIAnchor) - Right anchor.
top (UIAnchor) - Top anchor.
bottom (UIAnchor) - Bottom anchor.
rotation (number) - The rotation to apply.

Pushes the previous transform to the stack and activates the given one.

UI.push_transform_preset(preset, offsets, rotation)¶

Params:

preset (number) - The transform preset to use.
offsets (UIAnchorOffsets) - The offsets for each of the anchors.
rotation (number) - The rotation to apply.

Pushes the previous transform to the stack and activates the given one.

UI.pop_transform()¶: Pops the last transform off the stack and activates it.

UI.push_scale_offset_for_base_size(base_size, aspect_mode)¶

Params:

base_size (Vec2) - The base size.
aspect_mode (number) - The aspect mode to use.

Calculates the scale and offset for the given base size and according to the aspect mode.

UI.push_scale_offset(scale, offset)¶

Params:

scale (number) - The uniform scaling factor.
offset (Vec2) - The offset.

Pushes the scale and offset to the stack and activates the given parameters.

UI.pop_scale_offset()¶: Pops the last scale and offset from the stack and activates it.

UI.push_style_var_float(var, value)¶

Params:

var (number) - The style variation.
value (number) - The value to set.

Pushes the current style variation float value to the stack and sets the given one.

UI.push_style_var_vec4(var, value)¶

Params:

var (number) - The style variation.
value (Vec4) - The value to set.

Pushes the current style variation Vec4 value to the stack and sets the given one.

UI.pop_style_var()¶: Pops the last style variation from the stack and activates it.

UI.clip_children()¶: Clips the children of the current transform

UI.push_font_size(size)¶

Params:

size (number) - The font size (in px).

Pushes the current font size to the stack and sets the given one.

UI.pop_font_size()¶: Pops the last font size from the stack and activates it.

UI.intersects()¶: Returns true if the given position (in px) intersects the current transform.

Random¶

Collection of functions to calculate random values.

Random.load()¶: Loads all functions and types for this scripting interface.

Random.set_seed(seed)¶

Params:

seed (number) - The seed to set.

Sets the seed used for the underlying random number generator (RNG).

Random.rand_uint()¶

Returns:

value (number) - The random value.

Calculates a random (unsigned) integer value.

Random.rand_uint_min_max(min, max)¶

Params:

min (number) - The minimum random value to generate.
max (number) - The maximum random value to generate.

Returns:

value (number) - The random value.

Calculates a random (unsigned) integer value in the given interval.

Random.rand_float()¶

Returns:

value (number) - The random value.

Calculates a random floating point value in [0.0, 1.0].

Random.rand_float_min_max(min, max)¶

Params:

min (number) - The minimum random value to generate.
max (number) - The maximum random value to generate.

Returns:

value (number) - The random value.

Calculates a random floating point value in the given interval.

Entity¶

Functions to interact with entities.

Entity.load()¶: Loads all functions and types for this scripting interface.

Entity.get_type_id()¶

Returns:

value (number) - The type id for all entities.

Gets the type id for all entities.

Entity.is_alive(entity)¶

Params:

entity (Ref) - The entity to check.

Returns:

value (boolean) - True if the given entity is alive.

Returns whether the given entity is alive.

Entity.get_name(entity)¶

Params:

entity (Ref) - The entity to check.

Returns:

value (string) - The name of the given entity.

Returns the name of the given entity.

Entity.find_first_entity_with_name(name)¶

Params:

name (string) - The name of the entity to search for.

Returns:

value (Ref) - The entity with the given name. Ref is invalid if none was found.

Finds the first entity with the given name.

Entity.find_entities_with_name(name)¶

Params:

name (string) - The name of the entities to search for.

Returns:

value (table) - Table containing the entities with the given name.

Finds all entities with the given name and returns as table containg refs as result.

Save Data¶

Functions to interact with the save data system.

SaveData.load()¶: Loads all functions and types for this scripting interface.

SaveData.save_to_user_data(filename, node)¶

Params:

filename (string) - The filename to use (without the file extension).
node (Ref) - The node to save.

Stores the given node hierarchy using the given filename in the user data directory.

SaveData.load_from_user_data(filename)¶

Params:

filename (string) - The filename to load from (without the file extension).

Returns:

value (Ref) - The root node of the loaded hierarchy.

Loads the node hierarchy from the given file in the user data directory.

World¶

Collection of functions that operate on a global level.

World.load()¶: Loads all functions and types for this scripting interface.

World.get_root_node()¶

Returns:

value (Ref) - The root node of the world.

Returns the world’s root node.

World.get_world_name()¶

Returns:

value (string) - The name of the currently loaded world.

Returns the name of the currently loaded world.

World.load_world(name)¶

Params:

name (string) - The name of the world to load.

Loads the world with the given name.

World.save_world(name)¶

Params:

name (string) - The name of the world to save.

Saves the current world under the given name.

World.spawn_prefab(name)¶

Params:

name (string) - The name of the prefab to load.

Returns:

value (Ref) - The root node of the loaded prefab.

Loads the prefab with the given name.

World.spawn_prefab(name, parent, ignore_parent)¶

Params:

name (string) - The name of the prefab to load.
parent (Ref) - The parent node to attach the prefab to.
ignore_parent (boolean) - Set this to true to keep the local transform of the node and avoid undoing the parent transform first.

Returns:

value (Ref) - The root node of the loaded prefab.

Loads the prefab with the given name and attaches it to the given parent node.

World.get_current_time_factor()¶

Returns:

value (Ref) - The current time factor.

Returns the current time factor.

World.push_time_factor(factor)¶

Params:

factor (number) - The time factor to apply.

Pushes the current time factor to the stack and applies the given one. Use this to speed up or slow down the game time.

World.pop_time_factor()¶: Pops the last time factor from the stack and activates it.

World.radius_damage(position, radius, radius_damage_flags, group_mask, max_hardness)¶

Params:

position (Vec3) - The position.
radius (number) - The radius.
radius_damage_flags (number) - The flags to use.
group_mask (number) - Mask that defines the groups affected by this operation (set to -1 for all).
max_hardness (number) - Limits which voxels this damage operation can affect based on the hardness material parameter.

Applies damage to all voxel shapes in the given radius in the world.

World.calc_mouse_ray()¶

Returns:

origin (Vec3) - The origin of the ray (in world coordinates).
direction (Vec3) - The direction of the ray.

Calculates a ray that points at the current mouse position in the world.

World.highlight_node(node, color, outline)¶

Params:

node (Ref) - The node to highlight.
color (Vec4) - The color of the highlight.
outline (boolean) - Set to true to only highlight using an outline.

Enables a visual highlight (transparent overlay and/or outline) for the given node. Pass an invalid ref for the “node” parameter to remove the highlight.

Particle System¶

Functions to interact with the particle system.

ParticleSystem.load()¶: Loads all functions and types for this scripting interface.

ParticleSystem.spawn_particle_emitter(effect, position, lifetime, adjust_spawn_rate)¶

Params:

effect (string) - The name of the effect.
position (Vec3) - The spawn position of the emitter (in world coordinates).
lifetime (number) - The lifetime of the emitter in seconds.
adjust_spawn_rate (boolean) - Set to true to adjust the spawn rate based on the lifetime.

Returns:

value (Handle) - The handle for the emitter.

Spawns a new particle emitter.

ParticleSystem.despawn_particle_emitter(emitter)¶

Params:

emitter (Handle) - The emitter to despawn.

Despawns the given particle emitter.

ParticleSystem.attach_to_node(emitter, node)¶

Params:

emitter (Handle) - The emitter to attach.
node (Ref) - The node to attach the emitter to.

Attaches the given particle emitter to the provided node.

ParticleSystem.set_spawn_rate(emitter, spawn_rate)¶

Params:

emitter (Handle) - The emitter to adjust.
spawn_rate (number) - The spawn rate to set.

Sets the spawn rate for the given emitter.

ParticleSystem.set_position(emitter, position)¶

Params:

emitter (Handle) - The emitter to adjust.
position (Vec3) - The position to set.

Sets the position for the given emitter.

ParticleSystem.set_scale(emitter, position)¶

Params:

emitter (Handle) - The emitter to adjust.
position (number) - The scale to set.

Sets the scale for the given emitter.

ParticleSystem.set_emission_direction(emitter, direction)¶

Params:

emitter (Handle) - The emitter to adjust.
direction (Vec3) - The direction to set.

Sets the emission direction for the given emitter.

Input¶

Functions to interact with the input system.

Input.load()¶: Loads all functions and types for this scripting interface.

Input.get_key_state(key, player)¶

Params:

key (number) - The key to retrieve the state from (see Key table).
player (number) - The index of the player to retrieve the state from.

Returns:

value (number) - The current state of the key (see KeyState table).

Gets the current state of the given key.

Input.get_axis_state(axis, player)¶

Params:

axis (number) - The axis to retrieve the state from (see Axis table).
player (number) - The index of the player to retrieve the state from.

Returns:

value (number) - The current state of the axis in [0.0, 1.0].

Gets the current state of the given axis.

Input.get_mouse_pos()¶

Returns:

value (Vec2) - The position of the mouse.

Gets the current position of the mouse as pixel coordinates.

Input.get_mouse_pos_viewport()¶

Returns:

value (Vec2) - The position of the mouse in [0.0, 1.0].

Gets the current position of the mouse in the viewport.

Input.get_mouse_pos_relative()¶

Returns:

value (Vec2) - The delta movement of the mouse.

Gets the delta movement of the mouse in pixels.

Input.request_mouse_cursor()¶: Request the mouse cursor to show. Has to be called every frame to keep the mouse cursor visible.

Terrain¶

Functions to interact with the terrain generator.

Terrain.load()¶: Loads all functions and types for this scripting interface.

Terrain.generate_from_image(filename, palette, max_height, voxel_size)¶

Params:

filename (string) - The filename of the image.
palette (string) - The name of the palette to use.
max_height (number) - The maximum height of the terrain in world coordinates.
voxel_size (number) - The size of a single voxel.

Returns:

value (Ref) - The root node of the terrain.

Generates a new heightmap-based terrain from the given image.

Terrain.generate_from_data(data, size, palette, max_height, voxel_size)¶

Params:

data (table) - The heightmap data as a table made up of pixels (see Terrain.Pixel)
size (number) - The width/height of the terrain in pixels.
palette (string) - The name of the palette to use.
max_height (number) - The maximum height of the terrain in world coordinates.
voxel_size (number) - The size of a single voxel.

Returns:

value (Ref) - The root node of the terrain.

Generates a new heightmap-based terrain from the table.

Terrain.HeightmapPixel(height, grass_height, palette_index)¶

Params:

height (number) - The height in [0.0, 1.0].
grass_height (number) - The grass height in [0.0, 1.0].
palette_index (number) - The palette index.

Returns:

value (HeightmapPixel) - The new heightmap pixel.

Initializes a new pixel for the terrain generator.

Noise¶

Various procedural noise functions. Useful for, e.g., generating terrain, animations, etc.

Noise.load()¶: Loads all functions and types for this scripting interface.

Noise.simplex(x)¶

Params:

x (Vec4) - The coordinate to calculate the noise value at.

Returns:

value (number) - The noise value at the given coordinate.

Calculates perlin noise.

Noise.simplex(x)¶

Params:

x (Vec4) - The coordinate to calculate the noise value at.

Returns:

value (number) - The noise value at the given coordinate.

Calculates simplex noise.

Physics¶

Functions to interact with the various physics subsystems.

Physics.load()¶: Loads all functions and types for this scripting interface.

Physics.set_gravity(gravity)¶

Params:

gravity (Vec3) - The gravity to set.

Sets the global gravity (in meters per second).

Physics.get_gravity()¶

Returns:

value (Vec3) - The current global gravity.

Gets the global gravity (in meters per second).

Physics.overlap_sphere(position, radius, group_mask)¶

Params:

position (Vec3) - The position of the sphere in world coordinates.
radius (number) - The radius of the sphere.
group_mask (number) - Mask that defines the groups affected by this operation (set to -1 for all).

Returns:

hit (boolean) - True if a blocking hit is detected.
hit_entity (Ref) - The blocking entity. Invalid ref if no hit was detected.

Performs a sphere overlap test against the physics geometry.

Physics.sweep_sphere(position, radius, direction, distance, group_mask)¶

Params:

position (Vec3) - The position of the sphere in world coordinates.
radius (number) - The radius of the sphere.
direction (Vec3) - The direction to perform the sweep test in.
distance (number) - The distance to sweep.
group_mask (number) - Mask that defines the groups affected by this operation (set to -1 for all).

Returns:

hit (boolean) - True if a blocking hit is detected.
hit_distance (number) - The distance to the hit.
hit_position (Vec3) - The position of the hit.
hit_normal (Vec3) - The normal of the hit.
hit_entity (Ref) - The blocking entity. Invalid ref if no hit was detected.

Performs a sweeped sphere test against the physics geometry.

Physics.raycast(ray_origin, ray_direction, ray_distance, group_mask)¶

Params:

ray_origin (Vec3) - The origin of the ray in world coordinates.
ray_direction (Vec3) - The direction of ray.
ray_distance (number) - The maximum distance the ray should travel.
group_mask (number) - Mask that defines the groups affected by this operation (set to -1 for all).

Returns:

hit (boolean) - True if a blocking hit is detected.
hit_distance (number) - The distance to the hit.
hit_position (Vec3) - The position of the hit.
hit_normal (Vec3) - The normal of the hit.
hit_entity (Ref) - The blocking entity. Invalid ref if no hit was detected.

Performs a raycast again the physics geometry.

Debug Geometry¶

Functions to quickly draw geometry for debugging purposes.

DebugGeometry.load()¶: Loads all functions and types for this scripting interface.

DebugGeometry.draw_line(start_pos, end_pos, color, always_in_front)¶

Params:

start_pos (Vec3) - Line start position.
end_pos (Vec3) - Line end position.
color (Vec4) - The color of the line.
always_in_front (boolean) - Set to true to render the line in front of all the other geometry.

Draws a line.

DebugGeometry.draw_sphere(position, radius, color, always_in_front)¶

Params:

position (Vec3) - The center position of the sphere.
radius (number) - The radius of the sphere.
color (Vec4) - The color of the sphere.
always_in_front (boolean) - Set to true to render the sphere in front of all the other geometry.

Draws a sphere.

Sound¶

Functions to interact with the sound system.

Sound.load()¶: Loads all functions and types for this scripting interface.

Sound.play_sound_effect(name)¶

Params:

name (string) - The name of the sound effect to play.

Returns:

handle (Handle) - The handle of the created sound effect instance.

Starts playing the sound effect with the given name.

Sound.stop_sound_effect(handle)¶

Params:

handle (Handle) - The handle of the sound effect instance.

Stops playing the given sound effect instance.

Sound.set_position(handle, pos)¶

Params:

handle (Handle) - The handle of the sound effect instance.
pos (Vec3) - The position to set.

Sets the position of the given sound effect instance in the world. Used for spatial audio effects.

Sound.get_spectrum()¶

Returns:

spectrum (table) - Table containing the bins of the sound spectrum.

Retrieves the current snapshot of the sound spectrum.

Pathfinding¶

Functions to interact with the pathfinding system.

Pathfinding.load()¶: Loads all functions and types for this scripting interface.

Pathfinding.find_path(start_pos, end_pos, settings)¶

Params:

start_pos (Vec3) - The start position in the world.
end_pos (Vec3) - The end position in the world.
settings (PathSettings) - The path settings to use for finding the path.

Returns:

handle (Handle) - The handle of the path.

Starts finding a path.

Pathfinding.is_valid(handle)¶

Params:

handle (Handle) - The handle of the path.

Returns:

value (boolean) - True if the path is valid.

Checks if the given path is valid.

Pathfinding.reset_path(handle)¶

Params:

handle (Handle) - The handle of the path.

Resets the given path.

Pathfinding.destroy_path(handle)¶

Params:

handle (Handle) - The handle of the path.

Destroys the given path.

Pathfinding.is_path_found(handle)¶

Params:

handle (Handle) - The handle of the path.

Returns:

value (boolean) - True if a path has been found.

Check if a valid path has been found.

Pathfinding.get_next_position_on_path(handle)¶

Params:

handle (Handle) - The handle of the path.

Returns:

position (Vec3) - The next position on the path.
success (boolean) - True if a new position was retrieved.

Returns the next position on the path.

Pathfinding.draw_debug_geometry(handle, in_front)¶

Params:

handle (Handle) - The handle of the path.
in_front (boolean) - Set to true to draw the debug geometry in front of all other geometry.

Draws the internal debug geometry for the given path.

Pathfinding.draw_path(handle, color, in_front)¶

Params:

handle (Handle) - The handle of the path.
color (Vec4) - The color used for drawing.
in_front (boolean) - Set to true to draw the path in front of all other geometry.

Draws the path using lines.

Pathfinding.PathSettings()¶

Returns:

value (PathSettings) - The path settings.

Creates and initializes the settings for calculating a path to its default values.

Animation System¶

Functions to interact with the animation subsystem.

AnimationSystem.load()¶: Loads all functions and types for this scripting interface.

AnimationSystem.play_animation(node, desc)¶

Params:

node (Ref) - The node to start the animation on.
desc (AnimationDesc) - The animation description.

Returns:

value (Handle) - The animation instance handle.

Plays the given animation on the provided node and returns the animation instance handle.

AnimationSystem.stop_animation(instance)¶

Params:

instance (Handle) - The handle of the instance to stop.

Stops the provided animation instance.

AnimationSystem.stop_animations(node)¶

Params:

node (Ref) - The node to stop all animation instances on.

Stops all animation instances running on the provided node.

AnimationSystem.stop_all_animations(node)¶

Params:

node (Ref) - The node to stop all animation instances on.

Stops all animation instances running on the provided node and its hierarchy.

AnimationSystem.pause_animation(instance)¶

Params:

instance (Handle) - The handle of the instance to pause.

Pauses the provided animation instance.

AnimationSystem.resume_animation(instance)¶

Params:

instance (Handle) - The handle of the instance to resume.

Resumes the provided (paused) animation instance.

AnimationSystem.is_finished(instance)¶

Params:

instance (Handle) - The handle of the instance.

Returns:

value (boolean) - True if the animation is finished.

Returns true if the animation instance is finished. PLease note that finished instances can not be resumed and any operation on a finished instances equals a NOP.

AnimationSystem.blend_in_out(instance, target_blend_weight, duration, delay, stop_animation)¶

Params:

instance (Handle) - The handle of the instance.
target_blend_weight (number) - The target blend weight to animate towards.
duration (number) - The duration of the animation (in seconds).
delay (number) - The delay before the animation starts (in seconds).
stop_animation (boolean) - Set to true to stop the animation instance after the blend animation finished.

Animates the blend weight of the animation instances towards the provided target blend weight. Optionally stops the animation instance after the blending finished.

AnimationSystem.get_blend_weight(instance)¶

Params:

instance (Handle) - The handle of the instance.

Returns:

value (number) - The current blend weight.

Gets the current blend weight of the provided animation instance.

AnimationSystem.set_blend_weight(instance, play_speed)¶

Params:

instance (Handle) - The handle of the instance.
play_speed (number) - The blend weight to set.

Sets the blend weight of the provided animation instance.

AnimationSystem.get_play_speed(instance)¶

Params:

instance (Handle) - The handle of the instance.

Returns:

value (number) - The current play speed.

Gets the current play speed of the provided animation instance.

AnimationSystem.set_play_speed(instance, play_speed)¶

Params:

instance (Handle) - The handle of the instance.
play_speed (number) - The play speed to set.

Sets the play speed of the provided animation instance.

AnimationSystem.get_timeline_position(instance)¶

Params:

instance (Handle) - The handle of the instance.

Returns:

value (number) - The current timeline position.

Gets the current timeline position of the provided animation instance.

AnimationSystem.set_timeline_position(instance, timeline_position)¶

Params:

instance (Handle) - The handle of the instance.
timeline_position (number) - The timeline position to set.

Sets the timeline position of the provided animation instance.

AnimationSystem.AnimationDesc()¶

Returns:

value (AnimationDesc) - The animation description.

Creates and initializes the animation description to its default values.

Custom Data Component¶

Functions to interact with custom datas.

CustomData.load()¶: Loads all functions and types for this scripting interface.

CustomData.get_type_id(component)¶

Params:

component (Ref) - The component.

Returns:

value (number) - The type ID of the component.

Returns the type ID of the component.

CustomData.create(parent_entity)¶

Params:

parent_entity (Ref) - The parent entity.

Creates a new component and attaches it to the provided parent entity.

CustomData.destroy(component)¶

Params:

component (Ref) - The component to destroy.

Destroys the provided component.

CustomData.commit_changes(component)¶

Params:

component (Ref) - The component to update.

Commits all changes to the properties of the provided component.

CustomData.get_num_active_components()¶

Returns:

value (number) - Total total number of active components of this type.

Returns the total number of active components of this type.

CustomData.get_component_for_entity(entity)¶

Params:

entity (Ref) - The entity.

Returns:

value (Ref) - The component for the given entity.

Returns the component for the given entity.

CustomData.is_alive(component)¶

Params:

component (Ref) - The component.

Returns:

value (boolean) - True if the component is alive.

Returns true if the referenced component is alive.

CustomData.get_entity(component)¶

Params:

component (Ref) - The component.

Returns:

value (Ref) - The entity the component is assigned to.

Returns the entity the component is assigned to.

CustomData.get_property(component, property_name)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to retrieve.

Returns:

value (Variant) - The property as a variant.

Returns the requested property as a variant.

CustomData.set_property(component, property_name, value)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to set.
value (Variant) - The value to set.

Sets the requested property to the provided variant value.

CustomData.list_properties()¶

Returns:

value (table) - Table containing the names and types of all the exposed properties.

Lists all properties exposed by this component interface.

CustomData.get(component, index)¶

Params:

component (Ref) - The custom data component.
index (number) - The index of the value to retrieve.

Returns:

value (Variant) - The value for the given index.

Gets the value for the given index.

CustomData.set(component, index, value)¶

Params:

component (Ref) - The custom data component.
index (number) - The index of the value to retrieve.
value (Variant) - The value to set.

Sets the value for the given index.

CustomData.add(component, value)¶

Params:

component (Ref) - The custom data component.
value (Variant) - The value to add.

Adds a new value.

CustomData.remove(component, index)¶

Params:

component (Ref) - The custom data component.
index (number) - The index of the value to remove.

Adds a new value.

Tag Component¶

Functions to interact with tags.

Tag.load()¶: Loads all functions and types for this scripting interface.

Tag.get_type_id(component)¶

Params:

component (Ref) - The component.

Returns:

value (number) - The type ID of the component.

Returns the type ID of the component.

Tag.create(parent_entity)¶

Params:

parent_entity (Ref) - The parent entity.

Creates a new component and attaches it to the provided parent entity.

Tag.destroy(component)¶

Params:

component (Ref) - The component to destroy.

Destroys the provided component.

Tag.commit_changes(component)¶

Params:

component (Ref) - The component to update.

Commits all changes to the properties of the provided component.

Tag.get_num_active_components()¶

Returns:

value (number) - Total total number of active components of this type.

Returns the total number of active components of this type.

Tag.get_component_for_entity(entity)¶

Params:

entity (Ref) - The entity.

Returns:

value (Ref) - The component for the given entity.

Returns the component for the given entity.

Tag.is_alive(component)¶

Params:

component (Ref) - The component.

Returns:

value (boolean) - True if the component is alive.

Returns true if the referenced component is alive.

Tag.get_entity(component)¶

Params:

component (Ref) - The component.

Returns:

value (Ref) - The entity the component is assigned to.

Returns the entity the component is assigned to.

Tag.get_property(component, property_name)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to retrieve.

Returns:

value (Variant) - The property as a variant.

Returns the requested property as a variant.

Tag.set_property(component, property_name, value)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to set.
value (Variant) - The value to set.

Sets the requested property to the provided variant value.

Tag.list_properties()¶

Returns:

value (table) - Table containing the names and types of all the exposed properties.

Lists all properties exposed by this component interface.

Tag.find_entities_with_tag(tag)¶

Params:

tag (string) - The tag to search for.

Returns:

value (table) - Table containing all entities with the given tag.

Finds and returns all entities with the given tag.

Tag.add(tag, tag_name)¶

Params:

tag (Ref) - The component to add the new tag to.
tag_name (string) - The name of the tag to add.

Adds the tag with the given name.

Tag.remove(tag, tag_name)¶

Params:

tag (Ref) - The component to remove the tag from.
tag_name (string) - The name of the tag to remove.

Removes the tag with the given name.

Tag.get_tags(tag)¶

Params:

tag (Ref) - The component to retrieve the tags from.

Returns:

value (table) - Table containing all tags for the given component.

Returns all tags set for the given component.

Flipbook Animation Component¶

Functions to interact with flipbook animations.

FlipbookAnimation.load()¶: Loads all functions and types for this scripting interface.

FlipbookAnimation.get_type_id(component)¶

Params:

component (Ref) - The component.

Returns:

value (number) - The type ID of the component.

Returns the type ID of the component.

FlipbookAnimation.create(parent_entity)¶

Params:

parent_entity (Ref) - The parent entity.

Creates a new component and attaches it to the provided parent entity.

FlipbookAnimation.destroy(component)¶

Params:

component (Ref) - The component to destroy.

Destroys the provided component.

FlipbookAnimation.commit_changes(component)¶

Params:

component (Ref) - The component to update.

Commits all changes to the properties of the provided component.

FlipbookAnimation.get_num_active_components()¶

Returns:

value (number) - Total total number of active components of this type.

Returns the total number of active components of this type.

FlipbookAnimation.get_component_for_entity(entity)¶

Params:

entity (Ref) - The entity.

Returns:

value (Ref) - The component for the given entity.

Returns the component for the given entity.

FlipbookAnimation.is_alive(component)¶

Params:

component (Ref) - The component.

Returns:

value (boolean) - True if the component is alive.

Returns true if the referenced component is alive.

FlipbookAnimation.get_entity(component)¶

Params:

component (Ref) - The component.

Returns:

value (Ref) - The entity the component is assigned to.

Returns the entity the component is assigned to.

FlipbookAnimation.get_property(component, property_name)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to retrieve.

Returns:

value (Variant) - The property as a variant.

Returns the requested property as a variant.

FlipbookAnimation.set_property(component, property_name, value)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to set.
value (Variant) - The value to set.

Sets the requested property to the provided variant value.

FlipbookAnimation.list_properties()¶

Returns:

value (table) - Table containing the names and types of all the exposed properties.

Lists all properties exposed by this component interface.

FlipbookAnimation.play(component)¶

Params:

component (Ref) - The component in question.

Starts playing the flipbook animation.

FlipbookAnimation.stop(component)¶

Params:

component (Ref) - The component in question.

Stops playing the flipbook animation.

Post Effect Volume Component¶

Functions to interact with post effect volumes.

PostEffectVolume.load()¶: Loads all functions and types for this scripting interface.

PostEffectVolume.get_type_id(component)¶

Params:

component (Ref) - The component.

Returns:

value (number) - The type ID of the component.

Returns the type ID of the component.

PostEffectVolume.create(parent_entity)¶

Params:

parent_entity (Ref) - The parent entity.

Creates a new component and attaches it to the provided parent entity.

PostEffectVolume.destroy(component)¶

Params:

component (Ref) - The component to destroy.

Destroys the provided component.

PostEffectVolume.commit_changes(component)¶

Params:

component (Ref) - The component to update.

Commits all changes to the properties of the provided component.

PostEffectVolume.get_num_active_components()¶

Returns:

value (number) - Total total number of active components of this type.

Returns the total number of active components of this type.

PostEffectVolume.get_component_for_entity(entity)¶

Params:

entity (Ref) - The entity.

Returns:

value (Ref) - The component for the given entity.

Returns the component for the given entity.

PostEffectVolume.is_alive(component)¶

Params:

component (Ref) - The component.

Returns:

value (boolean) - True if the component is alive.

Returns true if the referenced component is alive.

PostEffectVolume.get_entity(component)¶

Params:

component (Ref) - The component.

Returns:

value (Ref) - The entity the component is assigned to.

Returns the entity the component is assigned to.

PostEffectVolume.get_property(component, property_name)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to retrieve.

Returns:

value (Variant) - The property as a variant.

Returns the requested property as a variant.

PostEffectVolume.set_property(component, property_name, value)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to set.
value (Variant) - The value to set.

Sets the requested property to the provided variant value.

PostEffectVolume.list_properties()¶

Returns:

value (table) - Table containing the names and types of all the exposed properties.

Lists all properties exposed by this component interface.

Camera Component¶

Functions to interact with cameras.

Camera.load()¶: Loads all functions and types for this scripting interface.

Camera.get_type_id(component)¶

Params:

component (Ref) - The component.

Returns:

value (number) - The type ID of the component.

Returns the type ID of the component.

Camera.create(parent_entity)¶

Params:

parent_entity (Ref) - The parent entity.

Creates a new component and attaches it to the provided parent entity.

Camera.destroy(component)¶

Params:

component (Ref) - The component to destroy.

Destroys the provided component.

Camera.commit_changes(component)¶

Params:

component (Ref) - The component to update.

Commits all changes to the properties of the provided component.

Camera.get_num_active_components()¶

Returns:

value (number) - Total total number of active components of this type.

Returns the total number of active components of this type.

Camera.get_component_for_entity(entity)¶

Params:

entity (Ref) - The entity.

Returns:

value (Ref) - The component for the given entity.

Returns the component for the given entity.

Camera.is_alive(component)¶

Params:

component (Ref) - The component.

Returns:

value (boolean) - True if the component is alive.

Returns true if the referenced component is alive.

Camera.get_entity(component)¶

Params:

component (Ref) - The component.

Returns:

value (Ref) - The entity the component is assigned to.

Returns the entity the component is assigned to.

Camera.get_property(component, property_name)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to retrieve.

Returns:

value (Variant) - The property as a variant.

Returns the requested property as a variant.

Camera.set_property(component, property_name, value)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to set.
value (Variant) - The value to set.

Sets the requested property to the provided variant value.

Camera.list_properties()¶

Returns:

value (table) - Table containing the names and types of all the exposed properties.

Lists all properties exposed by this component interface.

Voxel Shape Component¶

Functions to interact with voxel shapes.

VoxelShape.load()¶: Loads all functions and types for this scripting interface.

VoxelShape.get_type_id(component)¶

Params:

component (Ref) - The component.

Returns:

value (number) - The type ID of the component.

Returns the type ID of the component.

VoxelShape.create(parent_entity)¶

Params:

parent_entity (Ref) - The parent entity.

Creates a new component and attaches it to the provided parent entity.

VoxelShape.destroy(component)¶

Params:

component (Ref) - The component to destroy.

Destroys the provided component.

VoxelShape.commit_changes(component)¶

Params:

component (Ref) - The component to update.

Commits all changes to the properties of the provided component.

VoxelShape.get_num_active_components()¶

Returns:

value (number) - Total total number of active components of this type.

Returns the total number of active components of this type.

VoxelShape.get_component_for_entity(entity)¶

Params:

entity (Ref) - The entity.

Returns:

value (Ref) - The component for the given entity.

Returns the component for the given entity.

VoxelShape.is_alive(component)¶

Params:

component (Ref) - The component.

Returns:

value (boolean) - True if the component is alive.

Returns true if the referenced component is alive.

VoxelShape.get_entity(component)¶

Params:

component (Ref) - The component.

Returns:

value (Ref) - The entity the component is assigned to.

Returns the entity the component is assigned to.

VoxelShape.get_property(component, property_name)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to retrieve.

Returns:

value (Variant) - The property as a variant.

Returns the requested property as a variant.

VoxelShape.set_property(component, property_name, value)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to set.
value (Variant) - The value to set.

Sets the requested property to the provided variant value.

VoxelShape.list_properties()¶

Returns:

value (table) - Table containing the names and types of all the exposed properties.

Lists all properties exposed by this component interface.

VoxelShape.set(component, coord, palette_index)¶

Params:

component (Ref) - The voxel shape component.
coord (U8Vec3) - The coordinate of the voxel.
palette_index (number) - The palette index to set.

Sets the voxel to the given palette index.

VoxelShape.set_unsafe(component, coord, palette_index)¶

Params:

component (Ref) - The voxel shape component.
coord (U8Vec3) - The coordinate of the voxel.
palette_index (number) - The palette index to set.

Sets the voxel to the given palette index (without boundary checks).

VoxelShape.get(component, coord)¶

Params:

component (Ref) - The voxel shape component.
coord (U8Vec3) - The coordinate of the voxel.

Returns:

value (number) - The palette index of the given voxel.

Gets the palette index for a voxel.

VoxelShape.fill(component, min, max, palette_index)¶

Params:

component (Ref) - The voxel shape component.
min (U8Vec3) - The min voxel coorindate of the area.
max (U8Vec3) - The max voxel coordinate of the area.
palette_index (number) - The palette index to set.

Fills all voxels in the range defined by min and max.

VoxelShape.copy(target, source)¶

Params:

target (Ref) - The target voxel shape component.
source (Ref) - The source voxel shape component.

Copies the given source shape into the target shape.

VoxelShape.get_dim(component)¶

Params:

component (Ref) - The voxel shape component.

Returns:

value (U16Vec3) - The dimensions of the shape in voxels.

Gets the dimensions of the shape in voxels.

VoxelShape.voxelize(component)¶

Params:

component (Ref) - The voxel shape component.

Queues this shape for voxelization

VoxelShape.add_force_at_world_position(component, force, position)¶

Params:

component (Ref) - The voxel shape component.
force (Vec3) - The force vector to apply.
position (Vec3) - The position to apply the force at (world coordinates).

Applies a force at the given world position.

VoxelShape.add_force_at_local_position(component, force, position)¶

Params:

component (Ref) - The voxel shape component.
force (Vec3) - The force vector to apply.
position (Vec3) - The position to apply the force at (local coordinates).

Applies a force at the given local position.

VoxelShape.add_force(component, force)¶

Params:

component (Ref) - The voxel shape component.
force (Vec3) - The force vector to apply.

Applies a force at the center of mass.

VoxelShape.add_torque(component, torque)¶

Params:

component (Ref) - The voxel shape component.
torque (Vec3) - The torque vector to apply.

Applies a torque at the center of mass.

VoxelShape.get_linear_velocity(component)¶

Params:

component (Ref) - The voxel shape component.

Returns:

value (Vec3) - The linear velocity of the shape.

Gets the linear velocity of the shape.

VoxelShape.set_linear_velocity(component, velocity)¶

Params:

component (Ref) - The voxel shape component.
velocity (Vec3) - The linear velocity to set.

Sets the linear velocity of the shape.

VoxelShape.get_angular_velocity(component)¶

Params:

component (Ref) - The voxel shape component.

Returns:

value (Vec3) - The angular velocity of the shape.

Gets the angular velocity of the shape.

VoxelShape.set_angular_velocity(component, velocity)¶

Params:

component (Ref) - The voxel shape component.
velocity (Vec3) - The angular velocity to set.

Sets the angular velocity of the shape.

VoxelShape.get_mass(component)¶

Params:

component (Ref) - The voxel shape component.

Returns:

value (number) - The mass of the shape. Zero if no mass is available.

Gets the mass of the shape. Returns zero if not available.

Light Component¶

Functions to interact with lights.

Light.load()¶: Loads all functions and types for this scripting interface.

Light.get_type_id(component)¶

Params:

component (Ref) - The component.

Returns:

value (number) - The type ID of the component.

Returns the type ID of the component.

Light.create(parent_entity)¶

Params:

parent_entity (Ref) - The parent entity.

Creates a new component and attaches it to the provided parent entity.

Light.destroy(component)¶

Params:

component (Ref) - The component to destroy.

Destroys the provided component.

Light.commit_changes(component)¶

Params:

component (Ref) - The component to update.

Commits all changes to the properties of the provided component.

Light.get_num_active_components()¶

Returns:

value (number) - Total total number of active components of this type.

Returns the total number of active components of this type.

Light.get_component_for_entity(entity)¶

Params:

entity (Ref) - The entity.

Returns:

value (Ref) - The component for the given entity.

Returns the component for the given entity.

Light.is_alive(component)¶

Params:

component (Ref) - The component.

Returns:

value (boolean) - True if the component is alive.

Returns true if the referenced component is alive.

Light.get_entity(component)¶

Params:

component (Ref) - The component.

Returns:

value (Ref) - The entity the component is assigned to.

Returns the entity the component is assigned to.

Light.get_property(component, property_name)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to retrieve.

Returns:

value (Variant) - The property as a variant.

Returns the requested property as a variant.

Light.set_property(component, property_name, value)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to set.
value (Variant) - The value to set.

Sets the requested property to the provided variant value.

Light.list_properties()¶

Returns:

value (table) - Table containing the names and types of all the exposed properties.

Lists all properties exposed by this component interface.

Node Component¶

Functions to interact with nodes.

Node.get_type_id(component)¶

Params:

component (Ref) - The component.

Returns:

value (number) - The type ID of the component.

Returns the type ID of the component.

Node.get_num_active_components()¶

Returns:

value (number) - Total total number of active components of this type.

Returns the total number of active components of this type.

Node.get_component_for_entity(entity)¶

Params:

entity (Ref) - The entity.

Returns:

value (Ref) - The component for the given entity.

Returns the component for the given entity.

Node.is_alive(component)¶

Params:

component (Ref) - The component.

Returns:

value (boolean) - True if the component is alive.

Returns true if the referenced component is alive.

Node.get_entity(component)¶

Params:

component (Ref) - The component.

Returns:

value (Ref) - The entity the component is assigned to.

Returns the entity the component is assigned to.

Node.create(name)¶

Params:

name (string) - The name of the new node component.

Returns:

value (Ref) - The new node component.

Creates a new node component with the given name and attaches it to the root node of the world.

Node.create(name, parent_node, ignore_parent)¶

Params:

name (string) - The name of the new node component.
parent_node (Ref) - The node to attach the new node to.
ignore_parent (boolean) - Set this to true to keep the local transform of the node and avoid undoing the parent transform first.

Returns:

value (Ref) - The new node component.

Creates a new node component with the given name and attaches it to the provided node.

Node.attach(parent, child, ignore_parent)¶

Params:

parent (Ref) - The parent node to attach the child node to.
child (Ref) - The child node to attach.
ignore_parent (boolean) - Set this to true to keep the local transform of the node and avoid undoing the parent transform first.

Attaches the child node to the provided parent node.

Node.destroy(node)¶

Params:

node (Ref) - The node to destroy.

Destroys the given node component.

Node.get_depth(node)¶

Params:

node (Ref) - The node in question.

Returns:

value (number) - The depth of the node in the hierarchy.

Gets the depth of the node in the hierarchy (0: world root node, 1: children of the world root node, 2: …, and so on)

Node.get_parent(node)¶

Params:

node (Ref) - The node in question.

Returns:

value (Ref) - The parent of the node (if any).

Gets the parent node (if any).

Node.get_first_child(node)¶

Params:

node (Ref) - The node in question.

Returns:

value (Ref) - The first child of the node (if any).

Gets the first child of the node (if any).

Node.get_next_sibling(node)¶

Params:

node (Ref) - The node in question.

Returns:

value (Ref) - The next sibling of the node (if any).

Gets the next sibling of the node (if any).

Node.get_prev_sibling(node)¶

Params:

node (Ref) - The node in question.

Returns:

value (Ref) - The previous sibling of the node (if any).

Gets the previous sibling of the node (if any).

Node.set_hidden(node, hidden)¶

Params:

node (Ref) - The node in question.
hidden (boolean) - Pass true if the node should be hidden.

Sets the hidden state of the node.

Node.is_hidden(node)¶

Params:

node (Ref) - The node in question.

Returns:

value (boolean) - True if the node is hidden.

Retrieves the hidden state of the node.

Node.get_position(node)¶

Params:

node (Ref) - The node in question.

Returns:

value (Vec3) - The (local) position of the node.

Gets the (local) position of the node.

Node.get_world_position(node)¶

Params:

node (Ref) - The node in question.

Returns:

value (Vec3) - The (world) position of the node.

Gets the (world) position of the node.

Node.get_orientation(node)¶

Params:

node (Ref) - The node in question.

Returns:

value (Quat) - The (local) orientation of the node.

Gets the (local) orientation of the node.

Node.get_world_orientation(node)¶

Params:

node (Ref) - The node in question.

Returns:

value (Quat) - The (world) orientation of the node.

Gets the (world) orientation of the node.

Node.get_size(node)¶

Params:

node (Ref) - The node in question.

Returns:

value (Vec3) - The (local) size of the node.

Gets the (local) size of the node.

Node.get_world_size(node)¶

Params:

node (Ref) - The node in question.

Returns:

value (Vec3) - The (world) size of the node.

Gets the (world) size of the node.

Node.set_position(node, position)¶

Params:

node (Ref) - The node in question.
position (Vec3) - The (local) position of the node.

Sets the (local) position of the node.

Node.set_world_position(node, position)¶

Params:

node (Ref) - The node in question.
position (Vec3) - The (world) position of the node.

Sets the (world) position of the node.

Node.set_orientation(node, orientation)¶

Params:

node (Ref) - The node in question.
orientation (Quat) - The (local) orientation of the node.

Sets the (local) orientation of the node.

Node.set_world_orientation(node, orientation)¶

Params:

node (Ref) - The node in question.
orientation (Quat) - The (world) orientation of the node.

Sets the (world) orientation of the node.

Node.set_size(node, size)¶

Params:

node (Ref) - The node in question.
size (Vec3) - The (local) size of the node.

Sets the (local) size of the node.

Node.set_world_size(node, size)¶

Params:

node (Ref) - The node in question.
size (Vec3) - The (world) size of the node.

Sets the (world) size of the node.

Node.to_local_space(node, position)¶

Params:

node (Ref) - The node used for the transformation.
position (Vec3) - The position to transform.

Returns:

value (Vec3) - The position transformed into the local node space.

Transforms the provided position into the local space of the given node.

Node.to_local_space_direction(node, position)¶

Params:

node (Ref) - The node used for the transformation.
position (Vec3) - The direction to transform.

Returns:

value (Vec3) - The direction transformed into the local node space.

Transforms the provided direction into the local space of the given node.

Node.to_world_space(node, position)¶

Params:

node (Ref) - The node used for the transformation.
position (Vec3) - The position to transform.

Returns:

value (Vec3) - The position transformed into world space.

Transforms the provided position in the local space of the given node to world space.

Node.to_world_space_direction(node, direction)¶

Params:

node (Ref) - The node used for the transformation.
direction (Vec3) - The direction to transform.

Returns:

value (Vec3) - The direction transformed into world space.

Transforms the provided direction in the local space of the given node to world space.

Node.collect_nodes_depth_first(node)¶

Params:

node (Ref) - The root node to start collecting at.

Returns:

value (table) - Table containing all nodes in the hierarchy.

Collects all nodes in the hierarchy in depth first ordering starting at the provided node (including the root).

Node.collect_nodes_breadth_first(node)¶

Params:

node (Ref) - The root node to start at.

Returns:

value (table) - Table containing all nodes in the hierarchy.

Collects all nodes in the hierarchy in breadth first ordering starting at the provided node (including the root).

Node.update_transforms(node)¶

Params:

node (Ref) - The root node of the hierarchy.

Updates the transformations of the given node hierarchy.

Node.intersect_point(point, nodes, use_global_bounds)¶

Params:

point (Vec3) - The point test against.
nodes (table) - The nodes to check for intersections.
use_global_bounds (boolean) - Set to true to use the global bounds (the compound bounds of each node and all its children).

Returns:

value (table) - All nodes intersecting the provided point.

Iterates over all the provided nodes and returns the ones which intersect the given point.

Node.intersect_aabb(aabb, nodes, use_global_bounds)¶

Params:

aabb (AABB) - The AABB to test against.
nodes (table) - The nodes to check for intersections.
use_global_bounds (boolean) - Set to true to use the global bounds (the compound bounds of each node and all its children).

Returns:

value (table) - All nodes intersecting the provided AABB.

Iterates over all the provided nodes and returns the ones which intersect the given axis aligned bounding box (AABB).

Node.intersect_sphere(sphere, nodes, use_global_bounds)¶

Params:

sphere (Sphere) - The sphere to test against.
nodes (table) - The nodes to check for intersections.
use_global_bounds (boolean) - Set to true to use the global bounds (the compound bounds of each node and all its children).

Returns:

value (table) - All nodes intersecting the provided sphere.

Iterates over all the provided nodes and returns the ones which intersect the given sphere.

Character Controller Component¶

Functions to interact with character controllers.

CharacterController.load()¶: Loads all functions and types for this scripting interface.

CharacterController.get_type_id(component)¶

Params:

component (Ref) - The component.

Returns:

value (number) - The type ID of the component.

Returns the type ID of the component.

CharacterController.create(parent_entity)¶

Params:

parent_entity (Ref) - The parent entity.

Creates a new component and attaches it to the provided parent entity.

CharacterController.destroy(component)¶

Params:

component (Ref) - The component to destroy.

Destroys the provided component.

CharacterController.commit_changes(component)¶

Params:

component (Ref) - The component to update.

Commits all changes to the properties of the provided component.

CharacterController.get_num_active_components()¶

Returns:

value (number) - Total total number of active components of this type.

Returns the total number of active components of this type.

CharacterController.get_component_for_entity(entity)¶

Params:

entity (Ref) - The entity.

Returns:

value (Ref) - The component for the given entity.

Returns the component for the given entity.

CharacterController.is_alive(component)¶

Params:

component (Ref) - The component.

Returns:

value (boolean) - True if the component is alive.

Returns true if the referenced component is alive.

CharacterController.get_entity(component)¶

Params:

component (Ref) - The component.

Returns:

value (Ref) - The entity the component is assigned to.

Returns the entity the component is assigned to.

CharacterController.get_property(component, property_name)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to retrieve.

Returns:

value (Variant) - The property as a variant.

Returns the requested property as a variant.

CharacterController.set_property(component, property_name, value)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to set.
value (Variant) - The value to set.

Sets the requested property to the provided variant value.

CharacterController.list_properties()¶

Returns:

value (table) - Table containing the names and types of all the exposed properties.

Lists all properties exposed by this component interface.

CharacterController.move(component, move)¶

Params:

component (Ref) - The controller in question.
move (Vec3) - The movement to apply to the character controller in world space.

Moves the character controller.

CharacterController.is_grounded(component)¶

Params:

component (Ref) - The controller in question.

Returns:

value (boolean) - True if the controller is grounded.

Returns true if the character controller is grounded.

CharacterController.is_colliding_sides(component)¶

Params:

component (Ref) - The controller in question.

Returns:

value (boolean) - True if the controller is colliding with its sides.

Returns true if the controller is colliding with its sides.

CharacterController.is_colliding_up(component)¶

Params:

component (Ref) - The controller in question.

Returns:

value (boolean) - True if the top of the controller is colliding.

Returns true if the upper part of the controller is colliding.

Vehicle Component¶

Functions to interact with vehicles.

Vehicle.load()¶: Loads all functions and types for this scripting interface.

Vehicle Wheel Component¶

Functions to interact with vehicle wheels.

VehicleWheel.load()¶: Loads all functions and types for this scripting interface.

VehicleWheel.set_steering_angle(component, steering_angle)¶

Params:

component (Ref) - The wheel in question.
steering_angle (number) - The steering angle in radians.

Sets the steering angle.

VehicleWheel.get_steering_angle(component)¶

Params:

component (Ref) - The wheel in question.

Returns:

value (number) - The steering angle in radians.

Returns the steering angle.

VehicleWheel.set_torque(component, torque)¶

Params:

component (Ref) - The wheel in question.
torque (number) - The torque (as revolutions per second).

Sets the torque.

VehicleWheel.get_torque(component)¶

Params:

component (Ref) - The wheel in question.

Returns:

value (number) - The torque (as revolutions per second).

Returns the torque.

Joint Component¶

Functions to interact with vehicles.

Joint.load()¶: Loads all functions and types for this scripting interface.

Camera Controller Component¶

Functions to interact with camera controllers.

CameraController.load()¶: Loads all functions and types for this scripting interface.

CameraController.get_type_id(component)¶

Params:

component (Ref) - The component.

Returns:

value (number) - The type ID of the component.

Returns the type ID of the component.

CameraController.create(parent_entity)¶

Params:

parent_entity (Ref) - The parent entity.

Creates a new component and attaches it to the provided parent entity.

CameraController.destroy(component)¶

Params:

component (Ref) - The component to destroy.

Destroys the provided component.

CameraController.commit_changes(component)¶

Params:

component (Ref) - The component to update.

Commits all changes to the properties of the provided component.

CameraController.get_num_active_components()¶

Returns:

value (number) - Total total number of active components of this type.

Returns the total number of active components of this type.

CameraController.get_component_for_entity(entity)¶

Params:

entity (Ref) - The entity.

Returns:

value (Ref) - The component for the given entity.

Returns the component for the given entity.

CameraController.is_alive(component)¶

Params:

component (Ref) - The component.

Returns:

value (boolean) - True if the component is alive.

Returns true if the referenced component is alive.

CameraController.get_entity(component)¶

Params:

component (Ref) - The component.

Returns:

value (Ref) - The entity the component is assigned to.

Returns the entity the component is assigned to.

CameraController.get_property(component, property_name)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to retrieve.

Returns:

value (Variant) - The property as a variant.

Returns the requested property as a variant.

CameraController.set_property(component, property_name, value)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to set.
value (Variant) - The value to set.

Sets the requested property to the provided variant value.

CameraController.list_properties()¶

Returns:

value (table) - Table containing the names and types of all the exposed properties.

Lists all properties exposed by this component interface.

CameraController.set_target_node(component, node)¶

Params:

component (Ref) - The controller in question.
node (Ref) - The node the controller should track.

Sets the node the controller should track.

CameraController.set_target_euler_angles(component, angles)¶

Params:

component (Ref) - The controller in question.
angles (Vec3) - The target euler angles in radians.

Sets the target Euler angles.

CameraController.get_target_euler_angles(component)¶

Params:

component (Ref) - The controller in question.

Returns:

value (Vec3) - The current target euler angles in radians.

Gets the target Euler angles.

Particle Component¶

Functions to interact with particles.

Particle.load()¶: Loads all functions and types for this scripting interface.

Particle.get_type_id(component)¶

Params:

component (Ref) - The component.

Returns:

value (number) - The type ID of the component.

Returns the type ID of the component.

Particle.create(parent_entity)¶

Params:

parent_entity (Ref) - The parent entity.

Creates a new component and attaches it to the provided parent entity.

Particle.destroy(component)¶

Params:

component (Ref) - The component to destroy.

Destroys the provided component.

Particle.commit_changes(component)¶

Params:

component (Ref) - The component to update.

Commits all changes to the properties of the provided component.

Particle.get_num_active_components()¶

Returns:

value (number) - Total total number of active components of this type.

Returns the total number of active components of this type.

Particle.get_component_for_entity(entity)¶

Params:

entity (Ref) - The entity.

Returns:

value (Ref) - The component for the given entity.

Returns the component for the given entity.

Particle.is_alive(component)¶

Params:

component (Ref) - The component.

Returns:

value (boolean) - True if the component is alive.

Returns true if the referenced component is alive.

Particle.get_entity(component)¶

Params:

component (Ref) - The component.

Returns:

value (Ref) - The entity the component is assigned to.

Returns the entity the component is assigned to.

Particle.get_property(component, property_name)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to retrieve.

Returns:

value (Variant) - The property as a variant.

Returns the requested property as a variant.

Particle.set_property(component, property_name, value)¶

Params:

component (Ref) - The component.
property_name (string) - The name of the property to set.
value (Variant) - The value to set.

Sets the requested property to the provided variant value.

Particle.list_properties()¶

Returns:

value (table) - Table containing the names and types of all the exposed properties.

Lists all properties exposed by this component interface.

Particle.get_emitter_handle(component)¶

Params:

component (Ref) - The particle in question.

Returns:

value (Handle) - The emitter handle of this particle.

Gets the emitter handle.

Palette Resource¶

Functions to interact with palettes.

Palette.load()¶: Loads all functions and types for this scripting interface.

Palette.get_type_id(component)¶

Params:

component (Ref) - The resource.

Returns:

value (number) - The type ID of the resource.

Returns the type ID of the resource.

Palette.find_first_resource_with_:name(name)

Params:

name (string) - The name of the resource to find.

Returns:

value (Ref) - The first resource with the given name. Returns an invalid Ref if none is found.

Finds the first resource with the given name.

Palette.create(name)¶

Params:

name (string) - The name of the new resource.

Creates a new resource with the given name.

Palette.destroy(resource)¶

Params:

resource (Ref) - The resource to destroy.

Destroys the provided resource.

Palette.commit_changes(resource)¶

Params:

resource (Ref) - The resource to update.

Commits all changes to the properties of the provided resource.

Palette.get_num_active_resources()¶

Returns:

value (number) - Total total number of active resources of this type.

Returns the total number of active resources of this type.

Palette.is_alive(resource)¶

Params:

resource (Ref) - The resource.

Returns:

value (boolean) - True if the resource is alive.

Returns true if the referenced resource is alive.

Palette.get_property(resource, property_name)¶

Params:

resource (Ref) - The resource.
property_name (string) - The name of the property to retrieve.

Returns:

value (Variant) - The property as a variant.

Returns the requested property as a variant.

Palette.set_property(resource, property_name, value)¶

Params:

resource (Ref) - The resource.
property_name (string) - The name of the property to set.
value (Variant) - The value to set.

Sets the requested property to the provided variant value.

Palette.list_properties()¶

Returns:

value (table) - Table containing the names and types of all the exposed properties.

Lists all properties exposed by this resource interface.

Palette.set_color(palette, palette_index, color)¶

Params:

palette (Ref) - The palette in question.
palette_index (number) - The palette index of the color to change.
color (Vec4) - The color to set.

Sets the color for the given palette index of the given palette.

Palette.get_color(palette, palette_index)¶

Params:

palette (Ref) - The palette in question.
palette_index (number) - The palette index of the color to change.

Returns:

value (Vec4) - The color at the given palette index.

Gets the color for the given palette index of the given palette.

Palette.set_material_parameters(palette, palette_index, material_parameters)¶

Params:

palette (Ref) - The palette in question.
palette_index (number) - The palette index of the material_parameters to change.
material_parameters (Vec4) - The material parameters to set (roughness, matalmask, hardness, and emissive).

Sets the material parameters for the given palette index of the given palette.

Palette.get_material_parameters(palette, palette_index)¶

Params:

palette (Ref) - The palette in question.
palette_index (number) - The palette index of the material_parameters to change.

Returns:

value (Vec4) - The material parameters at the given palette index (roughness, metalmask, hardness, and emissive).

Gets the material parameters for the given palette index of the given palette.