NAV
Lua

Lua API

> Vector3

Vector3

local wishDir = Vector3(0, 0.1, 0);

Vector3 Vector3(number x, number y, number z)

Parameter Type Description
x number x-component of Vector3.
y number y-component of Vector3.
z number z-component of Vector3.

Construct a Vector3 from the given components.

Vector3.new(number x, number y, number z)

local wishDir = Vector3.new(0, 0.1, 0);

Vector3 Vector3.new(number x, number y, number z)

Parameter Type Description
x number x-component of Vector3.
y number y-component of Vector3.
z number z-component of Vector3.

Construct a Vector3 from the given components.

Vector3.magnitude(Vector3 v)

local wishDir = Vector3(0, 0.1, 0);
if (Vector3.magnitude(wishDir) > 0) then
   print("Do stuff")
end

number Vector3.magnitude(Vector3 v)

Parameter Type Description
v Vector3 Vector3 to find magnitude of.

Return the magnitude of the given Vector3.

Vector3.normalize(Vector3 v)

local wishDir = Vector3(0, 0.1, 0);
wishDir = Vector3.normalize(wishDir);

Vector3 Vector3.normalize(Vector3 v)

Parameter Type Description
v Vector3 Vector3 to normalize.

Return a normalized version of the given Vector3.

Vector3.invert(Vector3 v)

local vec = Vector3(1, 0, 1);
print(vec); -- {1, 0, 1}
local vec = Vector3.invert(vec);
print(vec); -- {-1, 0, -1}

Vector3 Vector3.invert(Vector3 v)

Parameter Type Description
v Vector3 Vector3 to invert.

Return an inverted version of the given Vector3.

Vector3.dot(Vector3 v1, Vector3 v2)

local v1 = Vector3(0, 1, 0);
local v2 = Vector3(0, 1, 0);
local dot = Vector3.dot(v1, v2); -- 1 

number Vector3.dot(Vector3 v1, Vector3 v2)

Parameter Type Description
v1 Vector3 Vector3 to dot product.
v2 Vector3 Vector3 to dot product.

Return the dot product of the two given vectors.

Vector3.cross(Vector3 v1, Vector3 v2)

local v1 = Vector3(1, 0, 0);
local v2 = Vector3(0, 1, 0);
local cross = Vector3.cross(v1, v2); -- {0, 0, 1}

Vector3 Vector3.cross(Vector3 v1, Vector3 v2)

Parameter Type Description
v1 Vector3 Vector3 to cross product.
v2 Vector3 Vector3 to cross product.

Return the cross product of the two given vectors.

Vector3.transform(Vector3 v, Matrix4 m)

local vecTransformed = Vector3.transform(myVec, myMatrix);
Parameter Type Description
v Vector3 Vector3 to transform.
m Matrix4 Matrix4 to transform Vector3 by.

Return a Vector3 equal to the given Vector3 transformed by the given Matrix4.

Vector3.unit_x()

local unitX = Vector3.unit_x() -- {1, 0, 0}

Vector3 Vector3.unit_x()

Return a Vector3 of magnitude 1 in the x-direction.

Vector3.unit_y()

local unitY = Vector3.unit_y() -- {0, 1, 0}

Vector3 Vector3.unit_y()

Return a Vector3 of magnitude 1 in the y-direction.

Vector3.unit_z()

local unitZ = Vector3.unit_z() -- {0, 0, 1}

Vector3 Vector3.unit_z()

Return a Vector3 of magnitude 1 in the z-direction.

Vector3:get_x()

local vec = Vector3(3.14159, 0, 0);
local x = vec:get_x(); -- 3.14159

number Vector3:get_x()

Return the x component of the given Vector3.

Vector3:get_y()

local vec = Vector3(0, 3.14159, 0);
local y = vec:get_y(); -- 3.14159

number Vector3:get_y()

Return the y component of the given Vector3.

Vector3:get_z()

local vec = Vector3(0, 0, 3.14159);
local z = vec:get_z(); -- 3.14159

number Vector3:get_z()

Return the z component of the given Vector3.

Vector3:set_x()

local vec = Vector3(0, 0, 0); -- {0, 0, 0}
vec:set_x(3.14159); -- {3.14159, 0, 0}

Vector3:set_x(number x)

Parameter Type Description
x number Value to given to x component of given Vector3.

Set the x component of the given Vector3 to the given value.

Vector3:set_y()

local vec = Vector3(0, 0, 0); -- {0, 0, 0}
vec:set_y(3.14159); -- {0, 3.14159, 0}

Vector3:set_y(number y)

Parameter Type Description
y number Value to given to y component of given Vector3.

