Game object API documentation

go.property_options

Options for accessing indexed or internal component properties with go.get and go.set.

FIELDS

on_input.action

Data supplied to the global on_input lifecycle function.

FIELDS

on_input.gamepad_guid_info

Parsed fields from a connected gamepad guid.

FIELDS

on_input.touch

One touch entry in on_input.action.

FIELDS

go.EASING

go.EASING: integer

Easing curves

VALUES

go.PLAYBACK

go.PLAYBACK: integer

Playback modes

VALUES

final()

final(self:script_instance)

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

EXAMPLES

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

fixed_update()

fixed_update(self:script_instance, dt:number)

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

go.animate()

go.animate(url:string|hash|url, property:string|hash, playback:go.PLAYBACK, to:number|vector3|vector4|quaternion, easing:vector|go.EASING, duration:number, [delay:number], [complete_function:fun(self:script_instance, url:url, property:hash)])

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

EXAMPLES

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

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

go.cancel_animations(url:string|hash|url, [property:string|hash])

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

EXAMPLES

go.cancel_animations(go.get_id(), "position")

go.cancel_animations(".")

go.cancel_animations("#sprite")

go.delete()

go.delete([id:string|hash|url|(string|hash|url)[]], [recursive:boolean])

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

EXAMPLES

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

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

go.exists(url:string|hash|url)→exists:boolean

This function can check for game objects in any collection by specifying the collection name in the URL.

PARAMETERS

RETURNS

EXAMPLES

go.exists("/my_game_object")

go.exists("other_collection:/my_game_object")

go.get()

go.get(url:string|hash|url, property:string|hash, [options:go.property_options])→value:number|boolean|hash|string|url|vector3|vector4|quaternion|resource_data

gets a named property of the specified game object or component

PARAMETERS

RETURNS

EXAMPLES

go.property("speed", 50)

local speed = go.get("#player", "speed")

-- get the first vector4 in the array: example[0] (the glsl indices are 0-based)
go.get(url, "example", {index=1})

-- get the last vector4 in the array: example[15] (the glsl indices are 0-based)
go.get(url, "example", {index=16})

-- get an element of a vector4 in the array: example[0].x (the glsl indices are 0-based)
go.get(url, "example.x", {index=1})

-- get all vector4's in the constant array
go.get(url, "example")
-- result: { vector4, vector4, ... }

-- get all elements of the vector4's from an array
go.get(url, "example.x")
-- result: { number1, number2, ... }

-- get the resource of a certain gui font
local font_hash = go.get("#gui", "fonts", {key = "system_font_BIG"})

-- Addressing the first level of a component:
go.get("#particlefx", "material", { keys = { "cone_emitter" } })

-- Note: There is currently no component that supports this, but a custom component could.
go.get("#my_component", "some_property", { keys = { "root", "child_node" } })

go.get_id()

go.get_id([path:string])→id:hash

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

RETURNS

EXAMPLES

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

go.get_parent([id:string|hash|url])→parent_id:hash|nil

Get the parent for a game object instance.

PARAMETERS

RETURNS

EXAMPLES

local parent_id = go.get_parent()

local parent_id = go.get_parent("x")

go.get_position()

go.get_position([id:string|hash|url])→position:vector3

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

PARAMETERS

RETURNS

EXAMPLES

local p = go.get_position()

local pos = go.get_position("my_gameobject")

go.get_rotation()

go.get_rotation([id:string|hash|url])→rotation:quaternion

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

PARAMETERS

RETURNS

EXAMPLES

local r = go.get_rotation()

local r = go.get_rotation("x")

go.get_scale()

go.get_scale([id:string|hash|url])→scale:vector3

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

PARAMETERS

RETURNS

EXAMPLES

local s = go.get_scale()

local s = go.get_scale("x")

go.get_scale_uniform()

go.get_scale_uniform([id:string|hash|url])→scale:number

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

RETURNS

EXAMPLES

local s = go.get_scale_uniform()

local s = go.get_scale_uniform("x")

go.get_world_position()

go.get_world_position([id:string|hash|url])→position:vector3

The function will return the world position calculated at the end of the previous frame. To recalculate it within the current frame, use go.update_world_transform on the instance before calling this. Use go.get_position to retrieve the position relative to the parent.

PARAMETERS

RETURNS

EXAMPLES

local p = go.get_world_position()

local p = go.get_world_position("x")

go.get_world_rotation()

go.get_world_rotation([id:string|hash|url])→rotation:quaternion

The function will return the world rotation calculated at the end of the previous frame. To recalculate it within the current frame, use go.update_world_transform on the instance before calling this. Use go.get_rotation to retrieve the rotation relative to the parent.

PARAMETERS

RETURNS

EXAMPLES

local r = go.get_world_rotation()

local r = go.get_world_rotation("x")

go.get_world_scale()

go.get_world_scale([id:string|hash|url])→scale:vector3

The function will return the world 3D scale factor calculated at the end of the previous frame. To recalculate it within the current frame, use go.update_world_transform on the instance before calling this. 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

RETURNS

EXAMPLES

local s = go.get_world_scale()

local s = go.get_world_scale("x")

go.get_world_scale_uniform()

go.get_world_scale_uniform([id:string|hash|url])→scale:number

The function will return the world scale factor calculated at the end of the previous frame. To recalculate it within the current frame, use go.update_world_transform on the instance before calling this. Use go.get_scale_uniform to retrieve the scale factor relative to the parent.

PARAMETERS

RETURNS

EXAMPLES

local s = go.get_world_scale_uniform()

local s = go.get_world_scale_uniform("x")

go.get_world_transform()

go.get_world_transform([id:string|hash|url])→transform:matrix4

