Game object

Functions, core hooks, messages and constants for manipulation of game objects. The "go" namespace is accessible from game object script files.

Namespace: go
Include: #include <>
CONSTANTS
go.EASING_INBACK in-back
go.EASING_INBOUNCE in-bounce
go.EASING_INCIRC in-circlic
go.EASING_INCUBIC in-cubic
go.EASING_INELASTIC in-elastic
go.EASING_INEXPO in-exponential
go.EASING_INOUTBACK in-out-back
go.EASING_INOUTBOUNCE in-out-bounce
go.EASING_INOUTCIRC in-out-circlic
go.EASING_INOUTCUBIC in-out-cubic
go.EASING_INOUTELASTIC in-out-elastic
go.EASING_INOUTEXPO in-out-exponential
go.EASING_INOUTQUAD in-out-quadratic
go.EASING_INOUTQUART in-out-quartic
go.EASING_INOUTQUINT in-out-quintic
go.EASING_INOUTSINE in-out-sine
go.EASING_INQUAD in-quadratic
go.EASING_INQUART in-quartic
go.EASING_INQUINT in-quintic
go.EASING_INSINE in-sine
go.EASING_LINEAR linear interpolation
go.EASING_OUTBACK out-back
go.EASING_OUTBOUNCE out-bounce
go.EASING_OUTCIRC out-circlic
go.EASING_OUTCUBIC out-cubic
go.EASING_OUTELASTIC out-elastic
go.EASING_OUTEXPO out-exponential
go.EASING_OUTINBACK out-in-back
go.EASING_OUTINBOUNCE out-in-bounce
go.EASING_OUTINCIRC out-in-circlic
go.EASING_OUTINCUBIC out-in-cubic
go.EASING_OUTINELASTIC out-in-elastic
go.EASING_OUTINEXPO out-in-exponential
go.EASING_OUTINQUAD out-in-quadratic
go.EASING_OUTINQUART out-in-quartic
go.EASING_OUTINQUINT out-in-quintic
go.EASING_OUTINSINE out-in-sine
go.EASING_OUTQUAD out-quadratic
go.EASING_OUTQUART out-quartic
go.EASING_OUTQUINT out-quintic
go.EASING_OUTSINE out-sine
go.PLAYBACK_LOOP_BACKWARD loop backward
go.PLAYBACK_LOOP_FORWARD loop forward
go.PLAYBACK_LOOP_PINGPONG ping pong loop
go.PLAYBACK_NONE no playback
go.PLAYBACK_ONCE_BACKWARD once backward
go.PLAYBACK_ONCE_FORWARD once forward
go.PLAYBACK_ONCE_PINGPONG once ping pong
MESSAGES
acquire_input_focus acquires the user input focus
disable disables the receiving component
enable enables the receiving component
release_input_focus releases the user input focus
set_parent sets the parent of the receiving instance
PROPERTIES
euler vector3 game object euler rotation
position vector3 game object position
rotation quaternion game object rotation
scale number game object scale
FUNCTIONS
void final(object self) called when a script component is finalized
void fixed_update(object self, number dt) called at fixed intervals to update the script component
void go.animate(stringhashurl url, stringhash property, constant playback, numbervector3vector4quaternion to, constantvector easing, number duration, number [delay], function(self, url, property) [complete_function]) animates a named property of the specified game object or component
void go.cancel_animations(stringhashurl url, stringhash [property]) cancels all or specified property animations of the game object or component
void go.delete(stringhashurltable [id], boolean [recursive]) delete one or more game object instances
bool go.exists(stringhashurl url) check if the specified game object exists
any go.get(stringhashurl url, stringhash property, table [options]) gets a named property of the specified game object or component
hash go.get_id(string [path]) gets the id of an instance
nil go.get_parent(stringhashurl [id]) get the parent for a specific game object instance
vector3 go.get_position(stringhashurl [id]) gets the position of a game object instance
quaternion go.get_rotation(stringhashurl [id]) gets the rotation of the game object instance
vector3 go.get_scale(stringhashurl [id]) gets the 3D scale factor of the game object instance
number go.get_scale_uniform(stringhashurl [id]) gets the uniform scale factor of the game object instance
vector3 go.get_world_position(stringhashurl [id]) gets the game object instance world position
quaternion go.get_world_rotation(stringhashurl [id]) gets the game object instance world rotation
vector3 go.get_world_scale(stringhashurl [id]) gets the game object instance world 3D scale factor
number go.get_world_scale_uniform(stringhashurl [id]) gets the uniform game object instance world scale factor
matrix4 go.get_world_transform(stringhashurl [id]) gets the game object instance world transform matrix
void go.property(string name, numberhashurlvector3vector4quaternionresourceboolean value) define a property for the script
void go.set(stringhashurl url, stringhash property, anytable value, table [options]) sets a named property of the specified game object or component, or a material constant
void go.set_parent(stringhashurl [id], stringhashurl [parent_id], boolean [keep_world_transform]) sets the parent for a specific game object instance
void go.set_position(vector3 position, stringhashurl [id]) sets the position of the game object instance
void go.set_rotation(quaternion rotation, stringhashurl [id]) sets the rotation of the game object instance
void go.set_scale(numbervector3 scale, stringhashurl [id]) sets the scale factor of the game object instance
vector3 go.world_to_local_position(vector3 position, stringhashurl url) convert position to game object's coordinate space
matrix4 go.world_to_local_transform(matrix4 transformation, stringhashurl url) convert transformation matrix to game object's coordinate space
void init(object self) called when a script component is initialized
nil on_input(object self, hash action_id, table action) called when user input is received
void on_message(object self, hash message_id, table message, url sender) called when a message has been sent to the script component
void on_reload(object self) called when the script component is reloaded
void update(object self, number dt) called every frame to update the script component