Set the y component of the given Vector3 to the given value.

Vector3:set_z()

local vec = Vector3(0, 0, 0); -- {0, 0, 0}
vec:set_z(3.14159); -- {0, 0, 3.14159}

Vector3:set_z(number z)

Parameter Tzpe Description
z number Value to given to z component of given Vector3.

Set the z component of the given Vector3 to the given value.

> Vector4

Vector4

local vec = Vector4(4, 0.1, 3.0, 1.0);

Vector4 Vector4(number x, number y, number z, number w)

Parameter Type Description
x number x component of Vector4.
y number y component of Vector4.
z number z component of Vector4.
w number w component of Vector4.

Construct a Vector4 from the given components.

Vector4.new(number x, number y, number z, number w)

local vec = Vector4.new(4, 0.1, 3.0, 1.0);

Vector4 Vector4.new(number x, number y, number z, number w)

Parameter Type Description
x number x component of Vector4.
y number y component of Vector4.
z number z component of Vector4.
w number w component of Vector4.

Construct a Vector4 from the given components.

Vector4.magnitude(Vector4 v)

local wishDir = Vector4(0, 0.1, 0, 1.0);
if (Vector4.magnitude(wishDir) > 0) then
   print("Do stuff")
end

number Vector4.magnitude(Vector4 v)

Parameter Type Description
v Vector4 Vector4 to find magnitude of.

Return the magnitude of the given Vector4.

Vector4.normalize(Vector4 v)

local wishDir = Vector4(0, 0.1, 0, 1.0);
wishDir = Vector4.normalize(wishDir);

Vector4 Vector4.normalize(Vector4 v)

Parameter Type Description
v Vector4 Vector4 to normalize.

Return a normalized version of the given Vector4.

Vector4.invert(Vector4 v)

local vec = Vector4(1, 0, 1, 1);
print(vec); -- {1, 0, 1, 1}
local vec = Vector4.invert(vec);
print(vec); -- {-1, 0, -1, -1}

Vector4 Vector4.invert(Vector4 v)

Parameter Type Description
v Vector4 Vector4 to invert.

Return an inverted version of the given Vector4.

Vector4.dot(Vector4 v1, Vector4 v2)

local v1 = Vector4(0, 1, 0, 1);
local v2 = Vector4(0, 1, 0, 1);
local dot = Vector4.dot(v1, v2); -- 2 

number Vector4.dot(Vector4 v1, Vector4 v2)

Parameter Type Description
v1 Vector4 Vector4 to dot product.
v2 Vector4 Vector4 to dot product.

Return the dot product of the two given vectors.

Vector4.transform(Vector4 v, Matrix4 m)

local vecTransformed = Vector4.transform(myVec, myMatrix);
Parameter Type Description
v Vector4 Vector4 to transform.
m Matrix4 Matrix4 to transform Vector4 by.

Return a Vector4 equal to the given Vector4 transformed by the given Matrix4.

Vector4.unit_x()

local unitX = Vector4.unit_x() -- {1, 0, 0, 0}

Vector4 Vector4.unit_x()

Return a Vector4 of magnitude 1 in the x-direction.

Vector4.unit_y()

local unitY = Vector4.unit_y() -- {0, 1, 0, 0}

Vector4 Vector4.unit_y()

Return a Vector4 of magnitude 1 in the y-direction.

Vector4.unit_z()

local unitZ = Vector4.unit_z() -- {0, 0, 1, 0}

Vector4 Vector4.unit_z()

Return a Vector4 of magnitude 1 in the z-direction.

Vector4.unit_w()

local unitW = Vector4.unit_w() -- {0, 0, 1, 0}

Vector4 Vector4.unit_w()

Return a Vector4 of magnitude 1 in the w-direction.

Vector4:get_x()

local vec = Vector4(3.14159, 0, 0, 1);
local x = vec:get_x(); -- 3.14159

number Vector4:get_x()

Return the x component of the given Vector4.

Vector4:get_y()

local vec = Vector4(0, 3.14159, 0, 1);
local y = vec:get_y(); -- 3.14159

number Vector4:get_y()

Return the y component of the given Vector4.

Vector4:get_z()

local vec = Vector4(0, 0, 3.14159, 1);
local z = vec:get_z(); -- 3.14159

number Vector4:get_z()

Return the z component of the given Vector4.

Vector4:get_w()

local vec = Vector4(0, 0, 3.14159, 1);
local w = vec:get_w(); -- 1 

number Vector4:get_w()

Return the w component of the given Vector4.

Vector4:set_x()

