Vector math is used in Teardown scripts to represent 3D positions, directions,
rotations and transforms. The base types are vectors, quaternions and transforms.
Vectors and quaternions are indexed tables with three and four components. Transforms
are tables consisting of one vector (pos) and one quaternion (rot)
An Entity is the basis of most objects in the Teardown engine (bodies, shapes, lights, locations, etc).
All entities can have tags, which is a way to store custom properties on entities for scripting purposes.
Some tags are also reserved for engine use. See documentation for details.
A body represents a rigid body in the scene. It can be either static or dynamic. Only dynamic bodies are
affected by physics.
A shape is a voxel object and always owned by a body. A single body may contain multiple shapes. The transform
of shape is expressed in the parent body coordinate system.
Locations are transforms placed in the editor as markers. Location transforms are always expressed in
world space coordinates.
Joints are used to physically connect two shapes. There are several types of joints and they are typically
placed in the editor. When destruction occurs, joints may be transferred to new shapes, detached or
completely disabled.
Light sources can be of several differnt types and configured in the editor. If a light source is owned
by a shape, the intensity of the light source is scaled by the emissive scale of that shape. If the
parent shape breaks, the emissive scale is set to zero and the light source is disabled. A light source
without a parent shape will always emit light, unless exlicitly disabled by a script.
Triggers can be placed in the scene and queried by scripts to see if something is within a certain part
of the scene.
Vehicles are set up in the editor and consists of multiple parts owned by a vehicle entity.
Sound functions are used for playing sounds or loops in the world. There sound functions are
alwyas positioned and will be affected by acoustics simulation. If you want to play dry sounds
without acoustics you should use UiSound and UiSoundLoop in the User Interface section.
Sprites are 2D images in PNG or JPG format that can be drawn into the world. Sprites can be
drawn with ot without depth test (occluded by geometry). Sprites will not be affected by lighting
but they will go through post processing. If you want to display positioned information to the player as
an overlay, you probably want to use the Ui functions in combination with UiWorldToPixel instead.
Functions to configure and emit particles, used for fire, smoke and other visual effects. There are
two types of particles in Teardown - plain particles and smoke particles. Plain particles are simple
billboard particles simulated with gravity and velocity that can be used for fire, debris, rain, snow and such.
Smoke particles are only intended for smoke and they are simulated with fluid dynamics internally and rendered
with some special tricks to get a more smoke-like appearance.
All functions in the particle API, except for SpawnParticle modify properties in the particle state, which is
then used when emitting particles, so the idea is to set up a state, and then emit one or several particles
using that state.
Most properties in the particle state can be either constant or animated over time. Supply a single argument
for constant, two argument for linear interpolation, and optionally a third argument for other types of
interpolation. There are also fade in and fade out parameters that fade from and to zero.
The spawn API can be used to add entities into the existing scenes. You can spawn existing
prefab XML files or generate XML and pass it in as a lua string.
The user interface functions are used for drawing interactive 2D graphics and can only be
called from the draw function of a script. The ui functions are designed with the immediate
mode gui paradigm in mind and uses a cursor and state stack. Pushing and popping the stack is cheap
and designed to be called often.
Returns running time of this script. If called from update, this returns
the simulated time, otherwise it returns wall time.
Returns timestep of the last frame. If called from update, this returns
the simulation time step, which is always one 60th of a second (0.0166667).
If called from tick or draw it returns the actual time since last frame.
Set value of a number variable in the global context with an optional transition.
If a transition is provided the value will animate from current value to the new value during the transition time.
Transition can be one of the following:
|
| linear | Linear transition |
| cosine | Slow at beginning and end |
| easein | Slow at beginning |
| easeout | Slow at end |
| bounce | Bounce and overshoot new value |
myValue = 0
SetValue("myValue", 1, "linear", 0.5)
This will change the value of myValue from 0 to 1 in a linear fasion over 0.5 seconds
PauseMenuButton
clicked = PauseMenuButton(title)
Arguments
title (string) – Text on button
Return value
clicked (boolean) – True if clicked, false otherwise
Calling this function will add a button on the bottom bar when the game is paused. Use this
as a way to bring up mod settings or other user interfaces while the game is running.
Call this function every frame from the tick function for as long as the pause menu button
should still be visible.
function tick()
if PauseMenuButton("MyMod Settings") then
visible = true
end
end
function draw()
if visible then
UiMakeInteractive()
...
end
end
StartLevel
StartLevel(mission, path, [layers], [passThrough])
Arguments
mission (string) – An identifier of your choice
path (string) – Path to level XML file
layers (string, optional) – Active layers. Default is no layers.
passThrough (boolean, optional) – If set, loading screen will have no text and music will keep playing
Return value
none
Start a level
--Start level with no active layers
StartLevel("level1", "MOD/level1.xml")
--Start level with two layers
StartLevel("level1", "MOD/level1.xml", "vehicles targets")
SetPaused
SetPaused(paused)
Arguments
paused (boolean) – True if game should be paused
Return value
none
Set paused state of the game
--Pause game and bring up pause menu on HUD
SetPaused(true)
Restart
Restart()
Arguments
none
Return value
none
Restart level
if shouldRestart then
Restart()
end
Menu
Menu()
Arguments
none
Return value
none
Go to main menu
if shouldExitLevel then
Menu()
end
ClearKey
ClearKey(key)
Arguments
key (string) – Registry key to clear
Return value
none
Remove registry node, including all child nodes.
--If the registry looks like this:
-- score
-- levels
-- level1 = 5
-- level2 = 4
ClearKey("score.levels")
--Afterwards, the registry will look like this:
-- score
ListKeys
children = ListKeys(parent)
Arguments
parent (string) – The parent registry key
Return value
children (table) – Indexed table of strings with child keys
List all child keys of a registry node.
--If the registry looks like this:
-- score
-- levels
-- level1 = 5
-- level2 = 4
local list = ListKeys("score.levels")
for i=1, #list do
print(list[i])
end
--This will output:
--level1
--level2
HasKey
exists = HasKey(key)
Arguments
key (string) – Registry key
Return value
exists (boolean) – True if key exists
Returns true if the registry contains a certain key
local foo = HasKey("score.levels")
SetInt
SetInt(key, value)
Arguments
key (string) – Registry key
value (number) – Desired value
Return value
none
SetInt("score.levels.level1", 4)
GetInt
value = GetInt(key)
Arguments
key (string) – Registry key
Return value
value (number) – Integer value of registry node or zero if not found
local a = GetInt("score.levels.level1")
SetFloat
SetFloat(key, value)
Arguments
key (string) – Registry key
value (number) – Desired value
Return value
none
SetFloat("level.time", 22.3)
GetFloat
value = GetFloat(key)
Arguments
key (string) – Registry key
Return value
value (number) – Float value of registry node or zero if not found
local time = GetFloat("level.time")
SetBool
SetBool(key, value)
Arguments
key (string) – Registry key
value (boolean) – Desired value
Return value
none
SetBool("level.robots.enabled", true)
GetBool
value = GetBool(key)
Arguments
key (string) – Registry key
Return value
value (boolean) – Boolean value of registry node or false if not found
local isRobotsEnabled = GetBool("level.robots.enabled")
SetString
SetString(key, value)
Arguments
key (string) – Registry key
value (string) – Desired value
Return value
none
SetString("level.name", "foo")
GetString
value = GetString(key)
Arguments
key (string) – Registry key
Return value
value (string) – String value of registry node or "" if not found
local name = GetString("level.name")
Vec
vec = Vec([x], [y], [z])
Arguments
x (number, optional) – X value
y (number, optional) – Y value
z (number, optional) – Z value
Return value
vec (table) – New vector
Create new vector and optionally initializes it to the provided values.
A Vec is equivalent to a regular lua table with three numbers.
--These are equivalent
local a1 = Vec()
local a2 = {0, 0, 0}
--These are equivalent
local b1 = Vec(0, 1, 0)
local b2 = {0, 1, 0}
VecCopy
new = VecCopy(org)
Arguments
org (table) – A vector
Return value
new (table) – Copy of org vector
Vectors should never be assigned like regular numbers. Since they are
implemented with lua tables assignment means two references pointing to
the same data. Use this function instead.
--Do this to assign a vector
local right1 = Vec(1, 2, 3)
local right2 = VecCopy(right1)
--Never do this unless you REALLY know what you're doing
local wrong1 = Vec(1, 2, 3)
local wrong2 = wrong1
VecLength
length = VecLength(vec)
Arguments
vec (table) – A vector
Return value
length (number) – Length (magnitude) of the vector
local v = Vec(1,1,0)
local l = VecLength(v)
--l now equals 1.41421356
VecNormalize
norm = VecNormalize(vec)
Arguments
vec (table) – A vector
Return value
norm (table) – A vector of length 1.0
If the input vector is of zero length, the function returns {0,0,1}
local v = Vec(0,3,0)
local n = VecNormalize(v)
--n now equals {0,1,0}
VecScale
norm = VecScale(vec, scale)
Arguments
vec (table) – A vector
scale (number) – A scale factor
Return value
norm (table) – A scaled version of input vector
local v = Vec(1,2,3)
local n = VecScale(v, 2)
--n now equals {2,4,6}
VecAdd
c = VecAdd(a, b)
Arguments
a (table) – Vector
b (table) – Vector
Return value
c (table) – New vector with sum of a and b
local a = Vec(1,2,3)
local b = Vec(3,0,0)
local c = VecAdd(a, b)
--c now equals {4,2,3}
VecSub
c = VecSub(a, b)
Arguments
a (table) – Vector
b (table) – Vector
Return value
c (table) – New vector representing a-b
local a = Vec(1,2,3)
local b = Vec(3,0,0)
local c = VecSub(a, b)
--c now equals {-2,2,3}
VecDot
c = VecDot(a, b)
Arguments
a (table) – Vector
b (table) – Vector
Return value
c (number) – Dot product of a and b
local a = Vec(1,2,3)
local b = Vec(3,1,0)
local c = VecDot(a, b)
--c now equals 5
VecCross
c = VecCross(a, b)
Arguments
a (table) – Vector
b (table) – Vector
Return value
c (table) – Cross product of a and b (also called vector product)
local a = Vec(1,0,0)
local b = Vec(0,1,0)
local c = VecCross(a, b)
--c now equals {0,0,1}
VecLerp
c = VecLerp(a, b, t)
Arguments
a (table) – Vector
b (table) – Vector
t (number) – fraction (usually between 0.0 and 1.0)
Return value
c (table) – Linearly interpolated vector between a and b, using t
local a = Vec(2,0,0)
local b = Vec(0,4,2)
local t = 0.5
--These two are equivalent
local c1 = VecLerp(a, b, t)
lcoal c2 = VecAdd(VecScale(a, 1-t), VecScale(b, t))
--c1 and c2 now equals {1, 2, 1}
Quat
quat = Quat([x], [y], [z], [w])
Arguments
x (number, optional) – X value
y (number, optional) – Y value
z (number, optional) – Z value
w (number, optional) – W value
Return value
quat (table) – New quaternion
Create new quaternion and optionally initializes it to the provided values.
Do not attempt to initialize a quaternion with raw values unless you know
what you are doing. Use QuatEuler or QuatAxisAngle instead.
If no arguments are given, a unit quaternion will be created: {0, 0, 0, 1}.
A quaternion is equivalent to a regular lua table with four numbers.
--These are equivalent
local a1 = Quat()
local a2 = {0, 0, 0, 1}
QuatCopy
new = QuatCopy(org)
Arguments
org (table) – Quaternion
Return value
new (table) – Copy of org quaternion
Quaternions should never be assigned like regular numbers. Since they are
implemented with lua tables assignment means two references pointing to
the same data. Use this function instead.
--Do this to assign a quaternion
local right1 = QuatEuler(0, 90, 0)
local right2 = QuatCopy(right1)
--Never do this unless you REALLY know what you're doing
local wrong1 = QuatEuler(0, 90, 0)
local wrong2 = wrong1
QuatAxisAngle
quat = QuatAxisAngle(axis, angle)
Arguments
axis (table) – Rotation axis, unit vector
angle (number) – Rotation angle in degrees
Return value
quat (table) – New quaternion
Create a quaternion representing a rotation around a specific axis
--Create quaternion representing rotation 30 degrees around Y axis
local q = QuatAxisAngle(Vec(0,1,0), 30)
QuatEuler
quat = QuatEuler(x, y, z)
Arguments
x (number) – Angle around X axis in degrees, sometimes also called roll or bank
y (number) – Angle around Y axis in degrees, sometimes also called yaw or heading
z (number) – Angle around Z axis in degrees, sometimes also called pitch or attitude
Return value
quat (table) – New quaternion
Create quaternion using euler angle notation. The order of applied rotations uses the
"NASA standard aeroplane" model:
- Rotation around Y axis (yaw or heading)
- Rotation around Z axis (pitch or attitude)
- Rotation around X axis (roll or bank)
--Create quaternion representing rotation 30 degrees around Y axis and 25 degrees around Z axis
local q = QuatEuler(0, 30, 25)
GetQuatEuler
x, y, z = GetQuatEuler(quat)
Arguments
quat (table) – Quaternion
Return value
x (number) – Angle around X axis in degrees, sometimes also called roll or bank
y (number) – Angle around Y axis in degrees, sometimes also called yaw or heading
z (number) – Angle around Z axis in degrees, sometimes also called pitch or attitude
Return euler angles from quaternion. The order of rotations uses the "NASA standard aeroplane" model:
- Rotation around Y axis (yaw or heading)
- Rotation around Z axis (pitch or attitude)
- Rotation around X axis (roll or bank)
--Return euler angles from quaternion q
rx, ry, rz = GetQuatEuler(q)
QuatLookAt
quat = QuatLookAt(eye, target)
Arguments
eye (table) – Vector representing the camera location
target (table) – Vector representing the point to look at
Return value
quat (table) – New quaternion
Create a quaternion pointing the negative Z axis (forward) towards
a specific point, keeping the Y axis upwards. This is very useful
for creating camera transforms.
local eye = Vec(0, 10, 0)
local target = Vec(0, 1, 5)
local rot = QuatLookAt(eye, target)
SetCameraTransform(Transform(eye, rot))
QuatSlerp
c = QuatSlerp(a, b, t)
Arguments
a (table) – Quaternion
b (table) – Quaternion
t (number) – fraction (usually between 0.0 and 1.0)
Return value
c (table) – New quaternion
Spherical, linear interpolation between a and b, using t. This is
very useful for animating between two rotations.
local a = QuatEuler(0, 10, 0)
local b = QuatEuler(0, 0, 45)
--Create quaternion half way between a and b
local q = QuatSlerp(a, b, 0.5)
QuatRotateQuat
c = QuatRotateQuat(a, b)
Arguments
a (table) – Quaternion
b (table) – Quaternion
Return value
c (table) – New quaternion
Rotate one quaternion with another quaternion. This is mathematically
equivalent to c = a * b using quaternion multiplication.
local a = QuatEuler(0, 10, 0)
local b = QuatEuler(0, 0, 45)
local q = QuatRotateQuat(a, b)
--q now represents a rotation first 10 degrees around
--the Y axis and then 45 degrees around the Z axis.
QuatRotateVec
vec = QuatRotateVec(a, vec)
Arguments
a (table) – Quaternion
vec (table) – Vector
Return value
vec (table) – Rotated vector
Rotate a vector by a quaternion
local q = QuatEuler(0, 10, 0)
local v = Vec(1, 0, 0)
local r = QuatRotateVec(q, v)
--r is now vector a rotated 10 degrees around the Y axis
Transform
transform = Transform([pos], [rot])
Arguments
pos (table, optional) – Vector representing transform position
rot (table, optional) – Quaternion representing transform rotation
Return value
transform (table) – New transform
A transform is a regular lua table with two entries: pos and rot,
a vector and quaternion representing transform position and rotation.
--Create transform located at {0, 0, 0} with no rotation
local t1 = Transform()
--Create transform located at {10, 0, 0} with no rotation
local t2 = Transform(Vec(10, 0,0))
--Create transform located at {10, 0, 0}, rotated 45 degrees around Y axis
local t2 = Transform(Vec(10, 0,0), QuatEuler(0, 45, 0))
TransformCopy
new = TransformCopy(org)
Arguments
org (table) – Transform
Return value
new (table) – Copy of org transform
Transforms should never be assigned like regular numbers. Since they are
implemented with lua tables assignment means two references pointing to
the same data. Use this function instead.
--Do this to assign a quaternion
local right1 = Transform(Vec(1,0,0), QuatEuler(0, 90, 0))
local right2 = TransformCopy(right1)
--Never do this unless you REALLY know what you're doing
local wrong1 = Transform(Vec(1,0,0), QuatEuler(0, 90, 0))
local wrong2 = wrong1
TransformToParentTransform
transform = TransformToParentTransform(parent, child)
Arguments
parent (table) – Transform
child (table) – Transform
Return value
transform (table) – New transform
Transform child transform out of the parent transform.
This is the opposite of TransformToLocalTransform.
local b = GetBodyTransform(body)
local s = GetShapeLocalTransform(shape)
--b represents the location of body in world space
--s represents the location of shape in body space
local w = TransformToParentTransform(b, s)
--w now represents the location of shape in world space
TransformToLocalTransform
transform = TransformToLocalTransform(parent, child)
Arguments
parent (table) – Transform
child (table) – Transform
Return value
transform (table) – New transform
Transform one transform into the local space of another transform.
This is the opposite of TransformToParentTransform.
local b = GetBodyTransform(body)
local w = GetShapeWorldTransform(shape)
--b represents the location of body in world space
--w represents the location of shape in world space
local s = TransformToLocalTransform(b, w)
--s now represents the location of shape in body space.
TransformToParentVec
r = TransformToParentVec(t, v)
Arguments
t (table) – Transform
v (table) – Vector
Return value
r (table) – Transformed vector
Transfom vector v out of transform t only considering rotation.
local t = GetBodyTransform(body)
local localUp = Vec(0, 1, 0)
local up = TransformToParentVec(t, localUp)
--up now represents the local body up direction in world space
TransformToLocalVec
r = TransformToLocalVec(t, v)
Arguments
t (table) – Transform
v (table) – Vector
Return value
r (table) – Transformed vector
Transfom vector v into transform t only considering rotation.
local t = GetBodyTransform(body)
local worldUp = Vec(0, 1, 0)
local up = TransformToLocalVec(t, worldUp)
--up now represents the world up direction in local body space
TransformToParentPoint
r = TransformToParentPoint(t, p)
Arguments
t (table) – Transform
p (table) – Vector representing position
Return value
r (table) – Transformed position
Transfom position p out of transform t.
local t = GetBodyTransform(body)
local bodyPoint = Vec(0, 0, -1)
local p = TransformToParentPoint(t, bodyPoint)
--p now represents the local body point {0, 0, -1 } in world space
TransformToLocalPoint
r = TransformToLocalPoint(t, p)
Arguments
t (table) – Transform
p (table) – Vector representing position
Return value
r (table) – Transformed position
Transfom position p into transform t.
local t = GetBodyTransform(body)
local worldOrigo = Vec(0, 0, 0)
local p = TransformToLocalPoint(t, worldOrigo)
--p now represents the position of world origo in local body space
SetTag
SetTag(handle, tag, [value])
Arguments
handle (number) – Entity handle
tag (string) – Tag name
value (string, optional) – Tag value
Return value
none
--Add "special" tag to an entity
SetTag(handle, "special")
--Add "team" tag to an entity and give it value "red"
SetTag(handle, "team", "red")
RemoveTag
RemoveTag(handle, tag)
Arguments
handle (number) – Entity handle
tag (string) – Tag name
Return value
none
Remove tag from an entity. If the tag had a value it is removed too.
RemoveTag(handle, "special")
HasTag
exists = HasTag(handle, tag)
Arguments
handle (number) – Entity handle
tag (string) – Tag name
Return value
exists (boolean) – Returns true if entity has tag
SetTag(handle, "special")
local hasSpecial = HasTag(handle, "special")
-- hasSpecial will be true
GetTagValue
value = GetTagValue(handle, tag)
Arguments
handle (number) – Entity handle
tag (string) – Tag name
Return value
value (string) – Returns the tag value, if any. Empty string otherwise.
SetTag(handle, "special")
value = GetTagValue(handle, "special")
-- value will be ""
SetTag(handle, "special", "foo")
value = GetTagValue(handle, "special")
-- value will be "foo"
GetDescription
description = GetDescription(handle)
Arguments
handle (number) – Entity handle
Return value
description (string) – The description string
All entities can have an associated description. For bodies and
shapes this can be provided through the editor. This function
retrieves that description.
local desc = GetDescription(body)
SetDescription
SetDescription(handle, description)
Arguments
handle (number) – Entity handle
description (string) – The description string
Return value
none
All entities can have an associated description. The description for
bodies and shapes will show up on the HUD when looking at them.
SetDescription(body, "Target object")
Delete
Delete(handle)
Arguments
handle (number) – Entity handle
Return value
none
Remove an entity from the scene. All entities owned by this entity
will also be removed.
Delete(body)
--All shapes associated with body will also be removed
IsHandleValid
exists = IsHandleValid(handle)
Arguments
handle (number) – Entity handle
Return value
exists (boolean) – Returns true if the entity pointed to by handle still exists
valid = IsHandleValid(body)
--valid is true if body still exists
Delete(body)
valid = IsHandleValid(body)
--valid will now be false
GetEntityType
type = GetEntityType(handle)
Arguments
handle (number) – Entity handle
Return value
type (string) – Type name of the provided entity
Returns the type name of provided entity, for example "body", "shape", "light", etc.
local t = GetEntityType(e)
if t == "body" then
--e is a body handle
end
FindBody
handle = FindBody(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
handle (number) – Handle to first body with specified tag or zero if not found
--Search for a body tagged "target" in script scope
local target = FindBody("target")
--Search for a body tagged "escape" in entire scene
local escape = FindBody("escape", true)
FindBodies
list = FindBodies(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
list (table) – Indexed table with handles to all bodies with specified tag
--Search for bodies tagged "target" in script scope
local targets = FindBodies("target")
for i=1, #targets do
local target = targets[i]
...
end
GetBodyTransform
transform = GetBodyTransform(handle)
Arguments
handle (number) – Body handle
Return value
transform (table) – Transform of the body
local t = GetBodyTransform(body)
SetBodyTransform
SetBodyTransform(handle, transform)
Arguments
handle (number) – Body handle
transform (table) – Desired transform
Return value
none
--Move a body 1 meter upwards
local t = GetBodyTransform(body)
t.pos = VecAdd(t.pos, Vec(0, 1, 0))
SetBodyTransform(body, t)
GetBodyMass
mass = GetBodyMass(handle)
Arguments
handle (number) – Body handle
Return value
mass (number) – Body mass. Static bodies always return zero mass.
local mass = GetBodyMass(body)
IsBodyDynamic
dynamic = IsBodyDynamic(handle)
Arguments
handle (number) – Body handle
Return value
dynamic (boolean) – Return true if body is dynamic
Check if body is dynamic. Note that something that was created static
may become dynamic due to destruction.
local dynamic = IsBodyDynamic(body)
SetBodyDynamic
SetBodyDynamic(handle, dynamic)
Arguments
handle (number) – Body handle
dynamic (boolean) – True for dynamic. False for static.
Return value
none
Change the dynamic state of a body. There is very limited use for this
function. In most situations you should leave it up to the engine to decide.
Use with caution.
SetBodyDynamic(body, false)
SetBodyVelocity
SetBodyVelocity(handle, velocity)
Arguments
handle (number) – Body handle (should be a dynamic body)
velocity (table) – Vector with linear velocity
Return value
none
This can be used for animating bodies with preserved physical interaction,
but in most cases you are better off with a motorized joint instead.
local vel = Vec(2,0,0)
SetBodyVelocity(body, vel)
GetBodyVelocity
velocity = GetBodyVelocity(handle)
Arguments
handle (number) – Body handle (should be a dynamic body)
Return value
velocity (table) – Linear velocity as vector
local linVel = GetBodyVelocity(body)
GetBodyVelocityAtPos
velocity = GetBodyVelocityAtPos(handle, pos)
Arguments
handle (number) – Body handle (should be a dynamic body)
pos (table) – World space point as vector
Return value
velocity (table) – Linear velocity on body at pos as vector
Return the velocity on a body taking both linear and angular velocity into account.
local vel = GetBodyVelocityAtPos(body, pos)
SetBodyAngularVelocity
SetBodyAngularVelocity(handle, angVel)
Arguments
handle (number) – Body handle (should be a dynamic body)
angVel (table) – Vector with angular velocity
Return value
none
This can be used for animating bodies with preserved physical interaction,
but in most cases you are better off with a motorized joint instead.
local angVel = Vec(2,0,0)
SetBodyAngularVelocity(body, angVel)
GetBodyAngularVelocity
angVel = GetBodyAngularVelocity(handle)
Arguments
handle (number) – Body handle (should be a dynamic body)
Return value
angVel (table) – Angular velocity as vector
local angVel = GetBodyAngularVelocity(body)
IsBodyActive
active = IsBodyActive(handle)
Arguments
handle (number) – Body handle
Return value
active (boolean) – Return true if body is active
Check if body is body is currently simulated. For performance reasons,
bodies that don't move are taken out of the simulation. This function
can be used to query the active state of a specific body. Only dynamic
bodies can be active.
if IsBodyActive(body) then
...
end
SetBodyActive
SetBodyActive(handle, active)
Arguments
handle (number) – Body handle
active (boolean) – Set to tru if body should be active (simulated)
Return value
none
This function makes it possible to manually activate and deactivate bodies to include or
exclude in simulation. The engine normally handles this automatically, so use with care.
--Wake up body
SetBodyActive(body, true)
--Put body to sleep
SetBodyActive(body, false)
ApplyBodyImpulse
ApplyBodyImpulse(handle, position, impulse)
Arguments
handle (number) – Body handle (should be a dynamic body)
position (table) – World space position as vector
impulse (table) – World space impulse as vector
Return value
none
Apply impulse to dynamic body at position (give body a push).
local pos = Vec(0,1,0)
local imp = Vec(0,0,10)
ApplyBodyImpulse(body, pos, imp)
GetBodyShapes
list = GetBodyShapes(handle)
Arguments
handle (number) – Body handle
Return value
list (table) – Indexed table of shape handles
Return handles to all shapes owned by a body
local shapes = GetBodyShapes(body)
for i=1,#shapes do
local shape = shapes[i]
end
GetBodyVehicle
handle = GetBodyVehicle(body)
Arguments
body (number) – Body handle
Return value
handle (number) – Get parent vehicle for body, or zero if not part of vehicle
local vehicle = GetBodyVehicle(body)
GetBodyBounds
min, max = GetBodyBounds(handle)
Arguments
handle (number) – Body handle
Return value
min (table) – Vector representing the AABB lower bound
max (table) – Vector representing the AABB upper bound
Return the world space, axis-aligned bounding box for a body.
local min, max = GetBodyBounds(body)
local boundsSize = VecSub(max, min)
local center = VecLerp(min, max, 0.5)
GetBodyCenterOfMass
point = GetBodyCenterOfMass(handle)
Arguments
handle (number) – Body handle
Return value
point (table) – Vector representing local center of mass in body space
--Visualize center of mass on for body
local com = GetBodyCenterOfMass(body)
local worldPoint = TransformToParentPoint(GetBodyTransform(body), com)
DebugCross(worldPoint)
IsBodyVisible
visible = IsBodyVisible(handle, maxDist, [rejectTransparent])
Arguments
handle (number) – Body handle
maxDist (number) – Maximum visible distance
rejectTransparent (boolean, optional) – See through transparent materials. Default false.
Return value
visible (boolean) – Return true if body is visible
This will check if a body is currently visible in the camera frustum and
not occluded by other objects.
if IsBodyVisible(body, 25) then
--Body is within 25 meters visible to the camera
end
IsBodyBroken
broken = IsBodyBroken(handle)
Arguments
handle (number) – Body handle
Return value
broken (boolean) – Return true if body is broken
Determine if any shape of a body has been broken.
local broken = IsBodyBroken(body)
IsBodyJointedToStatic
result = IsBodyJointedToStatic(handle)
Arguments
handle (number) – Body handle
Return value
result (boolean) – Return true if body is in any way connected to a static body
Determine if a body is in any way connected to a static object, either by being static itself or
be being directly or indirectly jointed to something static.
local connectedToStatic = IsBodyJointedToStatic(body)
DrawBodyOutline
DrawBodyOutline(handle, [r], [g], [b], a)
Arguments
handle (number) – Body handle
r (number, optional) – Red
g (number, optional) – Green
b (number, optional) – Blue
a (number) – Alpha
Return value
none
Render next frame with an outline around specified body.
If no color is given, a white outline will be drawn.
--Draw white outline at 50% transparency
DrawBodyOutline(body, 0.5)
--Draw green outline, fully opaque
DrawBodyOutline(body, 0, 1, 0, 1)
DrawBodyHighlight
DrawBodyHighlight(handle, amount)
Arguments
handle (number) – Body handle
amount (number) – Amount
Return value
none
Flash the appearance of a body when rendering this frame. This is
used for valuables in the game.
DrawBodyHighlight(body, 0.5)
GetBodyClosestPoint
hit, point, normal, shape = GetBodyClosestPoint(body, origin)
Arguments
body (number) – Body handle
origin (table) – World space point
Return value
hit (boolean) – True if a point was found
point (table) – World space closest point
normal (table) – World space normal at closest point
shape (number) – Handle to closest shape
This will return the closest point of a specific body
local hit, p, n, s = GetBodyClosestPoint(body, Vec(0, 5, 0))
if hit then
--Point p of shape s is closest
end
ConstrainVelocity
ConstrainVelocity(bodyA, bodyB, point, dir, relVel, [min], [max])
Arguments
bodyA (number) – First body handle (zero for static)
bodyB (number) – Second body handle (zero for static)
point (table) – World space point
dir (table) – World space direction
relVel (number) – Desired relative velocity along the provided direction
min (number, optional) – Minimum impulse (default: -infinity)
max (number, optional) – Maximum impulse (default: infinity)
Return value
none
This will tell the physics solver to constrain the velocity between two bodies. The physics solver
will try to reach the desired goal, while not applying an impulse bigger than the min and max values.
This function should only be used from the update callback.
--Constrain the velocity between bodies A and B so that the relative velocity
--along the X axis at point (0, 5, 0) is always 3 m/s
ConstrainVelocity(a, b, Vec(0, 5, 0), Vec(1, 0, 0), 3)
ConstrainAngularVelocity
ConstrainAngularVelocity(bodyA, bodyB, dir, relAngVel, [min], [max])
Arguments
bodyA (number) – First body handle (zero for static)
bodyB (number) – Second body handle (zero for static)
dir (table) – World space direction
relAngVel (number) – Desired relative angular velocity along the provided direction
min (number, optional) – Minimum angular impulse (default: -infinity)
max (number, optional) – Maximum angular impulse (default: infinity)
Return value
none
This will tell the physics solver to constrain the angular velocity between two bodies. The physics solver
will try to reach the desired goal, while not applying an angular impulse bigger than the min and max values.
This function should only be used from the update callback.
--Constrain the angular velocity between bodies A and B so that the relative angular velocity
--along the Y axis is always 3 rad/s
ConstrainAngularVelocity(a, b, Vec(1, 0, 0), 3)
ConstrainPosition
ConstrainPosition(bodyA, bodyB, pointA, pointB, [maxVel], [maxImpulse])
Arguments
bodyA (number) – First body handle (zero for static)
bodyB (number) – Second body handle (zero for static)
pointA (table) – World space point for first body
pointB (table) – World space point for second body
maxVel (number, optional) – Maximum relative velocity (default: infinite)
maxImpulse (number, optional) – Maximum impulse (default: infinite)
Return value
none
This is a helper function that uses ConstrainVelocity to constrain a point on one
body to a point on another body while not affecting the bodies more than the provided
maximum relative velocity and maximum impulse. In other words: physically push on
the bodies so that pointA and pointB are aligned in world space. This is useful for
physically animating objects. This function should only be used from the update callback.
--Constrain the origo of body a to an animated point in the world
local worldPos = Vec(0, 3+math.sin(GetTime()), 0)
ConstrainPosition(a, 0, GetBodyTransform(a).pos, worldPos)
--Constrain the origo of body a to the origo of body b (like a ball joint)
ConstrainPosition(a, b, GetBodyTransform(a).pos, GetBodyTransform(b).pos)
ConstrainOrientation
ConstrainOrientation(bodyA, bodyB, quatA, quatB, [maxAngVel], [maxAngImpulse])
Arguments
bodyA (number) – First body handle (zero for static)
bodyB (number) – Second body handle (zero for static)
quatA (table) – World space orientation for first body
quatB (table) – World space orientation for second body
maxAngVel (number, optional) – Maximum relative angular velocity (default: infinite)
maxAngImpulse (number, optional) – Maximum angular impulse (default: infinite)
Return value
none
This is the angular counterpart to ConstrainPosition, a helper function that uses
ConstrainAngularVelocity to constrain the orientation of one body to the orientation
on another body while not affecting the bodies more than the provided maximum relative
angular velocity and maximum angular impulse. In other words: physically rotate the
bodies so that quatA and quatB are aligned in world space. This is useful for
physically animating objects. This function should only be used from the update callback.
--Constrain the orietation of body a to an upright orientation in the world
ConstrainOrientation(a, 0, GetBodyTransform(a).rot, Quat())
--Constrain the orientation of body a to the orientation of body b
ConstrainOrientation(a, b, GetBodyTransform(a).rot, GetBodyTransform(b).rot)
GetWorldBody
body = GetWorldBody()
Arguments
none
Return value
body (number) – Handle to the static world body
Every scene in Teardown has an implicit static world body that contains all shapes that are not explicitly assigned a body in the editor.
local w = GetWorldBody()
FindShape
handle = FindShape(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
handle (number) – Handle to first shape with specified tag or zero if not found
--Search for a shape tagged "mybox" in script scope
local target = FindShape("mybox")
--Search for a shape tagged "laserturret" in entire scene
local escape = FindShape("laserturret", true)
FindShapes
list = FindShapes(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
list (table) – Indexed table with handles to all shapes with specified tag
--Search for shapes tagged "alarmbox" in script scope
local shapes = FindShapes("alarmbox")
for i=1, #shapes do
local shape = shapes[i]
...
end
GetShapeLocalTransform
transform = GetShapeLocalTransform(handle)
Arguments
handle (number) – Shape handle
Return value
transform (table) – Return shape transform in body space
--Shape transform in body local space
local shapeTransform = GetShapeLocalTransform(shape)
--Body transform in world space
local bodyTransform = GetBodyTransform(GetShapeBody(shape))
--Shape transform in world space
local worldTranform = TransformToParentTransform(bodyTransform, shapeTransform)
SetShapeLocalTransform
SetShapeLocalTransform(handle, transform)
Arguments
handle (number) – Shape handle
transform (table) – Shape transform in body space
Return value
none
local transform = Transform(Vec(0, 1, 0), QuatEuler(0, 90, 0))
SetShapeLocalTransform(shape, transform)
GetShapeWorldTransform
transform = GetShapeWorldTransform(handle)
Arguments
handle (number) – Shape handle
Return value
transform (table) – Return shape transform in world space
This is a convenience function, transforming the shape out of body space
local worldTransform = GetShapeWorldTransform(shape)
--This is equivalent to
local shapeTransform = GetShapeLocalTransform(shape)
local bodyTransform = GetBodyTransform(GetShapeBody(shape))
worldTranform = TransformToParentTransform(bodyTransform, shapeTransform)
GetShapeBody
handle = GetShapeBody(handle)
Arguments
handle (number) – Shape handle
Return value
handle (number) – Body handle
Get handle to the body this shape is owned by. A shape is always owned by a body,
but can be transfered to a new body during destruction.
local body = GetShapeBody(shape)
GetShapeJoints
list = GetShapeJoints(shape)
Arguments
shape (number) – Shape handle
Return value
list (table) – Indexed table with joints connected to shape
local hinges = GetShapeJoints(door)
for i=1, #hinges do
local joint = hinges[i]
...
end
GetShapeLights
list = GetShapeLights(shape)
Arguments
shape (number) – Shape handle
Return value
list (table) – Indexed table of lights owned by shape
local lights = GetShapeLights(shape)
for i=1, #lights do
local light = lights[i]
...
end
GetShapeBounds
min, max = GetShapeBounds(handle)
Arguments
handle (number) – Shape handle
Return value
min (table) – Vector representing the AABB lower bound
max (table) – Vector representing the AABB upper bound
Return the world space, axis-aligned bounding box for a shape.
local min, max = GetShapeBounds(shape)
local boundsSize = VecSub(max, min)
local center = VecLerp(min, max, 0.5)
SetShapeEmissiveScale
SetShapeEmissiveScale(handle, scale)
Arguments
handle (number) – Shape handle
scale (number) – Scale factor for emissiveness
Return value
none
Scale emissiveness for shape. If the shape has light sources attached,
their intensity will be scaled by the same amount.
--Pulsate emissiveness and light intensity for shape
local scale = math.sin(GetTime())*0.5 + 0.5
SetShapeEmissiveScale(shape, scale)
GetShapeMaterialAtPosition
type, r, g, b, a = GetShapeMaterialAtPosition(handle, pos)
Arguments
handle (number) – Shape handle
pos (table) – Position in world space
Return value
type (string) – Material type
r (number) – Red
g (number) – Green
b (number) – Blue
a (number) – Alpha
Return material properties for a particular voxel
local hit, dist, normal, shape = QueryRaycast(pos, dir, 10)
if hit then
local hitPoint = VecAdd(pos, VecScale(dir, dist))
local mat = GetShapeMaterialAtPosition(shape, hitPoint)
DebugPrint("Raycast hit voxel made out of " .. mat)
end
GetShapeMaterialAtIndex
type, r, g, b, a = GetShapeMaterialAtIndex(handle, x, y, z)
Arguments
handle (number) – Shape handle
x (number) – X integer coordinate
y (number) – Y integer coordinate
z (number) – Z integer coordinate
Return value
type (string) – Material type
r (number) – Red
g (number) – Green
b (number) – Blue
a (number) – Alpha
Return material properties for a particular voxel in the voxel grid indexed by integer values.
The first index is zero (not one, as opposed to a lot of lua related things)
local mat = GetShapeMaterialAtIndex(shape, 0, 0, 0)
DebugPrint("The voxel closest to origo is of material: " .. mat)
GetShapeSize
xsize, ysize, zsize, scale = GetShapeSize(handle)
Arguments
handle (number) – Shape handle
Return value
xsize (number) – Size in voxels along x axis
ysize (number) – Size in voxels along y axis
zsize (number) – Size in voxels along z axis
scale (number) – The size of one voxel in meters (with default scale it is 0.1)
Return the size of a shape in voxels
local x, y, z = GetShapeSize(shape)
GetShapeVoxelCount
count = GetShapeVoxelCount(handle)
Arguments
handle (number) – Shape handle
Return value
count (number) – Number of voxels in shape
Return the number of voxels in a shape, not including empty space
local voxelCount = GetShapeVoxelCount(shape)
IsShapeVisible
visible = IsShapeVisible(handle, maxDist, [rejectTransparent])
Arguments
handle (number) – Shape handle
maxDist (number) – Maximum visible distance
rejectTransparent (boolean, optional) – See through transparent materials. Default false.
Return value
visible (boolean) – Return true if shape is visible
This will check if a shape is currently visible in the camera frustum and
not occluded by other objects.
if IsShapeVisible(shape, 25) then
--Shape is within 25 meters visible to the camera
end
IsShapeBroken
broken = IsShapeBroken(handle)
Arguments
handle (number) – Shape handle
Return value
broken (boolean) – Return true if shape is broken
Determine if shape has been broken. Note that a shape can be transfered
to another body during destruction, but might still not be considered
broken if all voxels are intact.
local broken = IsShapeBroken(shape)
DrawShapeOutline
DrawShapeOutline(handle, [r], [g], [b], a)
Arguments
handle (number) – Shape handle
r (number, optional) – Red
g (number, optional) – Green
b (number, optional) – Blue
a (number) – Alpha
Return value
none
Render next frame with an outline around specified shape.
If no color is given, a white outline will be drawn.
--Draw white outline at 50% transparency
DrawShapeOutline(shape, 0.5)
--Draw green outline, fully opaque
DrawShapeOutline(shape, 0, 1, 0, 1)
DrawShapeHighlight
DrawShapeHighlight(handle, amount)
Arguments
handle (number) – Shape handle
amount (number) – Amount
Return value
none
Flash the appearance of a shape when rendering this frame.
DrawShapeHighlight(shape, 0.5)
SetShapeCollisionFilter
SetShapeCollisionFilter(handle, layer, mask)
Arguments
handle (number) – Shape handle
layer (number) – Layer bits (0-255)
mask (number) – Mask bits (0-255)
Return value
none
This is used to filter out collisions with other shapes. Each shape can be given a layer
bitmask (8 bits, 0-255) along with a mask (also 8 bits). The layer of one object must be in
the mask of the other object and vice versa for the collision to be valid. The default layer
for all objects is 1 and the default mask is 255 (collide with all layers).
--This will put shapes a and b in layer 2 and disable collisions with
--object shapes in layers 2, preventing any collisions between the two.
SetShapeCollisionFilter(a, 2, 255-2)
SetShapeCollisionFilter(b, 2, 255-2)
--This will put shapes c and d in layer 4 and allow collisions with other
--shapes in layer 4, but ignore all other collisions with the rest of the world.
SetShapeCollisionFilter(c, 4, 4)
SetShapeCollisionFilter(d, 4, 4)
GetShapeClosestPoint
hit, point, normal = GetShapeClosestPoint(shape, origin)
Arguments
shape (number) – Shape handle
origin (table) – World space point
Return value
hit (boolean) – True if a point was found
point (table) – World space closest point
normal (table) – World space normal at closest point
This will return the closest point of a specific shape
local hit, p, n = GetShapeClosestPoint(s, Vec(0, 5, 0))
if hit then
--Point p of shape s is closest to (0,5,0)
end
IsShapeTouching
touching = IsShapeTouching(a, b)
Arguments
a (number) – Handle to first shape
b (number) – Handle to second shape
Return value
touching (boolean) – True is shapes a and b are touching each other
This will check if two shapes has physical overlap
local touch = IsShapeTouching(a, b)
if hit then
--Shapes are touching or overlapping
end
FindLocation
handle = FindLocation(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
handle (number) – Handle to first location with specified tag or zero if not found
local loc = FindLocation("start")
FindLocations
list = FindLocations(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
list (table) – Indexed table with handles to all locations with specified tag
--Search for locations tagged "waypoint" in script scope
local locations = FindLocations("waypoint")
for i=1, #locs do
local locs = locations[i]
...
end
GetLocationTransform
transform = GetLocationTransform(handle)
Arguments
handle (number) – Location handle
Return value
transform (table) – Transform of the location
local t = GetLocationTransform(loc)
FindJoint
handle = FindJoint(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
handle (number) – Handle to first joint with specified tag or zero if not found
local joint = FindJoint("doorhinge")
FindJoints
list = FindJoints(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
list (table) – Indexed table with handles to all joints with specified tag
--Search for locations tagged "doorhinge" in script scope
local hinges = FindJoints("doorhinge")
for i=1, #hinges do
local joint = hinges[i]
...
end
IsJointBroken
broken = IsJointBroken(joint)
Arguments
joint (number) – Joint handle
Return value
broken (boolean) – True if joint is broken
local broken = IsJointBroken(joint)
GetJointType
type = GetJointType(joint)
Arguments
joint (number) – Joint handle
Return value
type (string) – Joint type
Joint type is one of the following: "ball", "hinge", "prismatic" or "rope".
An empty string is returned if joint handle is invalid.
if GetJointType(joint) == "rope" then
--Joint is rope
end
GetJointOtherShape
other = GetJointOtherShape(joint, shape)
Arguments
joint (number) – Joint handle
shape (number) – Shape handle
Return value
other (number) – Other shape handle
A joint is always connected to two shapes. Use this function if you know
one shape and want to find the other one.
--joint is connected to a and b
otherShape = GetJointOtherShape(joint, a)
--otherShape is now b
otherShape = GetJointOtherShape(joint, b)
--otherShape is now a
SetJointMotor
SetJointMotor(joint, velocity, [strength])
Arguments
joint (number) – Joint handle
velocity (number) – Desired velocity
strength (number, optional) – Desired strength. Default is infinite. Zero to disable.
Return value
none
Set joint motor target velocity. If joint is of type hinge, velocity is
given in radians per second angular velocity. If joint type is prismatic joint
velocity is given in meters per second. Calling this function will override and
void any previous call to SetJointMotorTarget.
--Set motor speed to 0.5 radians per second
SetJointMotor(hinge, 0.5)
SetJointMotorTarget
SetJointMotorTarget(joint, target, [maxVel], [strength])
Arguments
joint (number) – Joint handle
target (number) – Desired movement target
maxVel (number, optional) – Maximum velocity to reach target. Default is infinite.
strength (number, optional) – Desired strength. Default is infinite. Zero to disable.
Return value
none
If a joint has a motor target, it will try to maintain its relative movement. This
is very useful for elevators or other animated, jointed mechanisms.
If joint is of type hinge, target is an angle in degrees (-180 to 180) and velocity
is given in radians per second. If joint type is prismatic, target is given
in meters and velocity is given in meters per second. Setting a motor target will
override any previous call to SetJointMotor.
--Make joint reach a 45 degree angle, going at a maximum of 3 radians per second
SetJointMotorTarget(hinge, 45, 3)
GetJointLimits
min, max = GetJointLimits(joint)
Arguments
joint (number) – Joint handle
Return value
min (number) – Minimum joint limit (angle or distance)
max (number) – Maximum joint limit (angle or distance)
Return joint limits for hinge or prismatic joint. Returns angle or distance
depending on joint type.
local min, max = GetJointLimits(hinge)
GetJointMovement
movement = GetJointMovement(joint)
Arguments
joint (number) – Joint handle
Return value
movement (number) – Current joint position or angle
Return the current position or angle or the joint, measured in same way
as joint limits.
local current = GetJointMovement(hinge)
GetJointedBodies
bodies = GetJointedBodies(body)
Arguments
body (number) – Body handle (must be dynamic)
Return value
bodies (table) – Handles to all dynamic bodies in the jointed structure. The input handle will also be included.
--Draw outline for all bodies in jointed structure
local all = GetJointedBodies(body)
for i=1,#all do
DrawBodyOutline(all[i], 0.5)
end
DetachJointFromShape
DetachJointFromShape(joint, shape)
Arguments
joint (number) – Joint handle
shape (number) – Shape handle
Return value
none
Detach joint from shape. If joint is not connected to shape, nothing happens.
DetachJointFromShape(hinge, door)
FindLight
handle = FindLight(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
handle (number) – Handle to first light with specified tag or zero if not found
local light = FindLight("main")
FindLights
list = FindLights(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
list (table) – Indexed table with handles to all lights with specified tag
--Search for lights tagged "main" in script scope
local lights = FindLights("main")
for i=1, #lights do
local light = lights[i]
...
end
SetLightEnabled
SetLightEnabled(handle, enabled)
Arguments
handle (number) – Light handle
enabled (boolean) – Set to true if light should be enabled
Return value
none
If light is owned by a shape, the emissive scale of that shape will be set
to 0.0 when light is disabled and 1.0 when light is enabled.
SetLightEnabled(light, false)
SetLightColor
SetLightColor(handle, r, g, b)
Arguments
handle (number) – Light handle
r (number) – Red value
g (number) – Green value
b (number) – Blue value
Return value
none
This will only set the color tint of the light. Use SetLightIntensity for brightness.
Setting the light color will not affect the emissive color of a parent shape.
--Set light color to yellow
SetLightColor(light, 1, 1, 0)
SetLightIntensity
SetLightIntensity(handle, intensity)
Arguments
handle (number) – Light handle
intensity (number) – Desired intensity of the light
Return value
none
If the shape is owned by a shape you most likely want to use
SetShapeEmissiveScale instead, which will affect both the emissiveness
of the shape and the brightness of the light at the same time.
--Pulsate light
SetLightIntensity(light, math.sin(GetTime())*0.5 + 1.0)
GetLightTransform
transform = GetLightTransform(handle)
Arguments
handle (number) – Light handle
Return value
transform (table) – World space light transform
Lights that are owned by a dynamic shape are automatcially moved with that shape
local pos = GetLightTransform(light).pos
GetLightShape
handle = GetLightShape(handle)
Arguments
handle (number) – Light handle
Return value
handle (number) – Shape handle or zero if not attached to shape
local shape = GetLightShape(light)
IsLightActive
active = IsLightActive(handle)
Arguments
handle (number) – Light handle
Return value
active (boolean) – True if light is currently emitting light
if IsLightActive(light) then
--Do something
end
IsPointAffectedByLight
affected = IsPointAffectedByLight(handle, point)
Arguments
handle (number) – Light handle
point (table) – World space point as vector
Return value
affected (boolean) – Return true if point is in light cone and range
local point = Vec(0, 10, 0)
local affected = IsPointAffectedByLight(light, point)
FindTrigger
handle = FindTrigger(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
handle (number) – Handle to first trigger with specified tag or zero if not found
local goal = FindTrigger("goal")
FindTriggers
list = FindTriggers(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
list (table) – Indexed table with handles to all triggers with specified tag
--Find triggers tagged "toxic" in script scope
local triggers = FindTriggers("toxic")
for i=1, #triggers do
local trigger = triggers[i]
...
end
GetTriggerTransform
transform = GetTriggerTransform(handle)
Arguments
handle (number) – Trigger handle
Return value
transform (table) – Current trigger transform in world space
local t = GetTriggerTransform(trigger)
SetTriggerTransform
SetTriggerTransform(handle, transform)
Arguments
handle (number) – Trigger handle
transform (table) – Desired trigger transform in world space
Return value
none
local t = Transform(Vec(0, 1, 0), QuatEuler(0, 90, 0))
SetTriggerTransform(trigger, t)
GetTriggerBounds
min, max = GetTriggerBounds(handle)
Arguments
handle (number) – Trigger handle
Return value
min (table) – Lower point of trigger bounds in world space
max (table) – Upper point of trigger bounds in world space
Return the lower and upper points in world space of the trigger axis aligned bounding box
local mi, ma = GetTriggerBounds(trigger)
local list = QueryAabbShapes(mi, ma)
IsBodyInTrigger
inside = IsBodyInTrigger(trigger, body)
Arguments
trigger (number) – Trigger handle
body (number) – Body handle
Return value
inside (boolean) – True if body is in trigger volume
This function will only check the center point of the body
if IsBodyInTrigger(trigger, body) then
...
end
IsVehicleInTrigger
inside = IsVehicleInTrigger(trigger, vehicle)
Arguments
trigger (number) – Trigger handle
vehicle (number) – Vehicle handle
Return value
inside (boolean) – True if vehicle is in trigger volume
This function will only check origo of vehicle
if IsVehicleInTrigger(trigger, vehicle) then
...
end
IsShapeInTrigger
inside = IsShapeInTrigger(trigger, shape)
Arguments
trigger (number) – Trigger handle
shape (number) – Shape handle
Return value
inside (boolean) – True if shape is in trigger volume
This function will only check the center point of the shape
if IsShapeInTrigger(trigger, shape) then
...
end
IsPointInTrigger
inside = IsPointInTrigger(trigger, point)
Arguments
trigger (number) – Trigger handle
point (table) – Word space point as vector
Return value
inside (boolean) – True if point is in trigger volume
local p = Vec(0, 10, 0)
if IsPointInTrigger(trigger, p) then
...
end
IsTriggerEmpty
empty, maxpoint = IsTriggerEmpty(handle, [demolision])
Arguments
handle (number) – Trigger handle
demolision (boolean, optional) – If true, small debris and vehicles are ignored
Return value
empty (boolean) – True if trigger is empty
maxpoint (table) – World space point of highest point (largest Y coordinate) if not empty
This function will check if trigger is empty. If trigger contains any part of a body
it will return false and the highest point as second return value.
local empty, highPoint = IsTriggerEmpty(trigger)
if not empty then
--highPoint[2] is the tallest point in trigger
end
GetTriggerDistance
distance = GetTriggerDistance(trigger, point)
Arguments
trigger (number) – Trigger handle
point (table) – Word space point as vector
Return value
distance (number) – Positive if point is outside, negative if inside
Get distance to the surface of trigger volume. Will return negative distance if inside.
local p = Vec(0, 10, 0)
local dist = GetTriggerDistance(trigger, p)
GetTriggerClosestPoint
closest = GetTriggerClosestPoint(trigger, point)
Arguments
trigger (number) – Trigger handle
point (table) – Word space point as vector
Return value
closest (table) – Closest point in trigger as vector
Return closest point in trigger volume. Will return the input point itself if inside trigger
or closest point on surface of trigger if outside.
local p = Vec(0, 10, 0)
local closest = GetTriggerClosestPoint(trigger, p)
FindScreen
handle = FindScreen(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
handle (number) – Handle to first screen with specified tag or zero if not found
local screen = FindTrigger("tv")
FindScreens
list = FindScreens(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
list (table) – Indexed table with handles to all screens with specified tag
--Find screens tagged "tv" in script scope
local screens = FindScreens("tv")
for i=1, #screens do
local screen = screens[i]
...
end
SetScreenEnabled
SetScreenEnabled(screen, enabled)
Arguments
screen (number) – Screen handle
enabled (boolean) – True if screen should be enabled
Return value
none
Enable or disable screen
SetScreenEnabled(screen, true)
IsScreenEnabled
enabled = IsScreenEnabled(screen)
Arguments
screen (number) – Screen handle
Return value
enabled (boolean) – True if screen is enabled
local b = IsScreenEnabled(screen)
GetScreenShape
shape = GetScreenShape(screen)
Arguments
screen (number) – Screen handle
Return value
shape (number) – Shape handle or zero if none
Return handle to the parent shape of a screen
local shape = GetScreenShape(screen)
FindVehicle
handle = FindVehicle(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
handle (number) – Handle to first vehicle with specified tag or zero if not found
local vehicle = FindVehicle("mycar")
FindVehicles
list = FindVehicles(tag, [global])
Arguments
tag (string) – Tag name
global (boolean, optional) – Search in entire scene
Return value
list (table) – Indexed table with handles to all vehicles with specified tag
--Find all vehicles in level tagged "boat"
local boats = FindVehicles("boat")
for i=1, #boats do
local boat = boats[i]
...
end
GetVehicleTransform
transform = GetVehicleTransform(vehicle)
Arguments
vehicle (number) – Vehicle handle
Return value
transform (table) – Transform of vehicle
local t = GetVehicleTransform(vehicle)
GetVehicleBody
body = GetVehicleBody(vehicle)
Arguments
vehicle (number) – Vehicle handle
Return value
body (number) – Main body of vehicle
local body = GetVehicleBody(vehicle)
if IsBodyBroken(body) then
--Vehicle body is broken
end
GetVehicleHealth
health = GetVehicleHealth(vehicle)
Arguments
vehicle (number) – Vehicle handle
Return value
health (number) – Vehicle health (zero to one)
local health = GetVehicleHealth(vehicle)
GetVehicleDriverPos
pos = GetVehicleDriverPos(vehicle)
Arguments
vehicle (number) – Vehicle handle
Return value
pos (table) – Driver position as vector in vehicle space
local driverPos = GetVehicleDriverPos(vehicle)
local t = GetVehicleTransform(vehicle)
local worldPos = TransformToParentPoint(t, driverPos)
DriveVehicle
DriveVehicle(vehicle, drive, steering, handbrake)
Arguments
vehicle (number) – Vehicle handle
drive (number) – Reverse/forward control -1 to 1
steering (number) – Left/right control -1 to 1
handbrake (boolean) – Handbrake control
Return value
none
This function applies input to vehicles, allowing for autonomous driving. The vehicle
will be turned on automatically and turned off when no longer called. Call this from
the tick function, not update.
function tick()
--Drive mycar forwards
local v = FindVehicle("mycar")
DriveVehicle(v, 1, 0, false)
end
GetPlayerPos
position = GetPlayerPos()
Arguments
none
Return value
position (table) – Player center position
Return center point of player. This function is deprecated.
Use GetPlayerTransform instead.
local p = GetPlayerPos()
--This is equivalent to
p = VecAdd(GetPlayerTransform().pos, Vec(0,1,0))
GetPlayerTransform
transform = GetPlayerTransform(includePitch)
Arguments
includePitch (boolean) – Include the player pitch (look up/down) in transform
Return value
transform (table) – Current player transform
The player transform is located at the bottom of the player. The player transform
considers heading (looking left and right). Forward is along negative Z axis.
Player pitch (looking up and down) does not affect player transform unless includePitch
is set to true. If you want the transform of the eye, use GetPlayerCameraTransform() instead.
local t = GetPlayerTransform()
SetPlayerTransform
SetPlayerTransform(transform, includePitch)
Arguments
transform (table) – Desired player transform
includePitch (boolean) – Set player pitch (look up/down) as well
Return value
none
Instantly teleport the player to desired transform. Unless includePitch is
set to true, up/down look angle will be set to zero during this process.
Player velocity will be reset to zero.
local t = Transform(Vec(10, 0, 0), QuatEuler(0, 90, 0))
SetPlayerTransform(t)
SetPlayerGroundVelocity
SetPlayerGroundVelocity(vel)
Arguments
vel (table) – Desired ground velocity
Return value
none
Make the ground act as a conveyor belt, pushing the player even if ground shape is static.
SetPlayerGroundVelocity(Vec(2,0,0))
GetPlayerCameraTransform
transform = GetPlayerCameraTransform()
Arguments
none
Return value
transform (table) – Current player camera transform
The player camera transform is usually the same as what you get from GetCameraTransform,
but if you have set a camera transform manually with SetCameraTransform, you can retrieve
the standard player camera transform with this function.
local t = GetPlayerCameraTransform()
SetPlayerSpawnTransform
SetPlayerSpawnTransform(transform)
Arguments
transform (table) – Desired player spawn transform
Return value
none
Call this function during init to alter the player spawn transform.
local t = Transform(Vec(10, 0, 0), QuatEuler(0, 90, 0))
SetPlayerSpawnTransform(t)
GetPlayerVelocity
velocity = GetPlayerVelocity()
Arguments
none
Return value
velocity (table) – Player velocity in world space as vector
local vel = GetPlayerVelocity()
SetPlayerVehicle
SetPlayerVehicle(vehicle)
Arguments
vehicle (value) – Handle to vehicle or zero to not drive.
Return value
none
Drive specified vehicle.
local car = FindVehicle("mycar")
SetPlayerVehicle(car)
SetPlayerVelocity
SetPlayerVelocity(velocity)
Arguments
velocity (table) – Player velocity in world space as vector
Return value
none
SetPlayerVelocity(Vec(0, 5, 0))
GetPlayerVehicle
handle = GetPlayerVehicle()
Arguments
none
Return value
handle (number) – Current vehicle handle, or zero if not in vehicle
local vehicle = GetPlayerVehicle()
if vehicle ~= 0 then
...
end
GetPlayerGrabShape
handle = GetPlayerGrabShape()
Arguments
none
Return value
handle (number) – Handle to grabbed shape or zero if not grabbing.
local shape = GetPlayerGrabShape()
if shape ~= 0 then
...
end
GetPlayerGrabBody
handle = GetPlayerGrabBody()
Arguments
none
Return value
handle (number) – Handle to grabbed body or zero if not grabbing.
local body = GetPlayerGrabBody()
if body ~= 0 then
...
end
ReleasePlayerGrab
ReleasePlayerGrab()
Arguments
none
Return value
none
Release what the player is currently holding
ReleasePlayerGrab()
GetPlayerPickShape
handle = GetPlayerPickShape()
Arguments
none
Return value
handle (number) – Handle to picked shape or zero if nothing is picked
local shape = GetPlayerPickShape()
if shape ~= 0 then
...
end
GetPlayerPickBody
handle = GetPlayerPickBody()
Arguments
none
Return value
handle (number) – Handle to picked body or zero if nothing is picked
local body = GetPlayerPickBody()
if body ~= 0 then
...
end
GetPlayerInteractShape
handle = GetPlayerInteractShape()
Arguments
none
Return value
handle (number) – Handle to interactable shape or zero
Interactable shapes has to be tagged with "interact". The engine
determines which interactable shape is currently interactable.
local shape = GetPlayerInteractShape()
if shape ~= 0 then
...
end
GetPlayerInteractBody
handle = GetPlayerInteractBody()
Arguments
none
Return value
handle (number) – Handle to interactable body or zero
Interactable shapes has to be tagged with "interact". The engine
determines which interactable body is currently interactable.
local body = GetPlayerInteractBody()
if body ~= 0 then
...
end
SetPlayerScreen
SetPlayerScreen(handle)
Arguments
handle (number) – Handle to screen or zero for no screen
Return value
none
Set the screen the player should interact with. For the screen
to feature a mouse pointer and receieve input, the screen also
needs to have interactive property.
--Interact with screen
SetPlayerScreen(screen)
--Do not interact with screen
SetPlayerScreen(0)
GetPlayerScreen
handle = GetPlayerScreen()
Arguments
none
Return value
handle (number) – Handle to interacted screen or zero if none
--Interact with screen
local screen = GetPlayerScreen()
SetPlayerHealth
SetPlayerHealth(health)
Arguments
health (number) – Set player health (between zero and one)
Return value
none
SetPlayerHealth(0.5)
GetPlayerHealth
health = GetPlayerHealth()
Arguments
none
Return value
health (number) – Current player health
local health = GetPlayerHealth()
RespawnPlayer
RespawnPlayer()
Arguments
none
Return value
none
Respawn player at spawn position without modifying the scene
RespawnPlayer()
RegisterTool
RegisterTool(id, name, file, [group])
Arguments
id (string) – Tool unique identifier
name (string) – Tool name to show in hud
file (string) – Path to vox file
group (number, optional) – Tool group for this tool (1-6) Default is 6.
Return value
none
Register a custom tool that will show up in the player inventory and
can be selected with scroll wheel. Do this only once per tool.
You also need to enable the tool in the registry before it can be used.
function init()
RegisterTool("lasergun", "Laser Gun", "MOD/vox/lasergun.vox")
SetBool("game.tool.lasergun.enabled", true)
end
function tick()
if GetString("game.player.tool") == "lasergun" then
--Tool is selected. Tool logic goes here.
end
end
GetToolBody
handle = GetToolBody()
Arguments
none
Return value
handle (number) – Handle to currently visible tool body or zero if none
Return body handle of the visible tool. You can use this to retrieve tool shapes
and animate them, change emissiveness, etc. Do not attempt to set the tool body
transform, since it is controlled by the engine. Use SetToolTranform for that.
local toolBody = GetToolBody()
if toolBody~=0 then
...
end
SetToolTransform
SetToolTransform(transform, sway)
Arguments
transform (table) – Tool body transform
sway (number) – Tool sway amount. Default is 1.0.
Return value
none
Apply an additional transform on the visible tool body. This can be used to
create tool animations. You need to set this every frame from the tick function.
The optional sway parameter control the amount of tool swaying when walking.
Set to zero to disable completely.
--Offset the tool half a meter to the right
local offset = Transform(Vec(0.5, 0, 0))
SetToolTransform(offset)
LoadSound
handle = LoadSound(path, [nominalDistance])
Arguments
path (string) – Path to ogg sound file
nominalDistance (number, optional) – The distance in meters this sound is recorded at. Affects attenuation, default is 10.0
Return value
handle (number) – Sound handle
local snd = LoadSound("beep.ogg")
LoadLoop
handle = LoadLoop(path, [nominalDistance])
Arguments
path (string) – Path to ogg sound file
nominalDistance (number, optional) – The distance in meters this sound is recorded at. Affects attenuation, default is 10.0
Return value
handle (number) – Loop handle
local loop = LoadLoop("siren.ogg")
PlaySound
PlaySound(handle, [pos], [volume])
Arguments
handle (number) – Sound handle
pos (table, optional) – World position as vector. Default is player position.
volume (number, optional) – Playback volume. Default is 1.0
Return value
none
function init()
snd = LoadSound("beep.ogg")
end
function tick()
if trigSound then
local pos = Vec(100, 0, 0)
PlaySound(snd, pos, 0.5)
end
end
PlayLoop
PlayLoop(handle, [pos], [volume])
Arguments
handle (number) – Loop handle
pos (table, optional) – World position as vector. Default is player position.
volume (number, optional) – Playback volume. Default is 1.0
Return value
none
Call this function continuously to play loop
function init()
loop = LoadLoop("siren.ogg")
end
function tick()
local pos = Vec(100, 0, 0)
PlayLoop(loop, pos, 0.5)
end
PlayMusic
PlayMusic(path)
Arguments
path (string) – Music path
Return value
none
PlayMusic("MOD/music/background.ogg")
StopMusic
StopMusic()
Arguments
none
Return value
none
StopMusic()
LoadSprite
handle = LoadSprite(path)
Arguments
path (string) – Path to sprite. Must be PNG or JPG format.
Return value
handle (number) – Sprite handle
function init()
arrow = LoadSprite("arrow.png")
end
DrawSprite
DrawSprite(handle, transform, width, height, [r], [g], [b], [a], [depthTest], [additive])
Arguments
handle (number) – Sprite handle
transform (table) – Transform
width (number) – Width in meters
height (number) – Height in meters
r (number, optional) – Red color. Default 1.0.
g (number, optional) – Green color. Default 1.0.
b (number, optional) – Blue color. Default 1.0.
a (number, optional) – Alpha. Default 1.0.
depthTest (boolean, optional) – Depth test enabled. Default false.
additive (boolean, optional) – Additive blending enabled. Default false.
Return value
none
Draw sprite in world at next frame. Call this function from the tick callback.
function init()
arrow = LoadSprite("arrow.png")
end
function tick()
--Draw sprite using transform
--Size is two meters in width and height
--Color is white, fully opaue
local t = Transform(Vec(0, 10, 0), QuatEuler(0, GetTime(), 0))
DrawSprite(arrow, t, 2, 2, 1, 1, 1, 1)
end
QueryRequire
QueryRequire(layers)
Arguments
layers (string) – Space separate list of layers
Return value
none
Set required layers for next query. Available layers are:
|
| physical | have a physical representation |
| dynamic | part of a dynamic body |
| static | part of a static body |
| large | above debris threshold |
| small | below debris threshold |
--Raycast dynamic, physical objects above debris threshold, but not specific vehicle
QueryRequire("physical dynamic large")
QueryRejectVehicle(vehicle)
QueryRaycast(...)
QueryRejectVehicle
QueryRejectVehicle(vehicle)
Arguments
vehicle (number) – Vehicle handle
Return value
none
Exclude vehicle from the next query
--Do not include vehicle in next raycast
QueryRejectVehicle(vehicle)
QueryRaycast(...)
QueryRejectBody
QueryRejectBody(body)
Arguments
body (number) – Body handle
Return value
none
Exclude body from the next query
--Do not include body in next raycast
QueryRejectBody(body)
QueryRaycast(...)
QueryRejectShape
QueryRejectShape(shape)
Arguments
shape (number) – Shape handle
Return value
none
Exclude shape from the next query
--Do not include shape in next raycast
QueryRejectShape(shape)
QueryRaycast(...)
QueryRaycast
hit, dist, normal, shape = QueryRaycast(origin, direction, maxDist, [radius], [rejectTransparent])
Arguments
origin (table) – Raycast origin as world space vector
direction (table) – Unit length raycast direction as world space vector
maxDist (number) – Raycast maximum distance. Keep this as low as possible for good performance.
radius (number, optional) – Raycast thickness. Default zero.
rejectTransparent (boolean, optional) – Raycast through transparent materials. Default false.
Return value
hit (boolean) – True if raycast hit something
dist (number) – Hit distance from origin
normal (table) – World space normal at hit point
shape (number) – Handle to hit shape
This will perform a raycast or spherecast (if radius is more than zero) query.
If you want to set up a filter for the query you need to do so before every call
to this function.
--Raycast from a high point straight downwards, excluding a specific vehicle
QueryRejectVehicle(vehicle)
local hit, d = QueryRaycast(Vec(0, 100, 0), Vec(0, -1, 0), 100)
if hit then
...hit something at distance d
end
QueryClosestPoint
hit, point, normal, shape = QueryClosestPoint(origin, maxDist)
Arguments
origin (table) – World space point
maxDist (number) – Maximum distance. Keep this as low as possible for good performance.
Return value
hit (boolean) – True if a point was found
point (table) – World space closest point
normal (table) – World space normal at closest point
shape (number) – Handle to closest shape
This will query the closest point to all shapes in the world. If you
want to set up a filter for the query you need to do so before every call
to this function.
--Find closest point within 10 meters of {0, 5, 0}, excluding any point on myVehicle
QueryRejectVehicle(myVehicle)
local hit, p, n, s = QueryClosestPoint(Vec(0, 5, 0), 10)
if hit then
--Point p of shape s is closest
end
QueryAabbShapes
list = QueryAabbShapes(min, max)
Arguments
min (table) – Aabb minimum point
max (table) – Aabb maximum point
Return value
list (table) – Indexed table with handles to all shapes in the aabb
Return all shapes within the provided world space, axis-aligned bounding box
local list = QueryAabbShapes(Vec(0, 0, 0), Vec(10, 10, 10))
for i=1, #list do
local shape = list[i]
..
end
QueryAabbBodies
list = QueryAabbBodies(min, max)
Arguments
min (table) – Aabb minimum point
max (table) – Aabb maximum point
Return value
list (table) – Indexed table with handles to all bodies in the aabb
Return all bodies within the provided world space, axis-aligned bounding box
local list = QueryAabbBodies(Vec(0, 0, 0), Vec(10, 10, 10))
for i=1, #list do
local body = list[i]
..
end
QueryPath
QueryPath(start, end, [maxDist], [targetRadius])
Arguments
start (table) – World space start point
end (table) – World space target point
maxDist (number, optional) – Maximum path length before giving up. Default is infinite.
targetRadius (number, optional) – Maximum allowed distance to target in meters. Default is 2.0
Return value
none
Initiate path planning query. The result will run asynchronously as long as GetPathState
retuns "busy". An ongoing path query can be aborted with AbortPath. The path planning query
will use the currently set up query filter, just like the other query functions.
QueryPath(Vec(-10, 0, 0), Vec(10, 0, 0))
AbortPath
AbortPath()
Arguments
none
Return value
none
Abort current path query, regardless of what state it is currently in. This is a way to
save computing resources if the result of the current query is no longer of interest.
AbortPath()
GetPathState
state = GetPathState()
Arguments
none
Return value
state (string) – Current path planning state
Return the current state of the last path planning query.
|
| idle | No recent query |
| busy | Busy computing. No path found yet. |
| fail | Failed to find path. You can still get the resulting path (even though it won't reach the target). |
| done | Path planning completed and a path was found. Get it with GetPathLength and GetPathPoint) |
local s = GetPathState()
if s == "done" then
DoSomething()
end
GetPathLength
length = GetPathLength()
Arguments
none
Return value
length (number) – Length of last path planning result (in meters)
Return the path length of the most recently computed path query. Note that the result can often be retrieved even
if the path query failed. If the target point couldn't be reached, the path endpoint will be the point closest
to the target.
local l = GetPathLength()
GetPathPoint
point = GetPathPoint(dist)
Arguments
dist (number) – The distance along path. Should be between zero and result from GetPathLength()
Return value
point (table) – The path point dist meters along the path
Return a point along the path for the most recently computed path query. Note that the result can often be retrieved even
if the path query failed. If the target point couldn't be reached, the path endpoint will be the point closest
to the target.
local d = 0
local l = GetPathLength()
while d < l do
DebugCross(GetPathPoint(d))
d = d + 0.5
end
GetLastSound
volume, position = GetLastSound()
Arguments
none
Return value
volume (number) – Volume of loudest sound played last frame
position (table) – World position of loudest sound played last frame
local vol, pos = GetLastSound()
IsPointInWater
inWater, depth = IsPointInWater(point)
Arguments
point (table) – World point as vector
Return value
inWater (boolean) – True if point is in water
depth (number) – Depth of point into water, or zero if not in water
local wet, d = IsPointInWater(Vec(10, 0, 0))
if wet then
...point d meters into water
end
GetWindVelocity
vel = GetWindVelocity(point)
Arguments
point (table) – World point as vector
Return value
vel (table) – Wind at provided position
Get the wind velocity at provided point. The wind will be determined by wind property of
the environment, but it varies with position procedurally.
local v = GetWindVelocity(Vec(0, 10, 0))
ParticleReset
ParticleReset()
Arguments
none
Return value
none
Reset to default particle state, which is a plain, white particle of radius 0.5.
Collision is enabled and it alpha animates from 1 to 0.
ParticleReset()
ParticleType
ParticleType(type)
Arguments
type (string) – Type of particle. Can be "smoke" or "plain".
Return value
none
Set type of particle
ParticleType("smoke")
ParticleTile
ParticleTile(type)
Arguments
type (int) – Tile in the particle texture atlas (0-15)
Return value
none
--Smoke particle
ParticleTile(0)
--Fire particle
ParticleTile(5)
ParticleColor
ParticleColor(r0, g0, b0, [r1], [g1], [b1])
Arguments
r0 (float) – Red value
g0 (float) – Green value
b0 (float) – Blue value
r1 (float, optional) – Red value at end
g1 (float, optional) – Green value at end
b1 (float, optional) – Blue value at end
Return value
none
Set particle color to either constant (three arguments) or linear interpolation (six arguments)
--Constant red
ParticleColor(1,0,0)
--Animating from yellow to red
ParticleColor(1,1,0, 1,0,0)
ParticleRadius
ParticleRadius(r0, [r1], [interpolation], [fadein], [fadeout])
Arguments
r0 (float) – Radius
r1 (float, optional) – End radius
interpolation (string, optional) – Interpolation method: linear, smooth, easein, easeout or constant. Default is linear.
fadein (float, optional) – Fade in between t=0 and t=fadein. Default is zero.
fadeout (float, optional) – Fade out between t=fadeout and t=1. Default is one.
Return value
none
Set the particle radius. Max radius for smoke particles is 1.0.
--Constant radius 0.4 meters
ParticleRadius(0.4)
--Interpolate from small to large
ParticleRadius(0.1, 0.7)
ParticleAlpha
ParticleAlpha(a0, [a1], [interpolation], [fadein], [fadeout])
Arguments
a0 (float) – Alpha (0.0 - 1.0)
a1 (float, optional) – End alpha (0.0 - 1.0)
interpolation (string, optional) – Interpolation method: linear, smooth, easein, easeout or constant. Default is linear.
fadein (float, optional) – Fade in between t=0 and t=fadein. Default is zero.
fadeout (float, optional) – Fade out between t=fadeout and t=1. Default is one.
Return value
none
Set the particle alpha (opacity).
--Interpolate from opaque to transparent
ParticleAlpha(1.0, 0.0)
ParticleGravity
ParticleGravity(g0, [g1], [interpolation], [fadein], [fadeout])
Arguments
g0 (float) – Gravity
g1 (float, optional) – End gravity
interpolation (string, optional) – Interpolation method: linear, smooth, easein, easeout or constant. Default is linear.
fadein (float, optional) – Fade in between t=0 and t=fadein. Default is zero.
fadeout (float, optional) – Fade out between t=fadeout and t=1. Default is one.
Return value
none
Set particle gravity. It will be applied along the world Y axis. A negative value will move the particle downwards.
--Move particles slowly upwards
ParticleGravity(2)
ParticleDrag
ParticleDrag(d0, [d1], [interpolation], [fadein], [fadeout])
Arguments
d0 (float) – Drag
d1 (float, optional) – End drag
interpolation (string, optional) – Interpolation method: linear, smooth, easein, easeout or constant. Default is linear.
fadein (float, optional) – Fade in between t=0 and t=fadein. Default is zero.
fadeout (float, optional) – Fade out between t=fadeout and t=1. Default is one.
Return value
none
Particle drag will slow down fast moving particles. It's implemented slightly different for
smoke and plain particles. Drag must be positive, and usually look good between zero and one.
--Slow down fast moving particles
ParticleDrag(0.5)
ParticleEmissive
ParticleEmissive(d0, [d1], [interpolation], [fadein], [fadeout])
Arguments
d0 (float) – Emissive
d1 (float, optional) – End emissive
interpolation (string, optional) – Interpolation method: linear, smooth, easein, easeout or constant. Default is linear.
fadein (float, optional) – Fade in between t=0 and t=fadein. Default is zero.
fadeout (float, optional) – Fade out between t=fadeout and t=1. Default is one.
Return value
none
Draw particle as emissive (glow in the dark). This is useful for fire and embers.
--Highly emissive at start, not emissive at end
ParticleEmissive(5, 0)
ParticleRotation
ParticleRotation(r0, [r1], [interpolation], [fadein], [fadeout])
Arguments
r0 (float) – Rotation speed in radians per second.
r1 (float, optional) – End rotation speed in radians per second.
interpolation (string, optional) – Interpolation method: linear, smooth, easein, easeout or constant. Default is linear.
fadein (float, optional) – Fade in between t=0 and t=fadein. Default is zero.
fadeout (float, optional) – Fade out between t=fadeout and t=1. Default is one.
Return value
none
Makes the particle rotate. Positive values is counter-clockwise rotation.
--Rotate fast at start and slow at end
ParticleEmissive(10, 1)
ParticleStretch
ParticleStretch(s0, [s1], [interpolation], [fadein], [fadeout])
Arguments
s0 (float) – Stretch
s1 (float, optional) – End stretch
interpolation (string, optional) – Interpolation method: linear, smooth, easein, easeout or constant. Default is linear.
fadein (float, optional) – Fade in between t=0 and t=fadein. Default is zero.
fadeout (float, optional) – Fade out between t=fadeout and t=1. Default is one.
Return value
none
Stretch particle along with velocity. 0.0 means no stretching. 1.0 stretches with the particle motion over
one frame. Larger values stretches the particle even more.
--Stretch particle along direction of motion
ParticleStretch(1.0)
ParticleSticky
ParticleSticky(s0, [s1], [interpolation], [fadein], [fadeout])
Arguments
s0 (float) – Sticky (0.0 - 1.0)
s1 (float, optional) – End sticky (0.0 - 1.0)
interpolation (string, optional) – Interpolation method: linear, smooth, easein, easeout or constant. Default is linear.
fadein (float, optional) – Fade in between t=0 and t=fadein. Default is zero.
fadeout (float, optional) – Fade out between t=fadeout and t=1. Default is one.
Return value
none
Make particle stick when in contact with objects. This can be used for friction.
--Make particles stick to objects
ParticleSticky(0.5)
ParticleCollide
ParticleCollide(c0, [c1], [interpolation], [fadein], [fadeout])
Arguments
c0 (float) – Collide (0.0 - 1.0)
c1 (float, optional) – End collide (0.0 - 1.0)
interpolation (string, optional) – Interpolation method: linear, smooth, easein, easeout or constant. Default is linear.
fadein (float, optional) – Fade in between t=0 and t=fadein. Default is zero.
fadeout (float, optional) – Fade out between t=fadeout and t=1. Default is one.
Return value
none
Control particle collisions. A value of zero means that collisions are ignored. One means full collision.
It is sometimes useful to animate this value from zero to one in order to not collide with objects around
the emitter.
--Disable collisions
ParticleCollide(0)
--Enable collisions over time
ParticleCollide(0, 1)
--Ramp up collisions very quickly, only skipping the first 5% of lifetime
ParticleCollide(1, 1, "constant", 0.05)
ParticleFlags
ParticleFlags(bitmask)
Arguments
bitmask (number) – Particle flags (bitmask 0-65535)
Return value
none
Set particle bitmask. The value 256 means fire extinguishing particles and is currently the only
flag in use. There might be support for custom flags and queries in the future.
--Fire extinguishing particle
ParticleFlags(256)
SpawnParticle(...)
SpawnParticle
SpawnParticle(pos, velocity, lifetime)
Arguments
pos (table) – World space point as vector
velocity (table) – World space velocity as vector
lifetime (number) – Particle lifetime in seconds
Return value
none
Spawn particle using the previously set up particle state. You can call this multiple times
using the same particle state, but with different position, velocity and lifetime. You can
also modify individual properties in the particle state in between calls to to this function.
ParticleReset()
ParticleType("smoke")
ParticleColor(0.7, 0.6, 0.5)
--Spawn particle at world origo with upwards velocity and a lifetime of ten seconds
SpawnParticle(Vec(0, 0, 0), Vec(0, 1, 0), 10.0)
Spawn
entities = Spawn(xml, transform, [allowStatic], [jointExisting])
Arguments
xml (string) – File name or xml string
transform (table) – Spawn transform
allowStatic (boolean, optional) – Allow spawning static shapes and bodies (default false)
jointExisting (boolean, optional) – Allow joints to connect to existing scene geometry (default false)
Return value
entities (table) – Indexed table with handles to all spawned entities
The first argument can be either a prefab XML file in your mod folder or a string with XML content. It is also
possible to spawn prefabs from other mods, by using the mod id followed by colon, followed by the prefab path.
Spawning prefabs from other mods should be used with causion since the referenced mod might not be installed.
Spawn("MOD/prefab/mycar.xml", Transform(Vec(0, 5, 0)))
Spawn("<voxbox size='10 10 10' prop='true' material='wood'/>", Transform(Vec(0, 10, 0)))
Shoot
Shoot(origin, direction, [type], [strength], [maxDist])
Arguments
origin (table) – Origin in world space as vector
direction (table) – Unit length direction as world space vector
type (string, optional) – Shot type, see description, default is "bullet"
strength (number, optional) – Strength scaling, default is 1.0
maxDist (number, optional) – Maximum distance, default is 100.0
Return value
none
Fire projectile. Type can be one of "bullet", "rocket", "gun" or "shotgun".
For backwards compatilbility, type also accept a number, where 1 is same as "rocket" and anything else "bullet"
Note that this function will only spawn the projectile, not make any sound
Also note that "bullet" and "rocket" are the only projectiles that can hurt the player.
Shoot(Vec(0, 10, 0), Vec(0, 0, 1), "shotgun")
Paint
Paint(origin, radius, [type], [probability])
Arguments
origin (table) – Origin in world space as vector
radius (number) – Affected radius, in range 0.0 to 5.0
type (string, optional) – Paint type. Can be "explosion" or "spraycan". Default is spraycan.
probability (number, optional) – Dithering probability between zero and one, default is 1.0
Return value
none
Tint the color of objects within radius to either black or yellow.
Paint(Vec(0, 10, 0), 0.5, "spraycan")
MakeHole
count = MakeHole(position, r0, [r1], [r2], [silent])
Arguments
position (table) – Hole center point
r0 (number) – Hole radius for soft materials
r1 (number, optional) – Hole radius for medium materials. May not be bigger than r0. Default zero.
r2 (number, optional) – Hole radius for hard materials. May not be bigger than r1. Default zero.
silent (boolean, optional) – Make hole without playing any break sounds.
Return value
count (number) – Number of voxels that was cut out. This will be zero if there were no changes to any shape.
Make a hole in the environment. Radius is given in meters.
Soft materials: glass, foliage, dirt, wood, plaster and plastic.
Medium materials: concrete, brick and weak metal.
Hard materials: hard metal and hard masonry.
MakeHole(pos, 1.2, 1.0)
Explosion
Explosion(pos, size)
Arguments
pos (table) – Position in world space as vector
size (number) – Explosion size from 0.5 to 4.0
Return value
none
Explosion(Vec(0, 10, 0), 1)
SpawnFire
SpawnFire(pos)
Arguments
pos (table) – Position in world space as vector
Return value
none
SpawnFire(Vec(0, 10, 0))
GetFireCount
count = GetFireCount()
Arguments
none
Return value
count (number) – Number of active fires in level
local c = GetFireCount()
QueryClosestFire
hit, pos = QueryClosestFire(origin, maxDist)
Arguments
origin (table) – World space position as vector
maxDist (number) – Maximum search distance
Return value
hit (boolean) – A fire was found within search distance
pos (table) – Position of closest fire
local hit, pos = QueryClosestFire(GetPlayerTransform().pos, 5.0)
if hit then
--There is a fire within 5 meters to the player. Mark it with a debug cross.
DebugCross(pos)
end
QueryAabbFireCount
count = QueryAabbFireCount(min, max)
Arguments
min (table) – Aabb minimum point
max (table) – Aabb maximum point
Return value
count (number) – Number of active fires in bounding box
local count = QueryAabbFireCount(Vec(0,0,0), Vec(10,10,10))
RemoveAabbFires
count = RemoveAabbFires(min, max)
Arguments
min (table) – Aabb minimum point
max (table) – Aabb maximum point
Return value
count (number) – Number of fires removed
local removedCount= RemoveAabbFires(Vec(0,0,0), Vec(10,10,10))
GetCameraTransform
transform = GetCameraTransform()
Arguments
none
Return value
transform (table) – Current camera transform
local t = GetCameraTransform()
SetCameraTransform
SetCameraTransform(transform, [fov])
Arguments
transform (table) – Desired camera transform
fov (number, optional) – Optional horizontal field of view in degrees (default: 90)
Return value
none
Override current camera transform for this frame. Call continuously to keep overriding.
SetCameraTransform(Transform(Vec(0, 10, 0), QuatEuler(0, 90, 0)))
SetCameraFov
SetCameraFov(degrees)
Arguments
degrees (number) – Horizontal field of view in degrees (10-170)
Return value
none
Override field of view for the next frame for all camera modes, except when explicitly set in SetCameraTransform
function tick()
SetCameraFov(60)
end
SetCameraDof
SetCameraDof(distance, [amount])
Arguments
distance (number) – Depth of field distance
amount (number, optional) – Optional amount of blur (default 1.0)
Return value
none
Override depth of field for the next frame for all camera modes. Depth of field will be used even if turned off in options.
--Set depth of field to 10 meters
SetCameraDof(10)
PointLight
PointLight(pos, r, g, b, [intensity])
Arguments
pos (table) – World space light position
r (number) – Red
g (number) – Green
b (number) – Blue
intensity (number, optional) – Intensity. Default is 1.0.
Return value
none
Add a temporary point light to the world for this frame. Call continuously
for a steady light.
--Pulsating, yellow light above world origo
local intensity = 3 + math.sin(GetTime())
PointLight(Vec(0, 5, 0), 1, 1, 0, intensity)
SetTimeScale
SetTimeScale(scale)
Arguments
scale (number) – Time scale 0.1 to 1.0
Return value
none
Experimental. Scale time in order to make a slow-motion effect. Audio will
also be affected. Note that this will affect physics behavior and is not
intended for gameplay purposes. Calling this function will slow down time
for the next frame only. Call every frame from tick function to get steady
slow-motion.
--Slow down time when holding down a key
if InputDown('t') then
SetTimeScale(0.2)
end
SetEnvironmentDefault
SetEnvironmentDefault()
Arguments
none
Return value
none
Reset the environment properties to default. This is often useful before
setting up a custom environment.
SetEnvironmentDefault()
SetEnvironmentProperty
SetEnvironmentProperty(name, value0, [value1], [value2], [value3])
Arguments
name (string) – Property name
value0 (varying) – Property value (type depends on property)
value1 (varying, optional) – Extra property value (only some properties)
value2 (varying, optional) – Extra property value (only some properties)
value3 (varying, optional) – Extra property value (only some properties)
Return value
none
This function is used for manipulating the environment properties. The available properties are
exactly the same as in the editor, except for "snowonground" which is not currently supported.
SetEnvironmentProperty("skybox", "cloudy.dds")
SetEnvironmentProperty("rain", 0.7)
SetEnvironmentProperty("fogcolor", 0.5, 0.5, 0.8)
SetEnvironmentProperty("nightlight", false)
GetEnvironmentProperty
value0, value1, value2, value3, value4 = GetEnvironmentProperty(name)
Arguments
name (string) – Property name
Return value
value0 (varying) – Property value (type depends on property)
value1 (varying) – Property value (only some properties)
value2 (varying) – Property value (only some properties)
value3 (varying) – Property value (only some properties)
value4 (varying) – Property value (only some properties)
This function is used for querying the current environment properties. The available properties are
exactly the same as in the editor.
local skyboxPath = GetEnvironmentProperty("skybox")
local rainValue = GetEnvironmentProperty("rain")
local r,g,b = GetEnvironmentProperty("fogcolor")
local enabled = GetEnvironmentProperty("nightlight")
SetPostProcessingDefault
SetPostProcessingDefault()
Arguments
none
Return value
none
Reset the post processing properties to default.
SetPostProcessingDefault()
SetPostProcessingProperty
SetPostProcessingProperty(name, value0, [value1], [value2])
Arguments
name (string) – Property name
value0 (number) – Property value
value1 (number, optional) – Extra property value (only some properties)
value2 (number, optional) – Extra property value (only some properties)
Return value
none
This function is used for manipulating the post processing properties. The available properties are
exactly the same as in the editor.
--Sepia post processing
SetPostProcessingProperty("saturation", 0.4)
SetPostProcessingProperty("colorbalance", 1.3, 1.0, 0.7)
GetPostProcessingProperty
value0, value1, value2 = GetPostProcessingProperty(name)
Arguments
name (string) – Property name
Return value
value0 (number) – Property value
value1 (number) – Property value (only some properties)
value2 (number) – Property value (only some properties)
This function is used for querying the current post processing properties.
The available properties are exactly the same as in the editor.
local saturation = GetPostProcessingProperty("saturation")
local r,g,b = GetPostProcessingProperty("colorbalance")
DrawLine
DrawLine(p0, p1, [r], [g], [b], [a])
Arguments
p0 (table) – World space point as vector
p1 (table) – World space point as vector
r (number, optional) – Red
g (number, optional) – Green
b (number, optional) – Blue
a (number, optional) – Alpha
Return value
none
Draw a 3D line. In contrast to DebugLine, it will not show behind objects. Default color is white.
--Draw white debug line
DrawLine(Vec(0, 0, 0), Vec(-10, 5, -10))
--Draw red debug line
DrawLine(Vec(0, 0, 0), Vec(10, 5, 10), 1, 0, 0)
DebugLine
DebugLine(p0, p1, [r], [g], [b], [a])
Arguments
p0 (table) – World space point as vector
p1 (table) – World space point as vector
r (number, optional) – Red
g (number, optional) – Green
b (number, optional) – Blue
a (number, optional) – Alpha
Return value
none
Draw a 3D debug overlay line in the world. Default color is white.
--Draw white debug line
DebugLine(Vec(0, 0, 0), Vec(-10, 5, -10))
--Draw red debug line
DebugLine(Vec(0, 0, 0), Vec(10, 5, 10), 1, 0, 0)
DebugCross
DebugCross(p0, [r], [g], [b], [a])
Arguments
p0 (table) – World space point as vector
r (number, optional) – Red
g (number, optional) – Green
b (number, optional) – Blue
a (number, optional) – Alpha
Return value
none
Draw a debug cross in the world to highlight a location. Default color is white.
DebugCross(Vec(10, 5, 5))
DebugWatch
DebugWatch(name, value)
Arguments
name (string) – Name
value (string) – Value
Return value
none
Show a named valued on screen for debug purposes.
Up to 32 values can be shown simultaneously. Values updated the current
frame are drawn opaque. Old values are drawn transparent in white.
The function will also recognize vectors, quaternions and transforms as
second argument and convert them to strings automatically.
local t = 5
DebugWatch("time", t)
DebugPrint
DebugPrint(message)
Arguments
message (string) – Message to display
Return value
none
Display message on screen. The last 20 lines are displayed.
DebugPrint("time")
UiMakeInteractive
UiMakeInteractive()
Arguments
none
Return value
none
Calling this function will disable game input, bring up the mouse pointer
and allow Ui interaction with the calling script without pausing the game.
This can be useful to make interactive user interfaces from scripts while
the game is running. Call this continuously every frame as long as Ui
interaction is desired.
UiMakeInteractive()
UiPush
UiPush()
Arguments
none
Return value
none
Push state onto stack. This is used in combination with UiPop to
remember a state and restore to that state later.
UiColor(1,0,0)
UiText("Red")
UiPush()
UiColor(0,1,0)
UiText("Green")
UiPop()
UiText("Red")
UiPop
UiPop()
Arguments
none
Return value
none
Pop state from stack and make it the current one. This is used in
combination with UiPush to remember a previous state and go back to
it later.
UiColor(1,0,0)
UiText("Red")
UiPush()
UiColor(0,1,0)
UiText("Green")
UiPop()
UiText("Red")
UiWidth
width = UiWidth()
Arguments
none
Return value
width (number) – Width of draw context
local w = UiWidth()
UiHeight
height = UiHeight()
Arguments
none
Return value
height (number) – Height of draw context
local h = UiHeight()
UiCenter
center = UiCenter()
Arguments
none
Return value
center (number) – Half width of draw context
local c = UiCenter()
--Same as
local c = UiWidth()/2
UiMiddle
middle = UiMiddle()
Arguments
none
Return value
middle (number) – Half height of draw context
local m = UiMiddle()
--Same as
local m = UiHeight()/2
UiColor
UiColor(r, g, b, [a])
Arguments
r (number) – Red channel
g (number) – Green channel
b (number) – Blue channel
a (number, optional) – Alpha channel. Default 1.0
Return value
none
--Set color yellow
UiColor(1,1,0)
UiColorFilter
UiColorFilter(r, g, b, [a])
Arguments
r (number) – Red channel
g (number) – Green channel
b (number) – Blue channel
a (number, optional) – Alpha channel. Default 1.0
Return value
none
Color filter, multiplied to all future colors in this scope
UiPush()
--Draw menu in transparent, yellow color tint
UiColorFilter(1, 1, 0, 0.5)
drawMenu()
UiPop()
UiTranslate
UiTranslate(x, y)
Arguments
x (number) – X component
y (number) – Y component
Return value
none
Translate cursor
UiPush()
UiTranslate(100, 0)
UiText("Indented")
UiPop()
UiRotate
UiRotate(angle)
Arguments
angle (number) – Angle in degrees, counter clockwise
Return value
none
Rotate cursor
UiPush()
UiRotate(45)
UiText("Rotated")
UiPop()
UiScale
UiScale(x, [y])
Arguments
x (number) – X component
y (number, optional) – Y component. Default value is x.
Return value
none
Scale cursor either uniformly (one argument) or non-uniformly (two arguments)
UiPush()
UiScale(2)
UiText("Double size")
UiPop()
UiWindow
UiWindow(width, height, [clip], [inherit])
Arguments
width (number) – Window width
height (number) – Window height
clip (boolean, optional) – Clip content outside window. Default is false.
inherit (boolean, optional) – Inherit current clip region (for nested clip regions)
Return value
none
Set up new bounds. Calls to UiWidth, UiHeight, UiCenter and UiMiddle
will operate in the context of the window size.
If clip is set to true, contents of window will be clipped to
bounds (only works properly for non-rotated windows).
UiPush()
UiWindow(400, 200)
local w = UiWidth()
--w is now 400
UiPop()
UiSafeMargins
x0, y0, x1, y1 = UiSafeMargins()
Arguments
none
Return value
x0 (number) – Left
y0 (number) – Top
x1 (number) – Right
y1 (number) – Bottom
Return a safe drawing area that will always be visible regardless of
display aspect ratio. The safe drawing area will always be 1920 by 1080
in size. This is useful for setting up a fixed size UI.
function draw()
local x0, y0, x1, y1 = UiSafeMargins()
UiTranslate(x0, y0)
UiWindow(x1-x0, y1-y0, true)
--The drawing area is now 1920 by 1080 in the center of screen
drawMenu()
end
UiAlign
UiAlign(alignment)
Arguments
alignment (string) – Alignment keywords
Return value
none
The alignment determines how content is aligned with respect to the
cursor.
|
| left | Horizontally align to the left |
| right | Horizontally align to the right |
| center | Horizontally align to the center |
| top | Vertically align to the top |
| bottom | Veritcally align to the bottom |
| middle | Vertically align to the middle |
Alignment can contain combinations of these, for instance:
"center middle", "left top", "center top", etc. If horizontal
or vertical alginment is omitted it will depend on the element drawn.
Text, for instance has default vertical alignment at baseline.
UiAlign("left")
UiText("Aligned left at baseline")
UiAlign("center middle")
UiText("Fully centered")
UiModalBegin
UiModalBegin()
Arguments
none
Return value
none
Disable input for everything, except what's between UiModalBegin and UiModalEnd
(or if modal state is popped)
UiModalBegin()
if UiTextButton("Okay") then
--All other interactive ui elements except this one are disabled
end
UiModalEnd()
--This is also okay
UiPush()
UiModalBegin()
if UiTextButton("Okay") then
--All other interactive ui elements except this one are disabled
end
UiPop()
--No longer modal
UiModalEnd
UiModalEnd()
Arguments
none
Return value
none
Disable input for everything, except what's between UiModalBegin and UiModalEnd
Calling this function is optional. Modality is part of the current state and will
be lost if modal state is popped.
UiModalBegin()
if UiTextButton("Okay") then
--All other interactive ui elements except this one are disabled
end
UiModalEnd()
UiDisableInput
UiDisableInput()
Arguments
none
Return value
none
Disable input
UiPush()
UiDisableInput()
if UiTextButton("Okay") then
--Will never happen
end
UiPop()
UiEnableInput
UiEnableInput()
Arguments
none
Return value
none
Enable input that has been previously disabled
UiDisableInput()
if UiTextButton("Okay") then
--Will never happen
end
UiEnableInput()
if UiTextButton("Okay") then
--This can happen
end
UiReceivesInput
receives = UiReceivesInput()
Arguments
none
Return value
receives (boolean) – True if current context receives input
This function will check current state receives input. This is the case
if input is not explicitly disabled with (with UiDisableInput) and no other
state is currently modal (with UiModalBegin). Input functions and UI
elements already do this check internally, but it can sometimes be useful
to read the input state manually to trigger things in the UI.
if UiReceivesInput() then
highlightItemAtMousePointer()
end
UiGetMousePos
x, y = UiGetMousePos()
Arguments
none
Return value
x (number) – X coordinate
y (number) – Y coordinate
Get mouse pointer position relative to the cursor
local x, y = UiGetMousePos()
UiIsMouseInRect
inside = UiIsMouseInRect(w, h)
Arguments
w (number) – Width
h (number) – Height
Return value
inside (boolean) – True if mouse pointer is within rectangle
Check if mouse pointer is within rectangle. Note that this function respects
alignment.
if UiIsMouseInRect(100, 100) then
-- mouse pointer is in rectangle
end
UiWorldToPixel
x, y, distance = UiWorldToPixel(point)
Arguments
point (table) – 3D world position as vector
Return value
x (number) – X coordinate
y (number) – Y coordinate
distance (number) – Distance to point
Convert world space position to user interface X and Y coordinate relative
to the cursor. The distance is in meters and positive if in front of camera,
negative otherwise.
local x, y, dist = UiWorldToPixel(point)
if dist > 0 then
UiTranslate(x, y)
UiText("Label")
end
UiPixelToWorld
direction = UiPixelToWorld(x, y)
Arguments
x (number) – X coordinate
y (number) – Y coordinate
Return value
direction (table) – 3D world direction as vector
Convert X and Y UI coordinate to a world direction, as seen from current camera.
This can be used to raycast into the scene from the mouse pointer position.
UiMakeInteractive()
local x, y = UiGetMousePos()
local dir = UiPixelToWorld(x, y)
local pos = GetCameraTransform().pos
local hit, dist = QueryRaycast(pos, dir, 100)
if hit then
DebugPrint("hit distance: " .. dist)
end
UiBlur
UiBlur(amount)
Arguments
amount (number) – Blur amount (0.0 to 1.0)
Return value
none
Perform a gaussian blur on current screen content
UiBlur(1.0)
drawMenu()
UiFont
UiFont(path, size)
Arguments
path (string) – Path to TTF font file
size (number) – Font size (10 to 100)
Return value
none
UiFont("bold.ttf", 24)
UiText("Hello")
UiFontHeight
size = UiFontHeight()
Arguments
none
Return value
size (number) – Font size
local h = UiFontHeight()
UiText
w, h = UiText(text, [move])
Arguments
text (string) – Print text at cursor location
move (boolean, optional) – Automatically move cursor vertically. Default false.
Return value
w (number) – Width of text
h (number) – Height of text
UiFont("bold.ttf", 24)
UiText("Hello")
...
--Automatically advance cursor
UiText("First line", true)
UiText("Second line", true)
UiGetTextSize
w, h = UiGetTextSize(text)
Arguments
text (string) – A text string
Return value
w (number) – Width of text
h (number) – Height of text
local w, h = UiGetTextSize("Some text")
UiWordWrap
UiWordWrap(width)
Arguments
width (number) – Maximum width of text
Return value
none
UiWordWrap(200)
UiText("Some really long text that will get wrapped into several lines")
UiTextOutline
UiTextOutline(r, g, b, a, [thickness])
Arguments
r (number) – Red channel
g (number) – Green channel
b (number) – Blue channel
a (number) – Alpha channel
thickness (number, optional) – Outline thickness. Default is 0.1
Return value
none
--Black outline, standard thickness
UiTextOutline(0,0,0,1)
UiText("Text with outline")
UiTextShadow
UiTextShadow(r, g, b, a, [distance], [blur])
Arguments
r (number) – Red channel
g (number) – Green channel
b (number) – Blue channel
a (number) – Alpha channel
distance (number, optional) – Shadow distance. Default is 1.0
blur (number, optional) – Shadow blur. Default is 0.5
Return value
none
--Black drop shadow, 50% transparent, distance 2
UiTextShadow(0, 0, 0, 0.5, 2.0)
UiText("Text with drop shadow")
UiRect
UiRect(w, h)
Arguments
w (number) – Width
h (number) – Height
Return value
none
Draw solid rectangle at cursor position
--Draw full-screen black rectangle
UiColor(0, 0, 0)
UiRect(UiWidth(), UiHeight())
--Draw smaller, red, rotating rectangle in center of screen
UiPush()
UiColor(1, 0, 0)
UiTranslate(UiCenter(), UiMiddle())
UiRotate(GetTime())
UiAlign("center middle")
UiRect(100, 100)
UiPop()
UiImage
w, h = UiImage(path, [x0], [y0], [x1], [y1])
Arguments
path (string) – Path to image (PNG or JPG format)
x0 (number, optional) – Lower x coordinate (default is 0)
y0 (number, optional) – Lower y coordinate (default is 0)
x1 (number, optional) – Upper x coordinate (default is image width)
y1 (number, optional) – Upper y coordinate (default is image height)
Return value
w (number) – Width of drawn image
h (number) – Height of drawn image
Draw image at cursor position. If x0, y0, x1, y1 is provided a cropped version
will be drawn in that coordinate range.
--Draw image in center of screen
UiPush()
UiTranslate(UiCenter(), UiMiddle())
UiAlign("center middle")
UiImage("test.png")
UiPop()
UiGetImageSize
w, h = UiGetImageSize(path)
Arguments
path (string) – Path to image (PNG or JPG format)
Return value
w (number) – Image width
h (number) – Image height
Get image size
local w,h = UiGetImageSize("test.png")
UiImageBox
UiImageBox(path, width, height, borderWidth, borderHeight)
Arguments
path (string) – Path to image (PNG or JPG format)
width (number) – Width
height (number) – Height
borderWidth (number) – Border width
borderHeight (number) – Border height
Return value
none
Draw 9-slice image at cursor position. Width should be at least 2*borderWidth.
Height should be at least 2*borderHeight.
UiImageBox("menu-frame.png", 200, 200, 10, 10)
UiSound
UiSound(path, [volume], [pitch], [pan])
Arguments
path (string) – Path to sound file (OGG format)
volume (number, optional) – Playback volume. Default 1.0
pitch (number, optional) – Playback pitch. Default 1.0
pan (number, optional) – Playback stereo panning (-1.0 to 1.0). Default 0.0.
Return value
none
UI sounds are not affected by acoustics simulation. Use LoadSound / PlaySound for that.
UiSound("click.ogg")
UiSoundLoop
UiSoundLoop(path, [volume])
Arguments
path (string) – Path to looping sound file (OGG format)
volume (number, optional) – Playback volume. Default 1.0
Return value
none
Call this continuously to keep playing loop.
UI sounds are not affected by acoustics simulation. Use LoadLoop / PlayLoop for that.
if animating then
UiSoundLoop("screech.ogg")
end
UiMute
UiMute(amount, [music])
Arguments
amount (number) – Mute by this amount (0.0 to 1.0)
music (boolean, optional) – Mute music as well
Return value
none
Mute game audio and optionally music for the next frame. Call
continuously to stay muted.
if menuOpen then
UiMute(1.0)
end
UiButtonImageBox
UiButtonImageBox(path, borderWidth, borderHeight, [r], [g], [b], [a])
Arguments
path (string) – Path to image (PNG or JPG format)
borderWidth (number) – Border width
borderHeight (number) – Border height
r (number, optional) – Red multiply. Default 1.0
g (number, optional) – Green multiply. Default 1.0
b (number, optional) – Blue multiply. Default 1.0
a (number, optional) – Alpha channel. Default 1.0
Return value
none
Set up 9-slice image to be used as background for buttons.
UiButtonImageBox("button-9slice.png", 10, 10)
if UiTextButton("Test") then
...
end
UiButtonHoverColor
UiButtonHoverColor(r, g, b, [a])
Arguments
r (number) – Red multiply
g (number) – Green multiply
b (number) – Blue multiply
a (number, optional) – Alpha channel. Default 1.0
Return value
none
Button color filter when hovering mouse pointer.
UiButtonHoverColor(1, 0, 0)
if UiTextButton("Test") then
...
end
UiButtonPressColor
UiButtonPressColor(r, g, b, [a])
Arguments
r (number) – Red multiply
g (number) – Green multiply
b (number) – Blue multiply
a (number, optional) – Alpha channel. Default 1.0
Return value
none
Button color filter when pressing down.
UiButtonPressColor(0, 1, 0)
if UiTextButton("Test") then
...
end
UiButtonPressDist
UiButtonPressDist(dist)
Arguments
dist (number) – Press distance
Return value
none
The button offset when being pressed
UiButtonPressDistance(4)
if UiTextButton("Test") then
...
end
UiTextButton
pressed = UiTextButton(text, [w], [h])
Arguments
text (string) – Text on button
w (number, optional) – Button width
h (number, optional) – Button height
Return value
pressed (boolean) – True if user clicked button
if UiTextButton("Test") then
...
end
UiImageButton
pressed = UiImageButton(path)
Arguments
path (number) – Image path (PNG or JPG file)
Return value
pressed (boolean) – True if user clicked button
if UiImageButton("image.png") then
...
end
UiBlankButton
pressed = UiBlankButton(w, h)
Arguments
w (number) – Button width
h (number) – Button height
Return value
pressed (boolean) – True if user clicked button
if UiBlankButton(30, 30) then
...
end
UiSlider
value, done = UiSlider(path, axis, current, min, max)
Arguments
path (number) – Image path (PNG or JPG file)
axis (string) – Drag axis, must be "x" or "y"
current (number) – Current value
min (number) – Minimum value
max (number) – Maximum value
Return value
value (number) – New value, same as current if not changed
done (boolean) – True if user is finished changing (released slider)
value = UiSlider("dot.png", "x", value, 0, 100)
UiGetScreen
handle = UiGetScreen()
Arguments
none
Return value
handle (number) – Handle to the screen running this script or zero if none.
--Turn off screen running current script
screen = UiGetScreen()
SetScreenEnabled(screen, false)