Functions

final

void final(object self)

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).

PARAMETERS

object self reference to the script state to be used for storing data

EXAMPLES

function final(self)
    -- report finalization
    msg.post("my_friend_instance", "im_dead", {my_stats = self.some_value})
end

fixed_update

void fixed_update(object self, number dt)

This is a callback-function, which is called by the engine at fixed intervals to update the state of a script component. The function will be called if 'Fixed Update Frequency' is enabled in the Engine section of game.project. It can for instance be used to update game logic with the physics simulation if using a fixed timestep for the physics (enabled by ticking 'Use Fixed Timestep' in the Physics section of game.project).

PARAMETERS

object self reference to the script state to be used for storing data
number dt the time-step of the frame update

go.animate

void go.animate(stringhashurl url, stringhash property, constant playback, numbervector3vector4quaternion to, constantvector easing, number duration, number [delay], function(self, url, property) [complete_function])

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 them.

PARAMETERS

string url url of the game object or component having the propertyhash url url of the game object or component having the propertyurl url url of the game object or component having the property
string property id of the property to animatehash property id of the property to animate
constant playback 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
number to target property valuevector3 to target property valuevector4 to target property valuequaternion to target property value
constant easing easing to use during animation. Either specify a constant, see the animation guide for a complete list, or a vmath.vector with a curvevector easing easing to use during animation. Either specify a constant, see the animation guide for a complete list, or a vmath.vector with a curve
number duration duration of the animation in seconds
number [delay] delay before the animation starts in seconds
function(self, url, property) [complete_function] 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.

EXAMPLES

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)

go.cancel_animations

void go.cancel_animations(stringhashurl url, stringhash [property])

By calling this function, all or specified stored property animations of the game object or component will be canceled. See the properties guide for which properties can be animated and the animation guide for how to animate them.

PARAMETERS

string url url of the game object or componenthash url url of the game object or componenturl url url of the game object or component
string [property] optional id of the property to cancelhash [property] optional id of the property to cancel

EXAMPLES

Cancel the animation of the position of a game object:
go.cancel_animations(go.get_id(), "position")
Cancel all property animations of the current game object:
go.cancel_animations(".")
Cancel all property animations of the sprite component of the current game object:
go.cancel_animations("#sprite")

go.delete

void go.delete(stringhashurltable [id], boolean [recursive])

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().

PARAMETERS