The function will return the world transform matrix calculated at the end of the previous frame. To recalculate it within the current frame, use go.update_world_transform on the instance before calling this.

PARAMETERS

RETURNS

EXAMPLES

local m = go.get_world_transform()

local m = go.get_world_transform("x")

go.property()

go.property(name:string, value:number|hash|string|url|vector3|vector4|quaternion|resource_data|boolean)

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

EXAMPLES

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.property("player_name", "Player One")
go.property("dialogue", "First line\nSecond line")

go.set()

go.set(url:string|hash|url, property:string|hash, value:number|boolean|hash|string|url|vector3|vector4|quaternion|resource_data, [options:go.property_options])

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

PARAMETERS

EXAMPLES

go.property("speed", 50)

go.set("#player", "speed", 100)

-- set the first vector4 in the array: example[0] = v (the glsl indices are 0-based)
go.set(url, "example", vmath.vector4(1,1,1,1), {index=1})

-- set the last vector4 in the array: example[15] = v (the glsl indices are 0-based)
go.set(url, "example", vmath.vector4(2,2,2,2), {index=16})

-- set an element of a vector4 in the array: example[0].x = 7 (the glsl indices are 0-based)
go.set(url, "example.x", 7, {index=1})

-- set the first two vector4's in the array
-- if the array has more than two elements in the array they will not be set
go.set(url, "example", { vmath.vector4(1,1,1,1), vmath.vector4(2,2,2,2) })

go.property("big_font", resource.font())

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

go.property("my_material", resource.material)
function init(self)
    go.set("#particlefx", "material", self.my_material, { keys = { "cone_emitter" } })
end

-- Note: There is currently no component that supports this, but a custom component could.
go.set("#my_component", "some_property", some_value, { keys = { "root", "child_node" } })

go.set_parent()

go.set_parent([id:string|hash|url], [parent_id:string|hash|url], [keep_world_transform:boolean])

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

EXAMPLES

go.set_parent(go.get_id(),go.get_id("my_parent"))

go.set_parent(go.get_id("my_instance"),go.get_id("my_parent"))

go.set_parent(go.get_id("my_instance"))

go.set_position()

go.set_position(position:vector3, [id:string|hash|url])

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

PARAMETERS

EXAMPLES

local p = ...
go.set_position(p)

local p = ...
go.set_position(p, "x")

go.set_rotation()

go.set_rotation(rotation:quaternion, [id:string|hash|url])

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

PARAMETERS

EXAMPLES

local r = ...
go.set_rotation(r)

local r = ...
go.set_rotation(r, "x")

go.set_scale()

go.set_scale(scale:number|vector3, [id:string|hash|url])

The scale factor is relative to the parent (if any). The global world scale factor cannot be manually set. See manual to know how physics affected when setting scale from this function.

PARAMETERS

EXAMPLES

local s = vmath.vector3(2.0, 1.0, 1.0)
go.set_scale(s)

local s = 1.2
go.set_scale(s, "obj_id")

go.set_scale_xy()

go.set_scale_xy(scale:number|vector3, [id:string|hash|url])

The scale factor is relative to the parent (if any). The global world scale factor cannot be manually set. See manual to know how physics affected when setting scale from this function.

PARAMETERS

EXAMPLES

local s = vmath.vector3(2.0, 1.0, 5.0)
go.set_scale_xy(s) -- z will not be set here, only x and y

local s = 1.2
go.set_scale_xy(s, "obj_id") -- z will not be set here, only x and y

go.update_world_transform()

go.update_world_transform([id:string|hash|url])

Recalculates and updates the cached world transform immediately for the target instance and its ancestors (parent chain up to the collection root). Descendants (children) are not updated by this function. If no id is provided, the instance of the calling script is used. Use this after changing local transform mid-frame when you need the new world transform right away (e.g. before end-of-frame updates). Note that child instances will still have last-frame world transforms until the regular update.

PARAMETERS

EXAMPLES

go.update_world_transform()

go.update_world_transform("/other")

go.world_to_local_position()

go.world_to_local_position(position:vector3, url:string|hash|url)→converted_postion:vector3

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

PARAMETERS

RETURNS

EXAMPLES

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

go.world_to_local_transform(transformation:matrix4, url:string|hash|url)→converted_transform:matrix4

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

PARAMETERS

RETURNS

EXAMPLES

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

init(self:script_instance)

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

EXAMPLES

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

late_update()

late_update(self:script_instance, dt:number)

This is a callback-function, which is called by the engine at the end of the frame to update the state of a script component. Use it to make final adjustments to the game object instance.

PARAMETERS

on_input()

on_input(self:script_instance, action_id:hash|nil, action:on_input.action)→consume:boolean|nil

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.

PARAMETERS

RETURNS

EXAMPLES

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

on_message(self:script_instance, message_id:hash, message:table<any, any>, sender:url)

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

EXAMPLES

function init(self)
    -- let b know about some important data
    msg.post("b#script", "my_data", {important_value = 1})
end

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

on_reload(self:script_instance)

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

EXAMPLES

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

update(self:script_instance, dt:number)

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

EXAMPLES

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

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

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

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

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

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.

EXAMPLES

msg.post(".", "set_parent", {parent_id = go.get_id("my_parent")})

msg.post("my_instance", "set_parent", {parent_id = go.get_id("my_parent")})

msg.post("my_instance", "set_parent")

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.

EXAMPLES

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.

EXAMPLES

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.

EXAMPLES

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.

EXAMPLES

function init(self)
  -- Double the scaling on "player"
  local scale = go.get("player", "scale")
  go.set("player", "scale", scale * 2)
end