Version: stable
FUNCTION | |
---|---|
go.get() | gets a named property of the specified game object or component |
go.set() | sets a named property of the specified game object or component, or a material constant |
go.get_position() | gets the position of a game object instance |
go.get_rotation() | gets the rotation of the game object instance |
go.get_scale() | gets the 3D scale factor of the game object instance |
go.get_scale_uniform() | gets the uniform scale factor of the game object instance |
go.set_position() | sets the position of the game object instance |
go.set_rotation() | sets the rotation of the game object instance |
go.set_scale() | sets the scale factor of the game object instance |
go.set_parent() | sets the parent for a specific game object instance |
go.get_parent() | get the parent for a specific game object instance |
go.get_world_position() | gets the game object instance world position |
go.get_world_rotation() | gets the game object instance world rotation |
go.get_world_scale() | gets the game object instance world 3D scale factor |
go.get_world_scale_uniform() | gets the uniform game object instance world scale factor |
go.get_world_transform() | gets the game object instance world transform matrix |
go.get_id() | gets the id of an instance |
go.animate() | animates a named property of the specified game object or component |
go.cancel_animations() | cancels all animations of the named property of the specified game object or component |
go.delete() | delete one or more game object instances |
go.property() | define a property for the script |
init() | called when a script component is initialized |
final() | called when a script component is finalized |
update() | called every frame to update the script component |
on_message() | called when a message has been sent to the script component |
on_input() | called when user input is received |
on_reload() | called when the script component is reloaded |
MESSAGE | |
---|---|
acquire_input_focus | acquires the user input focus |
release_input_focus | releases the user input focus |
set_parent | sets the parent of the receiving instance |
enable | enables the receiving component |
disable | disables the receiving component |
PROPERTIES | |
---|---|
position | vector3 game object position |
rotation | quaternion game object rotation |
euler | vector3 game object euler rotation |
scale | number game object scale |
go.get(url,property)
PARAMETERS
url |
url of the game object or component having the property |
property |
id of the property to retrieve |
RETURNS
value |
the value of the specified property |
EXAMPLES
Get a property "speed" from a script "player", the property must be declared in the player-script:go.property("speed", 50)
local speed = go.get("#player", "speed")
go.set(url,property,value)
PARAMETERS
url |
url of the game object or component having the property |
property |
id of the property to set |
value |
the value to set |
EXAMPLES
Set a property "speed" of a script "player", the property must be declared in the player-script:go.property("speed", 50)
go.set("#player", "speed", 100)
go.get_position([id])
PARAMETERS
[id] |
optional id of the game object instance to get the position for, by default the instance of the calling script |
RETURNS
position |
instance position |
EXAMPLES
Get the position of the game object instance the script is attached to:local p = go.get_position()
local pos = go.get_position("my_gameobject")
go.get_rotation([id])
PARAMETERS
[id] |
optional id of the game object instance to get the rotation for, by default the instance of the calling script |
RETURNS
rotation |
instance rotation |
EXAMPLES
Get the rotation of the game object instance the script is attached to:local r = go.get_rotation()
local r = go.get_rotation("x")
go.get_scale([id])
PARAMETERS
[id] |
optional id of the game object instance to get the scale for, by default the instance of the calling script |
RETURNS
scale |
instance scale factor |
EXAMPLES
Get the scale of the game object instance the script is attached to:local s = go.get_scale()
local s = go.get_scale("x")
go.get_scale_uniform([id])
PARAMETERS
[id] |
optional id of the game object instance to get the uniform scale for, by default the instance of the calling script |
RETURNS
scale |
uniform instance scale factor |
EXAMPLES
Get the scale of the game object instance the script is attached to:local s = go.get_scale_uniform()
local s = go.get_scale_uniform("x")
go.set_position(position,[id])
PARAMETERS
position |
position to set |
[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)
local p = ... go.set_position(p, "x")
go.set_rotation(rotation,[id])
PARAMETERS
rotation |
rotation to set |
[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)
local r = ... go.set_rotation(r, "x")
go.set_scale(scale,[id])
PARAMETERS
scale |
vector or uniform scale factor, must be greater than 0 |
[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)
local s = 1.2 go.set_scale(s, "x")
go.set_parent([id],[parent_id],[keep_world_transform])
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
[id] |
optional id of the game object instance to set parent for, defaults to the instance containing the calling script |
[parent_id] |
optional id of the new parent game object, defaults to detaching game object from its parent |
[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"))
go.set_parent(go.get_id("my_instance"),go.get_id("my_parent"))
go.set_parent(go.get_id("my_instance"))
go.get_parent([id])
PARAMETERS
[id] |
optional id of the game object instance to get parent for, defaults to the instance containing the calling script |
RETURNS
parent_id |
parent instance or nil |
EXAMPLES
Get parent of the instance containing the calling script:local parent_id = go.get_parent()
local parent_id = go.get_parent("x")
go.get_world_position([id])
PARAMETERS
[id] |
optional id of the game object instance to get the world position for, by default the instance of the calling script |
RETURNS
position |
instance world position |
EXAMPLES
Get the world position of the game object instance the script is attached to:local p = go.get_world_position()
local p = go.get_world_position("x")
go.get_world_rotation([id])
go.get_rotation
to retrieve the rotation relative to the parent.
PARAMETERS
[id] |
optional id of the game object instance to get the world rotation for, by default the instance of the calling script |
RETURNS
rotation |
instance world rotation |
EXAMPLES
Get the world rotation of the game object instance the script is attached to:local r = go.get_world_rotation()
local r = go.get_world_rotation("x")
go.get_world_scale([id])
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
[id] |
optional id of the game object instance to get the world scale for, by default the instance of the calling script |
RETURNS
scale |
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()
local s = go.get_world_scale("x")
go.get_world_scale_uniform([id])
go.get_scale_uniform
to retrieve the scale factor relative to the parent.
PARAMETERS
[id] |
optional id of the game object instance to get the world scale for, by default the instance of the calling script |
RETURNS
scale |
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()
local s = go.get_world_scale_uniform("x")
go.get_world_transform([id])
PARAMETERS
[id] |
optional id of the game object instance to get the world transform for, by default the instance of the calling script |
RETURNS
transform |
instance world transform |
EXAMPLES
Get the world transform of the game object instance the script is attached to:local m = go.get_world_transform()
local m = go.get_world_transform("x")
go.get_id([path])
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.PARAMETERS
[path] |
path of the instance for which to return the id |
RETURNS
id |
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.animate(url,property,playback,to,easing,duration,[delay],[complete_function])
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.
PARAMETERS
url |
url of the game object or component having the property |
property |
id of the property to animate |
playback |
playback mode of the animation
|
to |
target property value |
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 |
duration |
duration of the animation in seconds |
[delay] |
delay before the animation starts in seconds |
[complete_function] |
optional function to call when the animation has completed
|
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
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(url,property)
PARAMETERS
url |
url of the game object or component having the property |
property |
ide of the property to animate |
EXAMPLES
Cancel the animation of the position of a game object:go.cancel_animations(go.get_id(), "position")
go.delete([id],[recursive])
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
[id] |
optional id or table of id's of the instance(s) to delete, the instance of the calling script is deleted by default |
[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)
-- 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.property(name,value)
PARAMETERS
name |
the id of the property |
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
init(self)
PARAMETERS
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
final(self)
PARAMETERS
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
update(self,dt)
PARAMETERS
self |
reference to the script state to be used for storing data |
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
on_message(self,message_id,message,sender)
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
self |
reference to the script state to be used for storing data |
message_id |
id of the received message |
message |
a table containing the message data |
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
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_input(self,action_id,action)
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 |
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
self |
reference to the script state to be used for storing data |
action_id |
id of the received input action, as mapped in the input_binding-file |
action |
a table containing the input data, see above for a description |
RETURNS
[consume] |
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_reload(self)
PARAMETERS
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
no playback
no playback
once forward
once forward
once backward
once backward
once ping pong
once ping pong
loop forward
loop forward
loop backward
loop backward
ping pong loop
ping pong loop
linear interpolation
linear interpolation
in-quadratic
in-quadratic
out-quadratic
out-quadratic
in-out-quadratic
in-out-quadratic
out-in-quadratic
out-in-quadratic
in-cubic
in-cubic
out-cubic
out-cubic
in-out-cubic
in-out-cubic
out-in-cubic
out-in-cubic
in-quartic
in-quartic
out-quartic
out-quartic
in-out-quartic
in-out-quartic
out-in-quartic
out-in-quartic
in-quintic
in-quintic
out-quintic
out-quintic
in-out-quintic
in-out-quintic
out-in-quintic
out-in-quintic
in-sine
in-sine
out-sine
out-sine
in-out-sine
in-out-sine
out-in-sine
out-in-sine
in-exponential
in-exponential
out-exponential
out-exponential
in-out-exponential
in-out-exponential
out-in-exponential
out-in-exponential
in-circlic
in-circlic
out-circlic
out-circlic
in-out-circlic
in-out-circlic
out-in-circlic
out-in-circlic
in-elastic
in-elastic
out-elastic
out-elastic
in-out-elastic
in-out-elastic
out-in-elastic
out-in-elastic
in-back
in-back
out-back
out-back
in-out-back
in-out-back
out-in-back
out-in-back
in-bounce
in-bounce
out-bounce
out-bounce
in-out-bounce
in-out-bounce
out-in-bounce
out-in-bounce
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.
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
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.
EXAMPLES
How to make a game object stop receiving input:msg.post(".", "release_input_focus")
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 |
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")})
msg.post("my_instance", "set_parent", {parent_id = go.get_id("my_parent")})
msg.post("my_instance", "set_parent")
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:
EXAMPLES
Enable the component "my_component":msg.post("#my_component", "enable")
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:
EXAMPLES
Disable the component "my_component":msg.post("#my_component", "disable")
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
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
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
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