string [id] optional id or table of id's of the instance(s) to delete, the instance of the calling script is deleted by defaulthash [id] optional id or table of id's of the instance(s) to delete, the instance of the calling script is deleted by defaulturl [id] optional id or table of id's of the instance(s) to delete, the instance of the calling script is deleted by defaulttable [id] optional id or table of id's of the instance(s) to delete, the instance of the calling script is deleted by default
boolean [recursive] optional boolean, set to true to recursively delete child hiearchy in child to parent order

EXAMPLES

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)

go.exists

bool go.exists(stringhashurl url)

check if the specified game object exists

PARAMETERS

string url url of the game object to checkhash url url of the game object to checkurl url url of the game object to check

RETURNS

bool true if the game object exists

EXAMPLES

Check if game object "my_game_object" exists
go.exists("/my_game_object")

go.get

any go.get(stringhashurl url, stringhash property, table [options])

gets a named property of the specified game object or component

PARAMETERS

string url url of the game object or component having the propertyhash url url of the game object or component having the propertyurl url url of the game object or component having the property
string property id of the property to retrievehash property id of the property to retrieve
table [options] optional options table - index integer index into array property (1 based) - key hash name of internal property

RETURNS

any the value of the specified property

EXAMPLES

Get a named property
function init(self)
    -- get the resource of a certain gui font
    local font_hash = go.get("#gui", "fonts", {key = "system_font_BIG"})
end

go.get_id

hash go.get_id(string [path])

Returns or constructs an instance identifier. The instance id is a hash of the absolute path to the instance.

  • If path is specified, it can either be absolute or relative to the instance of the calling script.
  • If path is not specified, the id of the game object instance the script is attached to will be returned.

PARAMETERS

string [path] path of the instance for which to return the id

RETURNS

hash instance id

EXAMPLES

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]

go.get_parent

nil go.get_parent(stringhashurl [id])

Get the parent for a game object instance.

PARAMETERS

string [id] optional id of the game object instance to get parent for, defaults to the instance containing the calling scripthash [id] optional id of the game object instance to get parent for, defaults to the instance containing the calling scripturl [id] optional id of the game object instance to get parent for, defaults to the instance containing the calling script

RETURNS

hash parent instance or nil
nil parent instance or nil

EXAMPLES

Get parent of the instance containing the calling script:
local parent_id = go.get_parent()
Get parent of the instance with id "x":
local parent_id = go.get_parent("x")

go.get_position

vector3 go.get_position(stringhashurl [id])

The position is relative the parent (if any). Use go.get_world_position to retrieve the global world position.

PARAMETERS

string [id] optional id of the game object instance to get the position for, by default the instance of the calling scripthash [id] optional id of the game object instance to get the position for, by default the instance of the calling scripturl [id] optional id of the game object instance to get the position for, by default the instance of the calling script

RETURNS

vector3 instance position

EXAMPLES

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")

go.get_rotation

quaternion go.get_rotation(stringhashurl [id])

The rotation is relative to the parent (if any). Use go.get_world_rotation to retrieve the global world rotation.

PARAMETERS

string [id] optional id of the game object instance to get the rotation for, by default the instance of the calling scripthash [id] optional id of the game object instance to get the rotation for, by default the instance of the calling scripturl [id] optional id of the game object instance to get the rotation for, by default the instance of the calling script

RETURNS

quaternion instance rotation

EXAMPLES

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")

go.get_scale

vector3 go.get_scale(stringhashurl [id])

The scale is relative the parent (if any). Use go.get_world_scale to retrieve the global world 3D scale factor.

PARAMETERS

string [id] optional id of the game object instance to get the scale for, by default the instance of the calling scripthash [id] optional id of the game object instance to get the scale for, by default the instance of the calling scripturl [id] optional id of the game object instance to get the scale for, by default the instance of the calling script

RETURNS

vector3 instance scale factor

EXAMPLES

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")

go.get_scale_uniform

number go.get_scale_uniform(stringhashurl [id])

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.

PARAMETERS

string [id] optional id of the game object instance to get the uniform scale for, by default the instance of the calling scripthash [id] optional id of the game object instance to get the uniform scale for, by default the instance of the calling scripturl [id] optional id of the game object instance to get the uniform scale for, by default the instance of the calling script