local vec = Vector4(0, 0, 0, 1); -- {0, 0, 0, 1}
vec:set_x(3.14159); -- {3.14159, 0, 0, 1}

Vector4:set_x(number x)

Parameter Type Description
x number Value to given to x component of given Vector4.

Set the x component of the given Vector4 to the given value.

Vector4:set_y()

local vec = Vector4(0, 0, 0, 1); -- {0, 0, 0, 1}
vec:set_y(3.14159); -- {0, 3.14159, 0, 1}

Vector4:set_y(number y)

Parameter Type Description
y number Value to given to y component of given Vector4.

Set the y component of the given Vector4 to the given value.

Vector4:set_z()

local vec = Vector4(0, 0, 0); -- {0, 0, 0, 1}
vec:set_z(3.14159); -- {0, 0, 3.14159, 1}

Vector4:set_z(number z)

Parameter Tzpe Description
z number Value to given to z component of given Vector4.

Set the z component of the given Vector4 to the given value.

Vector4:set_w()

local vec = Vector4(0, 0, 0); -- {0, 0, 0, 1}
vec:set_w(3.14159); -- {0, 0, 0, 3.14159}

Vector4:set_w(number w)

Parameter Twpe Description
w number Value to given to w component of given Vector4.

Set the w component of the given Vector4 to the given value.

> Quaternion

Quaternion

local quat = Quaternion(4, 0.1, 3.0, 1.0);

Quaternion Quaternion(number x, number y, number z, number w)

Parameter Type Description
x number x component of Quaternion.
y number y component of Quaternion.
z number z component of Quaternion.
w number w component of Quaternion.

Construct a Quaternion from the given components.

Quaternion.new(number x, number y, number z, number w)

local quat = Quaternion.new(4, 0.1, 3.0, 1.0);

Quaternion Quaternion(number x, number y, number z, number w)

Parameter Type Description
x number x component of Quaternion.
y number y component of Quaternion.
z number z component of Quaternion.
w number w component of Quaternion.

Construct a Quaternion from the given components.

Quaternion.create_from_axis_angle(Vector3 axis, number angleRadians)

local axis = Vector3(0, 1, 0);
local angle = math.pi/2.0; 
local quat = Quaternion.create_from_axis_angle(axis, angle);

Quaternion Quaternion.create_from_axis_angle(Vector3 axis, number angleRadians)

Parameter Type Description
axis Vector3 Axis of Quaternion.
angle number Angle of Quaternion.

Return a Quaternion constructed from the given axis and angle.

Quaternion.magnitude(Quaternion q)

local quat = Quaternion(1, 0, 0, 0);
print(Quaternion.magnitude(quat)); -- 1

number Quaternion.magnitude(Quaternion q)

Parameter Type Description
q Quaternion Quaternion to get magnitude of.

Return the magnitude of the given Quaternion.

Quaternion.normalize(Quaternion q)

local quat = Quaternion(2, 0, 0, 0);
print(Quaternion.normalize(quat)); -- {1, 0, 0, 0}

Quaternion Quaternion.normalize(Quaternion q)

Parameter Type Description
q Quaternion Quaternion to get normalized version of.

Returns a normalized version of the given Quaternion.

Quaternion.invert(Quaternion q)

local quat = Quaternion(2, 0, 0, 0);
print(Quaternion.invert(quat)); -- {-2, 0, 0, 0}

Quaternion Quaternion.invert(Quaternion q)

Parameter Type Description
q Quaternion Quaternion to get inverted version of.

Returns an inverted version of the given Quaternion.

Quaternion.dot(Quaternion q1, Quaternion q2)

local q1 = Quaternion(1, 0, 0, 0);
local q2 = Quaternion(1, 0, 0, 0);
local number = Quaternion.dot(q1, q2);

number Quaternion.dot(Quaternion q1, Quaternion q2)

Parameter Type Description
q1 Quaternion Quaternion get dot product of.
q2 Quaternion Quaternion get dot product of.

Returns the dot product of the two given Quaternions.

> Matrix4

Matrix4

local mat = Matrix4(1.0); -- identity matrix

Matrix4 Matrix4(number leading)

Parameter Type Description
leading number Number to have along leading diagonal of Matrix4.

Construct a diagonal Matrix4 with the leading edge filled with the given number.

Matrix4.create_translation_matrix(Vector3 translation)

local translationMatrix = Matrix4.create_translation_matrix(Vector3(0, 3, -10));

Matrix4 Matrix4.create_translation_matrix(Vector3 translation)

Parameter Type Description
translation Vector3 Translation to get.

Create a Matrix4 representing a translation transformation.

