Functions, core hooks, messages and constants for manipulation of game objects. The "go" namespace is accessible from game object script files.
acquires the user input focus
Post this message to a game object instance to make that instance acquire the user input focus.
User input is distributed by the engine to every instance that has
requested it. The last instance to request focus will receive it first.
This means that the scripts in the instance will have first-hand-chance
at reacting on user input, possibly consuming it (by returning
true
from on_input
) so that no other instances
can react on it. The most common case is for a script to send this message
to itself when it needs to respond to user input.
A script belonging to an instance which has the user input focus will
receive the input actions in its on_input
callback function.
See on_input for more information on how user input can be
handled.
This example demonstrates how to acquire and act on user input.
function init(self) -- acquire input focus as soon as the instance has been initialized msg.post(".", "acquire_input_focus") end function on_input(self, action_id, action) -- check which input we received if action_id == hash("my_action") then -- act on the input self.my_action_amount = action.value end end
disables the receiving component
This message disables the receiving component. All components are enabled by default, which means they will receive input, updates
and be a part of the simulation. A component is disabled when it receives the disable
message.
Components that currently supports this message are:
Disable the component "my_component":
msg.post("#my_component", "disable")
enables the receiving component
This message enables the receiving component. All components are enabled by default, which means they will receive input, updates
and be a part of the simulation. A component is disabled when it receives the disable
message.
Components that currently supports this message are:
Enable the component "my_component":
msg.post("#my_component", "enable")
vector3 game object euler rotation
The rotation of the game object expressed in Euler angles. Euler angles are specified in degrees in the interval (-360, 360). The type of the property is vector3.
How to set a game object's rotation with euler angles, either as a vector3 or selecting a specific dimension:
function init(self) -- set "player" euler z rotation component to 45 degrees around z. local rotz = 45 go.set("player", "euler.z", rotz) local rot = go.get("player", "euler") -- do something useful assert(rot.z == rotz) end
called when a script component is finalized
This is a callback-function, which is called by the engine when a script component is finalized (destroyed). It can be used to e.g. take some last action, report the finalization to other game object instances, delete spawned objects or release user input focus (see release_input_focus).
self -
object reference to the script state to be used for storing data
function final(self) -- report finalization msg.post("my_friend_instance", "im_dead", {my_stats = self.some_value}) end
in-back
in-bounce
in-circlic
in-cubic
in-elastic
in-exponential
in-out-back
in-out-bounce
in-out-circlic
in-out-cubic
in-out-elastic
in-out-exponential
in-out-quadratic
in-out-quartic
in-out-quintic
in-out-sine
in-quadratic
in-quartic
in-quintic
in-sine
linear interpolation
out-back
out-bounce
out-circlic
out-cubic
out-elastic
out-exponential
out-in-back
out-in-bounce
out-in-circlic
out-in-cubic
out-in-elastic
out-in-exponential
out-in-quadratic
out-in-quartic
out-in-quintic
out-in-sine
out-quadratic
out-quartic
out-quintic
out-sine
loop backward
loop forward
ping pong loop
no playback
once backward
once forward
once ping pong
animates a named property of the specified game object or component
This is only supported for numerical properties. If the node property is already being animated, that animation will be canceled and replaced by the new one.
If a complete_function
(lua function) is specified, that function will be called when the animation has completed.
By starting a new animation in that function, several animations can be sequenced together. See the examples for more information.
If you call go.animate()
from a game object's final()
function,
any passed complete_function
will be ignored and never called upon animation completion.
See the properties guide for which properties can be animated and the animation guide for how to animate them.
url -
string | hash | url url of the game object or component having the property
property -
string | hash id of the property to animate
playback -
constant playback mode of the animation
go.PLAYBACK_ONCE_FORWARD
go.PLAYBACK_ONCE_BACKWARD
go.PLAYBACK_ONCE_PINGPONG
go.PLAYBACK_LOOP_FORWARD
go.PLAYBACK_LOOP_BACKWARD
go.PLAYBACK_LOOP_PINGPONG
to -
number | vector3 | vector4 | quaternion target property value
easing -
constant | vector easing to use during animation. Either specify a constant, see the animation guide for a complete list, or a vmath.vector with a curve
duration -
number duration of the animation in seconds
[delay] -
number delay before the animation starts in seconds
[complete_function] -
function(self, url, property) optional function to call when the animation has completed
self
object The current object.
url
url The game object or component instance for which the property is animated.
property
hash The id of the animated property.
Animate the position of a game object to x = 10 during 1 second, then y = 20 during 1 second:
local function x_done(self, url, property) go.animate(go.get_id(), "position.y", go.PLAYBACK_ONCE_FORWARD, 20, go.EASING_LINEAR, 1) end function init(self) go.animate(go.get_id(), "position.x", go.PLAYBACK_ONCE_FORWARD, 10, go.EASING_LINEAR, 1, 0, x_done) end
Animate the y position of a game object using a crazy custom easing curve:
local values = { 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1 } local vec = vmath.vector(values) go.animate("go", "position.y", go.PLAYBACK_LOOP_PINGPONG, 100, vec, 2.0)
cancels all animations of the named property of the specified game object or component
By calling this function, all stored animations of the given property will be canceled.
See the properties guide for which properties can be animated and the animation guide for how to animate them.
url -
string | hash | url url of the game object or component having the property
property -
string | hash ide of the property to animate
Cancel the animation of the position of a game object:
go.cancel_animations(go.get_id(), "position")
delete one or more game object instances
Delete one or more game objects identified by id. Deletion is asynchronous meaning that
the game object(s) are scheduled for deletion which will happen at the end of the current
frame. Note that game objects scheduled for deletion will be counted against
max_instances
in "game.project" until they are actually removed.
Deleting a game object containing a particle FX component emitting particles will not immediately stop the particle FX from emitting particles. You need to manually stop the particle FX using particlefx.stop()
.
Deleting a game object containing a sound component that is playing will not immediately stop the sound from playing. You need to manually stop the sound using sound.stop()
.
[id] -
string | hash | url | table optional id or table of id's of the instance(s) to delete, the instance of the calling script is deleted by default
[recursive] -
boolean optional boolean, set to true to recursively delete child hiearchy in child to parent order
This example demonstrates how to delete game objects
-- Delete the script game object go.delete() -- Delete a game object with the id "my_game_object". local id = go.get_id("my_game_object") -- retrieve the id of the game object to be deleted go.delete(id) -- Delete a list of game objects. local ids = { hash("/my_object_1"), hash("/my_object_2"), hash("/my_object_3") } go.delete(ids)
This example demonstrates how to delete a game objects and their children (child to parent order)
-- Delete the script game object and it's children go.delete(true) -- Delete a game object with the id "my_game_object" and it's children. local id = go.get_id("my_game_object") -- retrieve the id of the game object to be deleted go.delete(id, true) -- Delete a list of game objects and their children. local ids = { hash("/my_object_1"), hash("/my_object_2"), hash("/my_object_3") } go.delete(ids, true)
gets a named property of the specified game object or component
url -
string | hash | url url of the game object or component having the property
property -
string | hash id of the property to retrieve
value -
any the value of the specified property
Get a property "speed" from a script "player", the property must be declared in the player-script:
go.property("speed", 50)
Then in the calling script (assumed to belong to the same game object, but does not have to):
local speed = go.get("#player", "speed")
gets the id of an instance
Returns or constructs an instance identifier. The instance id is a hash of the absolute path to the instance.
path
is specified, it can either be absolute or relative to the instance of the calling script.path
is not specified, the id of the game object instance the script is attached to will be returned.[path] -
string path of the instance for which to return the id
id -
hash instance id
For the instance with path /my_sub_collection/my_instance
, the following calls are equivalent:
local id = go.get_id() -- no path, defaults to the instance containing the calling script print(id) --> hash: [/my_sub_collection/my_instance] local id = go.get_id("/my_sub_collection/my_instance") -- absolute path print(id) --> hash: [/my_sub_collection/my_instance] local id = go.get_id("my_instance") -- relative path print(id) --> hash: [/my_sub_collection/my_instance]
gets the position of a game object instance
The position is relative the parent (if any). Use go.get_world_position to retrieve the global world position.
[id] -
string | hash | url optional id of the game object instance to get the position for, by default the instance of the calling script
position -
vector3 instance position
Get the position of the game object instance the script is attached to:
local p = go.get_position()
Get the position of another game object instance "my_gameobject":
local pos = go.get_position("my_gameobject")
gets the rotation of the game object instance
The rotation is relative to the parent (if any). Use go.get_world_rotation to retrieve the global world position.
[id] -
string | hash | url optional id of the game object instance to get the rotation for, by default the instance of the calling script
rotation -
quaternion instance rotation
Get the rotation of the game object instance the script is attached to:
local r = go.get_rotation()
Get the rotation of another game object instance with id "x":
local r = go.get_rotation("x")
gets the 3D scale factor of the game object instance
The scale is relative the parent (if any). Use go.get_world_scale to retrieve the global world 3D scale factor.
[id] -
string | hash | url optional id of the game object instance to get the scale for, by default the instance of the calling script
scale -
vector3 instance scale factor
Get the scale of the game object instance the script is attached to:
local s = go.get_scale()
Get the scale of another game object instance with id "x":
local s = go.get_scale("x")
gets the uniform scale factor of the game object instance
The uniform scale is relative the parent (if any). If the underlying scale vector is non-uniform the min element of the vector is returned as the uniform scale factor.
[id] -
string | hash | url optional id of the game object instance to get the uniform scale for, by default the instance of the calling script
scale -
number uniform instance scale factor
Get the scale of the game object instance the script is attached to:
local s = go.get_scale_uniform()
Get the uniform scale of another game object instance with id "x":
local s = go.get_scale_uniform("x")
gets the game object instance world position
Use go.get_position to retrieve the position relative to the parent.
[id] -
string | hash | url optional id of the game object instance to get the world position for, by default the instance of the calling script
position -
vector3 instance world position
Get the world position of the game object instance the script is attached to:
local p = go.get_world_position()
Get the world position of another game object instance with id "x":
local p = go.get_world_position("x")
gets the game object instance world rotation
Use go.get_rotation
to retrieve the rotation relative to the parent.
[id] -
string | hash | url optional id of the game object instance to get the world rotation for, by default the instance of the calling script
rotation -
quaternion instance world rotation
Get the world rotation of the game object instance the script is attached to:
local r = go.get_world_rotation()
Get the world rotation of another game object instance with id "x":
local r = go.get_world_rotation("x")
gets the game object instance world 3D scale factor
Use go.get_scale
to retrieve the 3D scale factor relative to the parent.
This vector is derived by decomposing the transformation matrix and should be used with care.
For most cases it should be fine to use go.get_world_scale_uniform instead.
[id] -
string | hash | url optional id of the game object instance to get the world scale for, by default the instance of the calling script
scale -
vector3 instance world 3D scale factor
Get the world 3D scale of the game object instance the script is attached to:
local s = go.get_world_scale()
Get the world scale of another game object instance "x":
local s = go.get_world_scale("x")
gets the uniform game object instance world scale factor
Use go.get_scale_uniform
to retrieve the scale factor relative to the parent.
[id] -
string | hash | url optional id of the game object instance to get the world scale for, by default the instance of the calling script
scale -
number instance world scale factor
Get the world scale of the game object instance the script is attached to:
local s = go.get_world_scale_uniform()
Get the world scale of another game object instance with id "x":
local s = go.get_world_scale_uniform("x")
gets the game object instance world transform matrix
[id] -
string | hash | url optional id of the game object instance to get the world transform for, by default the instance of the calling script
transform -
matrix4 instance world transform
Get the world transform of the game object instance the script is attached to:
local m = go.get_world_transform()
Get the world transform of another game object instance with id "x":
local m = go.get_world_transform("x")
define a property for the script
This function defines a property which can then be used in the script through the self-reference. The properties defined this way are automatically exposed in the editor in game objects and collections which use the script. Note that you can only use this function outside any callback-functions like init and update.
name -
string the id of the property
value -
number | hash | url | vector3 | vector4 | quaternion default value of the property. In the case of a url, only the empty constructor msg.url() is allowed
This example demonstrates how to define a property called "health" in a script. The health is decreased whenever someone sends a message called "take_damage" to the script.
go.property("health", 100) function init(self) -- prints 100 to the output print(self.health) end function on_message(self, message_id, message, sender) if message_id == hash("take_damage") then self.health = self.health - message.damage print("Ouch! My health is now: " .. self.health) end end
sets a named property of the specified game object or component
url -
string | hash | url url of the game object or component having the property
property -
string | hash id of the property to set
value -
any the value to set
Set a property "speed" of a script "player", the property must be declared in the player-script:
go.property("speed", 50)
Then in the calling script (assumed to belong to the same game object, but does not have to):
go.set("#player", "speed", 100)
sets the parent for a specific game object instance
Sets the parent for a game object instance. This means that the instance will exist in the geometrical space of its parent, like a basic transformation hierarchy or scene graph. If no parent is specified, the instance will be detached from any parent and exist in world space.
[id] -
string | hash | url optional id of the game object instance to set parent for, defaults to the instance containing the calling script
[parent_id] -
string | hash | url optional id of the new parent game object, defaults to detaching game object from its parent
[keep_world_transform] -
boolean optional boolean, set to true to maintain the world transform when changing spaces. Defaults to false.
Attach myself to another instance "my_parent":
go.set_parent(go.get_id(),go.get_id("my_parent"))
Attach an instance "my_instance" to another instance "my_parent":
go.set_parent(go.get_id("my_instance"),go.get_id("my_parent"))
Detach an instance "my_instance" from its parent (if any):
go.set_parent(go.get_id("my_instance"))
sets the position of the game object instance
The position is relative to the parent (if any). The global world position cannot be manually set.
position -
vector3 position to set
[id] -
string | hash | url optional id of the game object instance to set the position for, by default the instance of the calling script
Set the position of the game object instance the script is attached to:
local p = ... go.set_position(p)
Set the position of another game object instance with id "x":
local p = ... go.set_position(p, "x")
sets the rotation of the game object instance
The rotation is relative to the parent (if any). The global world rotation cannot be manually set.
rotation -
quaternion rotation to set
[id] -
string | hash | url optional id of the game object instance to get the rotation for, by default the instance of the calling script
Set the rotation of the game object instance the script is attached to:
local r = ... go.set_rotation(r)
Set the rotation of another game object instance with id "x":
local r = ... go.set_rotation(r, "x")
sets the scale factor of the game object instance
The scale factor is relative to the parent (if any). The global world scale factor cannot be manually set.
Physics are currently not affected when setting scale from this function.
scale -
number | vector3 vector or uniform scale factor, must be greater than 0
[id] -
string | hash | url optional id of the game object instance to get the scale for, by default the instance of the calling script
Set the scale of the game object instance the script is attached to:
local s = vmath.vector3(2.0, 1.0, 1.0) go.set_scale(s)
Set the scale of another game object instance with id "x":
local s = 1.2 go.set_scale(s, "x")
called when a script component is initialized
This is a callback-function, which is called by the engine when a script component is initialized. It can be used to set the initial state of the script.
self -
object reference to the script state to be used for storing data
function init(self) -- set up useful data self.my_value = 1 end
called when user input is received
This is a callback-function, which is called by the engine when user input is sent to the game object instance of the script. It can be used to take action on the input, e.g. move the instance according to the input.
For an instance to obtain user input, it must first acquire input focus
through the message acquire_input_focus
.
Any instance that has obtained input will be put on top of an
input stack. Input is sent to all listeners on the stack until the
end of stack is reached, or a listener returns true
to signal that it wants input to be consumed.
See the documentation of acquire_input_focus for more information.
The action
parameter is a table containing data about the input mapped to the
action_id
.
For mapped actions it specifies the value of the input and if it was just pressed or released.
Actions are mapped to input in an input_binding-file.
Mouse movement is specifically handled and uses nil
as its action_id
.
The action
only contains positional parameters in this case, such as x and y of the pointer.
Here is a brief description of the available table fields:
Field | Description |
---|---|
value |
The amount of input given by the user. This is usually 1 for buttons and 0-1 for analogue inputs. This is not present for mouse movement. |
pressed |
If the input was pressed this frame. This is not present for mouse movement. |
released |
If the input was released this frame. This is not present for mouse movement. |
repeated |
If the input was repeated this frame. This is similar to how a key on a keyboard is repeated when you hold it down. This is not present for mouse movement. |
x |
The x value of a pointer device, if present. |
y |
The y value of a pointer device, if present. |
screen_x |
The screen space x value of a pointer device, if present. |
screen_y |
The screen space y value of a pointer device, if present. |
dx |
The change in x value of a pointer device, if present. |
dy |
The change in y value of a pointer device, if present. |
screen_dx |
The change in screen space x value of a pointer device, if present. |
screen_dy |
The change in screen space y value of a pointer device, if present. |
gamepad |
The index of the gamepad device that provided the input. |
touch |
List of touch input, one element per finger, if present. See table below about touch input |
Touch input table:
Field | Description |
---|---|
id |
A number identifying the touch input during its duration. |
pressed |
True if the finger was pressed this frame. |
released |
True if the finger was released this frame. |
tap_count |
Number of taps, one for single, two for double-tap, etc |
x |
The x touch location. |
y |
The y touch location. |
dx |
The change in x value. |
dy |
The change in y value. |
acc_x |
Accelerometer x value (if present). |
acc_y |
Accelerometer y value (if present). |
acc_z |
Accelerometer z value (if present). |
self -
object reference to the script state to be used for storing data
action_id -
hash id of the received input action, as mapped in the input_binding-file
action -
table a table containing the input data, see above for a description
[consume] -
boolean optional boolean to signal if the input should be consumed (not passed on to others) or not, default is false
This example demonstrates how a game object instance can be moved as a response to user input.
function init(self) -- acquire input focus msg.post(".", "acquire_input_focus") -- maximum speed the instance can be moved self.max_speed = 2 -- velocity of the instance, initially zero self.velocity = vmath.vector3() end function update(self, dt) -- move the instance go.set_position(go.get_position() + dt * self.velocity) end function on_input(self, action_id, action) -- check for movement input if action_id == hash("right") then if action.released then -- reset velocity if input was released self.velocity = vmath.vector3() else -- update velocity self.velocity = vmath.vector3(action.value * self.max_speed, 0, 0) end end end
called when a message has been sent to the script component
This is a callback-function, which is called by the engine whenever a message has been sent to the script component. It can be used to take action on the message, e.g. send a response back to the sender of the message.
The message
parameter is a table containing the message data. If the message is sent from the engine, the
documentation of the message specifies which data is supplied.
self -
object reference to the script state to be used for storing data
message_id -
hash id of the received message
message -
table a table containing the message data
sender -
url address of the sender
This example demonstrates how a game object instance, called "a", can communicate with another instance, called "b". It is assumed that both script components of the instances has id "script".
Script of instance "a":
function init(self) -- let b know about some important data msg.post("b#script", "my_data", {important_value = 1}) end
Script of instance "b":
function init(self) -- store the url of instance "a" for later use, by specifying nil as socket we -- automatically use our own socket self.a_url = msg.url(nil, go.get_id("a"), "script") end function on_message(self, message_id, message, sender) -- check message and sender if message_id == hash("my_data") and sender == self.a_url then -- use the data in some way self.important_value = message.important_value end end
called when the script component is reloaded
This is a callback-function, which is called by the engine when the script component is reloaded, e.g. from the editor. It can be used for live development, e.g. to tweak constants or set up the state properly for the instance.
self -
object reference to the script state to be used for storing data
This example demonstrates how to tweak the speed of a game object instance that is moved on user input.
function init(self) -- acquire input focus msg.post(".", "acquire_input_focus") -- maximum speed the instance can be moved, this value is tweaked in the on_reload function below self.max_speed = 2 -- velocity of the instance, initially zero self.velocity = vmath.vector3() end function update(self, dt) -- move the instance go.set_position(go.get_position() + dt * self.velocity) end function on_input(self, action_id, action) -- check for movement input if action_id == hash("right") then if action.released then -- reset velocity if input was released self.velocity = vmath.vector3() else -- update velocity self.velocity = vmath.vector3(action.value * self.max_speed, 0, 0) end end end function on_reload(self) -- edit this value and reload the script component self.max_speed = 100 end
vector3 game object position
The position of the game object. The type of the property is vector3.
How to query a game object's position, either as a vector3 or selecting a specific dimension:
function init(self) -- get position from "player" local pos = go.get("player", "position") local posx = go.get("player", "position.x") -- do something useful assert(pos.x == posx) end
releases the user input focus
Post this message to an instance to make that instance release the user input focus. See acquire_input_focus for more information on how the user input handling works.
How to make a game object stop receiving input:
msg.post(".", "release_input_focus")
quaternion game object rotation
The rotation of the game object. The type of the property is quaternion.
How to set a game object's rotation:
function init(self) -- set "player" rotation to 45 degrees around z. local rotz = vmath.quat_rotation_z(3.141592 / 4) go.set("player", "rotation", rotz) end
number game object scale
The uniform scale of the game object. The type of the property is number.
How to scale a game object:
function init(self) -- Double the scaling on "player" local scale = go.get("player", "scale") go.set("player", "scale", scale * 2) end
sets the parent of the receiving instance
When this message is sent to an instance, it sets the parent of that instance. This means that the instance will exist in the geometrical space of its parent, like a basic transformation hierarchy or scene graph. If no parent is specified, the instance will be detached from any parent and exist in world space. A script can send this message to itself to set the parent of its instance.
parent_id -
hash the id of the new parent
keep_world_transform -
number if the world transform of the instance should be preserved when changing spaces, 0 for false and 1 for true. The default value is 1.
Attach myself to another instance "my_parent":
msg.post(".", "set_parent", {parent_id = go.get_id("my_parent")})
Attach an instance "my_instance" to another instance "my_parent":
msg.post("my_instance", "set_parent", {parent_id = go.get_id("my_parent")})
Detach an instance "my_instance" from its parent (if any):
msg.post("my_instance", "set_parent")
called every frame to update the script component
This is a callback-function, which is called by the engine every frame to update the state of a script component. It can be used to perform any kind of game related tasks, e.g. moving the game object instance.
self -
object reference to the script state to be used for storing data
dt -
number the time-step of the frame update
This example demonstrates how to move a game object instance through the script component:
function init(self) -- set initial velocity to be 1 along world x-axis self.my_velocity = vmath.vector3(1, 0, 0) end function update(self, dt) -- move the game object instance go.set_position(go.get_position() + dt * self.my_velocity) end