RETURNS

number uniform instance scale factor

EXAMPLES

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")

go.get_world_position

vector3 go.get_world_position(stringhashurl [id])

The function will return the world position calculated at the end of the previous frame. Use go.get_position to retrieve the position relative to the parent.

PARAMETERS

string [id] optional id of the game object instance to get the world position for, by default the instance of the calling scripthash [id] optional id of the game object instance to get the world position for, by default the instance of the calling scripturl [id] optional id of the game object instance to get the world position for, by default the instance of the calling script

RETURNS

vector3 instance world position

EXAMPLES

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")

go.get_world_rotation

quaternion go.get_world_rotation(stringhashurl [id])

The function will return the world rotation calculated at the end of the previous frame. Use go.get_rotation to retrieve the rotation relative to the parent.

PARAMETERS

string [id] optional id of the game object instance to get the world rotation for, by default the instance of the calling scripthash [id] optional id of the game object instance to get the world rotation for, by default the instance of the calling scripturl [id] optional id of the game object instance to get the world rotation for, by default the instance of the calling script

RETURNS

quaternion instance world rotation

EXAMPLES

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")

go.get_world_scale

vector3 go.get_world_scale(stringhashurl [id])

The function will return the world 3D scale factor calculated at the end of the previous frame. 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.

PARAMETERS

string [id] optional id of the game object instance to get the world scale for, by default the instance of the calling scripthash [id] optional id of the game object instance to get the world scale for, by default the instance of the calling scripturl [id] optional id of the game object instance to get the world scale for, by default the instance of the calling script

RETURNS

vector3 instance world 3D scale factor

EXAMPLES

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")

go.get_world_scale_uniform

number go.get_world_scale_uniform(stringhashurl [id])

The function will return the world scale factor calculated at the end of the previous frame. Use go.get_scale_uniform to retrieve the scale factor relative to the parent.

PARAMETERS

string [id] optional id of the game object instance to get the world scale for, by default the instance of the calling scripthash [id] optional id of the game object instance to get the world scale for, by default the instance of the calling scripturl [id] optional id of the game object instance to get the world scale for, by default the instance of the calling script

RETURNS

number instance world scale factor

EXAMPLES

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")

go.get_world_transform

matrix4 go.get_world_transform(stringhashurl [id])

The function will return the world transform matrix calculated at the end of the previous frame.

PARAMETERS

string [id] optional id of the game object instance to get the world transform for, by default the instance of the calling scripthash [id] optional id of the game object instance to get the world transform for, by default the instance of the calling scripturl [id] optional id of the game object instance to get the world transform for, by default the instance of the calling script

RETURNS

matrix4 instance world transform

EXAMPLES

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")

go.property

void go.property(string name, numberhashurlvector3vector4quaternionresourceboolean value)

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.

PARAMETERS

string name the id of the property
number value default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.hash value default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.url value default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.vector3 value default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.vector4 value default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.quaternion value default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.resource value default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.boolean value default value of the property. In the case of a url, only the empty constructor msg.url() is allowed. In the case of a resource one of the resource constructors (eg resource.atlas(), resource.font() etc) is expected.

EXAMPLES

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

go.set

void go.set(stringhashurl url, stringhash property, anytable value, table [options])

sets a named property of the specified game object or component, or a material constant

PARAMETERS

string url url of the game object or component having the propertyhash url url of the game object or component having the propertyurl url url of the game object or component having the property
string property id of the property to sethash property id of the property to set
any value the value to settable value the value to set
table [options] optional options table - index integer index into array property (1 based) - key hash name of internal property

EXAMPLES

Set a named property
go.property("big_font", resource.font())

function init(self)
    go.set("#gui", "fonts", self.big_font, {key = "system_font_BIG"})
end

go.set_parent

void go.set_parent(stringhashurl [id], stringhashurl [parent_id], boolean [keep_world_transform])

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. This function will generate a set_parent message. It is not until the message has been processed that the change actually takes effect. This typically happens later in the same frame or the beginning of the next frame. Refer to the manual to learn how messages are processed by the engine.

PARAMETERS