Matrix4.create_scale_matrix(Vector3 scale)

local scaleMatrix = Matrix4.create_scale_matrix(Vector3(0.1, 0.1, 0.1));

Matrix4 Matrix4.create_scale_matrix(Vector3 scale)

Parameter Type Description
scale Vector3 Scale to get.

Create a Matrix4 representing a scale transformation.

Matrix4.create_from_quaternion(Quaternion rotation)

local myQuat = Quaternion.create_from_axis_angle(Vector3(0, 1, 0), math.pi/2.0);
local rotation = Matrix4.create_from_quaternion(myQuat);

Matrix4 Matrix4.create_from_quaternion(Quaternion rotation)

Parameter Type Description
rotation Quaternion Rotation to get.

Create a Matrix4 representing a rotation transformation.

Matrix4.transpose(Matrix4 mat)

local mat = Matrix4(1.0); -- identity matrix
local mat = Matrix4.transpose(mat); -- identity matrix

Matrix4 Matrix4.transpose(Matrix4 mat)

Parameter Type Description
mat Matrix4 Matrix4 to transpose.

Returns a transposed (swapped rows and columns) version of the given Matrix4.

Matrix4.inverse(Matrix4 mat)

local mat = Matrix4(1.0); -- identity matrix
local mat = Matrix4.inverse(mat); -- identity matrix

Matrix4 Matrix4.inverse(Matrix4 mat)

Parameter Type Description
mat Matrix4 Matrix4 to return inverse of.

Returns a matrix-inversed version of the given Matrix4.

> Script

Script.spawn_prefab

camera = Script.spawn_prefab("player", Vector3(0, 0, 0));

Entity Script.spawn_prefab(string prefabPath, Vector3 position)

Parameter Type Description
prefabPath string Path to prefab file to spawn in, excluding .prefab suffix.
position Vector3 Position to spawn prefab at.

Create an entity from the given prefab at the given position.

Script.is_next_message()

if (Script.is_next_message()) then
  local msg = Script.next_message()
end

bool Script.is_next_message()

Returns true if a new message is available for the Lua script and false otherwise.

Script.next_message()

if (Script.is_next_message()) then
  local msg = Script.next_message()
end

table Script.next_message()

Returns a table with the message contents.

Script.get_world_transform(Entity entity)

Matrix4 Script.get_world_transform(Entity entity)

local myEntity = Script.spawn_prefab("x", Vector3(0, 0, 0));
local worldTransform = Script.get_world_transform(myEntity);
Parameter Type Description
entity Entity Entity to get world transform of.

Get the world transform of a given entity.

Script.get_local_transform(Entity entity)

Matrix4 Script.get_local_transform(Entity entity)

local myEntity = Script.spawn_prefab("x", Vector3(0, 0, 0));
local localTransform = Script.get_local_transform(myEntity);
Parameter Type Description
entity Entity Entity to get local transform of.

Get the local transform (transform relative to parent) of a given entity.

Script.set_entity_animation_index(Entity entity, number animationIndex)

Script.set_entity_animation_index(Entity entity, number animationIndex)

Script.set_entity_animation_index(myEntity, 3);
Parameter Type Description
entity Entity Entity to set animation index of.
animationIndex number Index of animation to play.

Set the animation that is currently playing for a given entity.

Script.set_skybox_material(string skyboxMaterialPath)

Script.set_skybox_material(string skyboxMaterialPath) lua Script.set_skybox_material("skyDome01.material");

Parameter Type Description
skyboxMaterialPath string Path to material to render skybox with.

Set the material the skybox is currently being rendered with.

Script.create_gui_panel(number startX, number startY, number endX, number endY, string materialPath)

Entity Script.create_gui_panel(number startX, number startY, number endX, number endY, string materialPath)

guiStartTitlePanel = Script.create_gui_panel(-0.8, 0.9, 0.8, 0.3, "menuTitlePanel.material");
Parameter Type Description
startX number Start x-coordinate of the panel.
startY number Start y-coordinate of the panel.
endX number End x-coordinate of the panel.
endY number End y-coordinate of the panel.
materialPath string Path to material to render panel with.

Creates a panel (just a non-interactive, 2D UI element).

Script.create_gui_button(number startX, number startY, number endX, number endY, string defaultMaterialPath, string pressedMaterialPath, string hoverMaterialPath)

Entity Script.create_gui_button(number startX, number startY, number endX, number endY, string defaultMaterialPath, string pressedMaterialPath, string hoverMaterialPath)