string [id] optional id of the game object instance to set parent for, defaults to the instance containing the calling scripthash [id] optional id of the game object instance to set parent for, defaults to the instance containing the calling scripturl [id] optional id of the game object instance to set parent for, defaults to the instance containing the calling script
string [parent_id] optional id of the new parent game object, defaults to detaching game object from its parenthash [parent_id] optional id of the new parent game object, defaults to detaching game object from its parenturl [parent_id] optional id of the new parent game object, defaults to detaching game object from its parent
boolean [keep_world_transform] optional boolean, set to true to maintain the world transform when changing spaces. Defaults to false.

EXAMPLES

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"))

go.set_position

void go.set_position(vector3 position, stringhashurl [id])

The position is relative to the parent (if any). The global world position cannot be manually set.

PARAMETERS

vector3 position position to set
string [id] optional id of the game object instance to set the position for, by default the instance of the calling scripthash [id] optional id of the game object instance to set the position for, by default the instance of the calling scripturl [id] optional id of the game object instance to set the position for, by default the instance of the calling script

EXAMPLES

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")

go.set_rotation

void go.set_rotation(quaternion rotation, stringhashurl [id])

The rotation is relative to the parent (if any). The global world rotation cannot be manually set.

PARAMETERS

quaternion rotation rotation to set
string [id] optional id of the game object instance to get the rotation for, by default the instance of the calling scripthash [id] optional id of the game object instance to get the rotation for, by default the instance of the calling scripturl [id] optional id of the game object instance to get the rotation for, by default the instance of the calling script

EXAMPLES

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")

go.set_scale

void go.set_scale(numbervector3 scale, stringhashurl [id])

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.

PARAMETERS

number scale vector or uniform scale factor, must be greater than 0vector3 scale vector or uniform scale factor, must be greater than 0
string [id] optional id of the game object instance to get the scale for, by default the instance of the calling scripthash [id] optional id of the game object instance to get the scale for, by default the instance of the calling scripturl [id] optional id of the game object instance to get the scale for, by default the instance of the calling script

EXAMPLES

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")

go.world_to_local_position

vector3 go.world_to_local_position(vector3 position, stringhashurl url)

The function uses world transformation calculated at the end of previous frame.

PARAMETERS

vector3 position position which need to be converted
string url url of the game object which coordinate system convert tohash url url of the game object which coordinate system convert tourl url url of the game object which coordinate system convert to

RETURNS

vector3 converted position

EXAMPLES

Convert position of "test" game object into coordinate space of "child" object.
  local test_pos = go.get_world_position("/test")
  local child_pos = go.get_world_position("/child")
  local new_position = go.world_to_local_position(test_pos, "/child")

go.world_to_local_transform

matrix4 go.world_to_local_transform(matrix4 transformation, stringhashurl url)

The function uses world transformation calculated at the end of previous frame.

PARAMETERS

matrix4 transformation transformation which need to be converted
string url url of the game object which coordinate system convert tohash url url of the game object which coordinate system convert tourl url url of the game object which coordinate system convert to

RETURNS

matrix4 converted transformation

EXAMPLES

Convert transformation of "test" game object into coordinate space of "child" object.
   local test_transform = go.get_world_transform("/test")
   local child_transform = go.get_world_transform("/child")
   local result_transform = go.world_to_local_transform(test_transform, "/child")

init

void init(object self)

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.

PARAMETERS

object self reference to the script state to be used for storing data

EXAMPLES

function init(self)
    -- set up useful data
    self.my_value = 1
end

on_input

nil on_input(object self, hash action_id, table action)

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).

PARAMETERS

object self reference to the script state to be used for storing data
hash action_id id of the received input action, as mapped in the input_binding-file
table action a table containing the input data, see above for a description

RETURNS

boolean optional boolean to signal if the input should be consumed (not passed on to others) or not, default is false
nil optional boolean to signal if the input should be consumed (not passed on to others) or not, default is false

EXAMPLES

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

on_message

void on_message(object self, hash message_id, table message, url sender)

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.

PARAMETERS

object self reference to the script state to be used for storing data
hash message_id id of the received message
table message a table containing the message data
url sender address of the sender