guiToggleHardModeButton = Script.create_gui_button(-0.10, -0.20, 0.10, -0.40,  "s_difficulty_default.material", "s_difficulty_pressed.material", "s_difficulty_hover.material");
Parameter Type Description
startX number Start x-coordinate of the panel.
startY number Start y-coordinate of the panel.
endX number End x-coordinate of the panel.
endY number End y-coordinate of the panel.
defaultMaterialPath string Material to render with if button isn’t pressed or hovered over.
pressedMaterialPath string Material to render with if button is pressed.
hoverMaterialPath string Material to render with if button is hovered over.

Creates a gui button that sends button press events.

Script.get_local_translation(Entity entity)

Vector3 Script.get_local_translation(Entity entity)

local chaserTranslate = Script.get_local_translation(chaser);
Parameter Type Description
entity Entity Entity to set the local translation of.

Get the local translation (translation relative to parent) of the given entity.

Script.get_world_translation(Entity entity)

Vector3 Script.get_world_translation(Entity entity)

local chaserWTranslate = Script.get_world_translation(chaser);
Parameter Type Description
entity Entity Entity to set the world translation of.

Get the world translation (translation relative to world coordinate system) of the given entity.

Script.get_local_scale(Entity entity)

Vector3 Script.get_local_scale(Entity entity)

local chaserScale = Script.get_local_scale(chaser);
Parameter Type Description
entity Entity Entity to set the local scale of.

Get the local scale of the given entity.

Script.get_world_scale(Entity entity)

Vector3 Script.get_world_scale(Entity entity)

local chaserWScale = Script.get_world_scale(chaser);
Parameter Type Description
entity Entity Entity to get the world scale of.

Get the world scale of the given entity.

Script.set_local_scale(Entity entity, Vector3 scale)

Vector3 Script.set_local_scale(Entity entity, Vector3 scale)

Script.set_local_scale(trigger_area, Vector3(5.0, 5.0, 5.0));
Parameter Type Description
entity Entity Entity to set the local scale of.
scale Vector3 New scale to set.

Set the local scale of the given entity.

Script.get_local_orientation(Entity entity)

Quaternion Script.get_local_orientation(Entity entity)

localOrientation = Script.get_local_orientation(player);
Parameter Type Description
entity Entity Entity to set the local orientation of.

Get the local orientation of the given entity.

Script.get_world_orientation(Entity entity)

Quaternion Script.get_world_orientation(Entity entity)

worldOrientation = Script.get_world_orientation(player);
Parameter Type Description
entity Entity Entity to get the world orientation of.

Get the world orientation of the given entity.

Script.set_local_orientation(Entity entity, Quaternion orientation)

Quaternion Script.set_local_orientation(Entity entity, Quaternion orientation)

Script.set_local_translation(ent, myRot);
Parameter Type Description
entity Entity Entity to set the local orientation of.
orientation Quaternion New orientation to set.

Set the local orientation of the given entity.

Script.destroy_entity(Entity entity)

Script.destroy_entity(Entity entity)

Script.destroy_entity(guiStartPlayButton)
Parameter Type Description
entity Entity Entity to destroy.

Send a message to all systems, telling them to destroy the given entity.

Script.set_material_parameter(string materialResourceFilePath, string parameterName, string parameterType, any data)

Script.set_material_parameter(string materialResourceFilePath, string parameterName, string parameterType, any data)

Script.set_material_parameter("colour.material", "u_colour", "vec4", Vector4(0.8, 0.8, 0.8, 1.0))
Parameter Type Description
materialResourceFilePath string Material to set parameter of.
parameterName string Parameter in material to manipulate.
parameterType string Type of parameter (vec4, int, mat4, float).
data any New data to give to parameter.

Set the value of a parameter in a given material.

Script.quit()

Script.quit()

Script.quit() -- Shutdown everything 

Sends a quit message to all systems, telling them to shutdown. Shuts down the engine.

Script.set_pause(bool shouldPause)

Script.set_pause(true); -- Pause game
Script.set_pause(false); -- Unpause game

Script.set_pause(bool shouldPause)

Parameter Type Description
shouldPause bool true to pause, false to unpause.

Systems will receive pause message, up to them whether they should pause or not.

> Input

Input.is_key_pressed(string keyName)

if (Input.is_key_pressed("w")) then
  print("W pressed")
end

bool Input.is_key_pressed(string keyName)

Parameter Type Description
keyName string Name of key to check if pressed.

Returns true if the given key is pressed and false otherwise.

Input.get_mouse_delta_xy()

dX, dY = Input.get_mouse_delta_xy()

deltaX, deltaY Input.get_mouse_delta_xy()

Returns the amount (in pixels) the mouse has moved since the last frame.

Lua