EXAMPLES

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

on_reload

void on_reload(object self)

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.

PARAMETERS

object self reference to the script state to be used for storing data

EXAMPLES

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

update

void update(object self, number dt)

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.

PARAMETERS

object self reference to the script state to be used for storing data
number dt the time-step of the frame update

EXAMPLES

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

Constants

go.EASING_INBACK

in-back


go.EASING_INBOUNCE

in-bounce


go.EASING_INCIRC

in-circlic


go.EASING_INCUBIC

in-cubic


go.EASING_INELASTIC

in-elastic


go.EASING_INEXPO

in-exponential


go.EASING_INOUTBACK

in-out-back


go.EASING_INOUTBOUNCE

in-out-bounce


go.EASING_INOUTCIRC

in-out-circlic


go.EASING_INOUTCUBIC

in-out-cubic


go.EASING_INOUTELASTIC

in-out-elastic


go.EASING_INOUTEXPO

in-out-exponential


go.EASING_INOUTQUAD

in-out-quadratic


go.EASING_INOUTQUART

in-out-quartic


go.EASING_INOUTQUINT

in-out-quintic


go.EASING_INOUTSINE

in-out-sine


go.EASING_INQUAD

in-quadratic


go.EASING_INQUART

in-quartic


go.EASING_INQUINT

in-quintic


go.EASING_INSINE

in-sine


go.EASING_LINEAR

linear interpolation


go.EASING_OUTBACK

out-back


go.EASING_OUTBOUNCE

out-bounce


go.EASING_OUTCIRC

out-circlic


go.EASING_OUTCUBIC

out-cubic


go.EASING_OUTELASTIC

out-elastic


go.EASING_OUTEXPO

out-exponential


go.EASING_OUTINBACK

out-in-back


go.EASING_OUTINBOUNCE

out-in-bounce


go.EASING_OUTINCIRC

out-in-circlic


go.EASING_OUTINCUBIC

out-in-cubic


go.EASING_OUTINELASTIC

out-in-elastic


go.EASING_OUTINEXPO

out-in-exponential


go.EASING_OUTINQUAD

out-in-quadratic


go.EASING_OUTINQUART

out-in-quartic


go.EASING_OUTINQUINT

out-in-quintic


go.EASING_OUTINSINE

out-in-sine


go.EASING_OUTQUAD

out-quadratic


go.EASING_OUTQUART

out-quartic


go.EASING_OUTQUINT

out-quintic


go.EASING_OUTSINE

out-sine


go.PLAYBACK_LOOP_BACKWARD

loop backward


go.PLAYBACK_LOOP_FORWARD

loop forward


go.PLAYBACK_LOOP_PINGPONG

ping pong loop


go.PLAYBACK_NONE

no playback


go.PLAYBACK_ONCE_BACKWARD

once backward


go.PLAYBACK_ONCE_FORWARD

once forward


go.PLAYBACK_ONCE_PINGPONG

once ping pong


Messages

acquire_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.

EXAMPLES

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

disable

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:

  • Camera
  • Collection Proxy
  • Collision Object
  • Gui
  • Label
  • Spine Model
  • Sprite
  • Tile Grid
  • Model
  • Mesh

EXAMPLES

Disable the component "my_component":
msg.post("#my_component", "disable")

enable

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:

  • Camera
  • Collection Proxy
  • Collision Object
  • Gui
  • Label
  • Spine Model
  • Sprite
  • Tile Grid
  • Model
  • Mesh

EXAMPLES

Enable the component "my_component":
msg.post("#my_component", "enable")

release_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.

EXAMPLES

How to make a game object stop receiving input:
msg.post(".", "release_input_focus")

set_parent

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 the id of the new parent
keep_world_transform 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.

EXAMPLES

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")

Properties

euler

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.

vector3 game object euler rotation

EXAMPLES

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

position

The position of the game object. The type of the property is vector3.

vector3 game object position

EXAMPLES

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

rotation

The rotation of the game object. The type of the property is quaternion.

quaternion game object rotation

EXAMPLES

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

scale

The uniform scale of the game object. The type of the property is number.

number game object scale

EXAMPLES

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