go

gets a named property of the specified game object or component

// Get a property "speed" from a script "player"; the property must be declared
// in the player script:
go.property("speed", 50);

// Then in the calling script (assumed to belong to the same game object, but it
// does not have to):
const speed = go.get("#player", "speed");

// Get a value in a material property array (the glsl indices are 0-based):
go.get(url, "example", { index: 1 }); // the first vector4 in the array: example[0]
go.get(url, "example", { index: 16 }); // the last vector4 in the array: example[15]
go.get(url, "example.x", { index: 1 }); // an element of a vector4: example[0].x

// Get all values in a material property array as a table:
go.get(url, "example"); // => [vector4, vector4, ...]
go.get(url, "example.x"); // => [number1, number2, ...]

// Get a named property (the resource of a certain gui font):
const font_hash = go.get("#gui", "fonts", { key: "system_font_BIG" });

// Get a property from a sub-component, using the "keys" options table
// (addressing the first level of a component):
go.get("#particlefx", "material", { keys: ["cone_emitter"] });

// Get a property in a deeper sub-hierarchy (if the component supports it).
// Note: no built-in component supports this yet, but a custom one could.
go.get("#my_component", "some_property", { keys: ["root", "child_node"] });

Parameters

• url: string | Hash | Url — url of the game object or component having the property
• property: string | Hash — id of the property to retrieve
• options?: Record<string | number, unknown> — optional options table
• index number index into array property (1 based)
• key hash name of internal property
• keys table array of internal component resources identified by key (e.g. a particle fx emitter, see examples below)

Returns

• value: number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource"> — the value of the specified property

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

// Set a property "speed" of a script "player"; the property must be declared in
// the player script:
go.property("speed", 50);

// Then in the calling script (assumed to belong to the same game object, but it
// does not have to):
go.set("#player", "speed", 100);

// Set a vector4 in a material property array (the glsl indices are 0-based):
go.set(url, "example", vmath.vector4(1, 1, 1, 1), { index: 1 }); // example[0] = v
go.set(url, "example", vmath.vector4(2, 2, 2, 2), { index: 16 }); // example[15] = v
go.set(url, "example.x", 7, { index: 1 }); // example[0].x = 7

// Set a material property array by a table of vector4 (only the first two are
// set; extra array elements are ignored):
go.set(url, "example", [vmath.vector4(1, 1, 1, 1), vmath.vector4(2, 2, 2, 2)]);

// Set a named property (inside init(self)):
go.property("big_font", resource.font());
go.set("#gui", "fonts", self.big_font, { key: "system_font_BIG" });

// Set a property on a sub-component, using the "keys" options table (inside
// init(self)):
go.property("my_material", resource.material);
go.set("#particlefx", "material", self.my_material, { keys: ["cone_emitter"] });

// Set a property in a deeper sub-hierarchy (if the component supports it).
// Note: no built-in component supports this yet, but a custom one could.
go.set("#my_component", "some_property", some_value, { keys: ["root", "child_node"] });

Parameters

• url: string | Hash | Url — url of the game object or component having the property
• property: string | Hash — id of the property to set
• value: number | boolean | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource"> — the value to set
• options?: Record<string | number, unknown> — optional options table
• index integer index into array property (1 based)
• key hash name of internal property
• keys table array of internal component resources identified by key (e.g. a particle fx emitter, see examples below)

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

// Get the position of the game object the script is attached to:
const p = go.get_position();

// Get the position of another game object "my_gameobject":
const pos = go.get_position("my_gameobject");

Parameters

• id?: string | Hash | Url — optional id of the game object instance to get the position for, by default the instance of the calling script

Returns

• position: Vector3 — instance position

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

// Get the rotation of the game object the script is attached to:
const r = go.get_rotation();

// Get the rotation of another game object with id "x":
const r2 = go.get_rotation("x");

Parameters

• id?: string | Hash | Url — optional id of the game object instance to get the rotation for, by default the instance of the calling script

Returns

• rotation: Quaternion — instance rotation

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

// Get the scale of the game object the script is attached to:
const s = go.get_scale();

// Get the scale of another game object with id "x":
const s2 = go.get_scale("x");

Parameters

• id?: string | Hash | Url — optional id of the game object instance to get the scale for, by default the instance of the calling script

Returns

• scale: Vector3 — instance scale factor

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.

// Get the uniform scale of the game object the script is attached to:
const s = go.get_scale_uniform();

// Get the uniform scale of another game object with id "x":
const s2 = go.get_scale_uniform("x");

Parameters

• id?: string | Hash | Url — optional id of the game object instance to get the uniform scale for, by default the instance of the calling script

Returns

• scale: number — uniform instance scale factor

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

// `p` is the desired position (a Vector3).
const p = vmath.vector3();

// Set the position of the game object the script is attached to:
go.set_position(p);

// Reach a sibling game object by its id — relative addressing, no socket prefix:
go.set_position(p, "x");

Parameters

• position: Vector3 — position to set
• id?: string | Hash | Url — optional id of the game object instance to set the position for, by default the instance of the calling script

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

// `r` is the desired rotation (a Quaternion).
const r = vmath.quat();

// Set the rotation of the game object the script is attached to:
go.set_rotation(r);

// Set the rotation of another game object with id "x":
go.set_rotation(r, "x");

Parameters

• rotation: Quaternion — rotation to set
• id?: string | Hash | Url — optional id of the game object instance to get the rotation for, by default the instance of the calling script

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.

// Set the scale of the game object the script is attached to:
const s = vmath.vector3(2.0, 1.0, 1.0);
go.set_scale(s);

// Set the scale of another game object with id "obj_id":
const s2 = 1.2;
go.set_scale(s2, "obj_id");

Parameters

• scale: number | Vector3 — vector or uniform scale factor, must be greater than 0
• id?: string | Hash | Url — optional id of the game object instance to get the scale for, by default the instance of the calling script

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.

// Set the scale of the game object the script is attached to:
const s = vmath.vector3(2.0, 1.0, 5.0);
go.set_scale_xy(s); // z will not be set here, only x and y

// Set the scale of another game object with id "obj_id":
const s2 = 1.2;
go.set_scale_xy(s2, "obj_id"); // z will not be set here, only x and y

Parameters

• scale: number | Vector3 — vector or uniform scale factor, must be greater than 0
• id?: string | Hash | Url — optional id of the game object instance to get the scale for, by default the instance of the calling script

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.

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

Parameters

• id?: string | Hash | Url — optional id of the game object instance to set parent for, defaults to the instance containing the calling script
• parent_id?: string | Hash | Url — optional id of the new parent game object, defaults to detaching game object from its parent
• keep_world_transform?: boolean — optional boolean, set to true to maintain the world transform when changing spaces. Defaults to false.

Get the parent for a game object instance.

// Get parent of the instance containing the calling script:
const parent_id = go.get_parent();

// Get parent of the instance with id "x":
const parent_id2 = go.get_parent("x");

Parameters

• id?: string | Hash | Url — optional id of the game object instance to get parent for, defaults to the instance containing the calling script

Returns

• parent_id: Hash | nil — parent instance or nil

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.

// Get the world position of the game object the script is attached to:
const p = go.get_world_position();

// Reach a sibling game object by its id — relative addressing, no socket prefix:
const p2 = go.get_world_position("x");

Parameters

• id?: string | Hash | Url — optional id of the game object instance to get the world position for, by default the instance of the calling script

Returns

• position: Vector3 — instance world position

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.

// Get the world rotation of the game object the script is attached to:
const r = go.get_world_rotation();

// Get the world rotation of another game object with id "x":
const r2 = go.get_world_rotation("x");

Parameters

• id?: string | Hash | Url — optional id of the game object instance to get the world rotation for, by default the instance of the calling script

Returns

• rotation: Quaternion — instance world rotation

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.

// Get the world 3D scale of the game object the script is attached to:
const s = go.get_world_scale();

// Get the world scale of another game object "x":
const s2 = go.get_world_scale("x");

Parameters

• id?: string | Hash | Url — optional id of the game object instance to get the world scale for, by default the instance of the calling script

Returns

• scale: Vector3 — instance world 3D scale factor

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.

// Get the world uniform scale of the game object the script is attached to:
const s = go.get_world_scale_uniform();

// Get the world uniform scale of another game object with id "x":
const s2 = go.get_world_scale_uniform("x");

Parameters

• id?: string | Hash | Url — optional id of the game object instance to get the world scale for, by default the instance of the calling script

Returns

• scale: number — instance world scale factor

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.

// Get the world transform of the game object the script is attached to:
const m = go.get_world_transform();

// Get the world transform of another game object with id "x":
const m2 = go.get_world_transform("x");

Parameters

• id?: string | Hash | Url — optional id of the game object instance to get the world transform for, by default the instance of the calling script

Returns

• transform: Matrix4 — instance world transform

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.

// Update this game object's world transform:
go.update_world_transform();

// Update another game object's world transform:
go.update_world_transform("/other");

Parameters

• id?: string | Hash | Url — optional id of the game object instance to update

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.

// For the instance with path /my_sub_collection/my_instance, the following calls
// are equivalent:
const id = go.get_id(); // no path, defaults to the instance containing the calling script
print(id); // => hash: [/my_sub_collection/my_instance]

const id2 = go.get_id("/my_sub_collection/my_instance"); // absolute path
print(id2); // => hash: [/my_sub_collection/my_instance]

const id3 = go.get_id("my_instance"); // relative path
print(id3); // => hash: [/my_sub_collection/my_instance]

Parameters

• path?: string — path of the instance for which to return the id

Returns

• id: Hash — instance id

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.

// Animate the position of a game object to x = 10 during 1 second, then
// y = 20 during 1 second:
go.animate(go.get_id(), "position.x", go.PLAYBACK_ONCE_FORWARD, 10, go.EASING_LINEAR, 1, 0, () => {
  go.animate(go.get_id(), "position.y", go.PLAYBACK_ONCE_FORWARD, 20, go.EASING_LINEAR, 1);
});

// Animate the y position of a game object using a crazy custom easing curve:
const 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,
];
const vec = vmath.vector(values);
go.animate("go", "position.y", go.PLAYBACK_LOOP_PINGPONG, 100, vec, 2.0);

Parameters

• url: string | Hash | Url — url of the game object or component having the property

• property: string | Hash — id of the property to animate

• playback: go.PLAYBACK_ONCE_FORWARD | go.PLAYBACK_ONCE_BACKWARD | go.PLAYBACK_ONCE_PINGPONG | go.PLAYBACK_LOOP_FORWARD | go.PLAYBACK_LOOP_BACKWARD | go.PLAYBACK_LOOP_PINGPONG — playback mode of the animation

• go.PLAYBACK_ONCE_FORWARD

• go.PLAYBACK_ONCE_BACKWARD

• go.PLAYBACK_ONCE_PINGPONG

• go.PLAYBACK_LOOP_FORWARD

• go.PLAYBACK_LOOP_BACKWARD

• go.PLAYBACK_LOOP_PINGPONG

• to: number | Vector3 | Vector4 | Quaternion — target property value

• easing: Vector | go.EASING_INBACK | go.EASING_INBOUNCE | go.EASING_INCIRC | go.EASING_INCUBIC | go.EASING_INELASTIC | go.EASING_INEXPO | go.EASING_INOUTBACK | go.EASING_INOUTBOUNCE | go.EASING_INOUTCIRC | go.EASING_INOUTCUBIC | go.EASING_INOUTELASTIC | go.EASING_INOUTEXPO | go.EASING_INOUTQUAD | go.EASING_INOUTQUART | go.EASING_INOUTQUINT | go.EASING_INOUTSINE | go.EASING_INQUAD | go.EASING_INQUART | go.EASING_INQUINT | go.EASING_INSINE | go.EASING_LINEAR | go.EASING_OUTBACK | go.EASING_OUTBOUNCE | go.EASING_OUTCIRC | go.EASING_OUTCUBIC | go.EASING_OUTELASTIC | go.EASING_OUTEXPO | go.EASING_OUTINBACK | go.EASING_OUTINBOUNCE | go.EASING_OUTINCIRC | go.EASING_OUTINCUBIC | go.EASING_OUTINELASTIC | go.EASING_OUTINEXPO | go.EASING_OUTINQUAD | go.EASING_OUTINQUART | go.EASING_OUTINQUINT | go.EASING_OUTINSINE | go.EASING_OUTQUAD | go.EASING_OUTQUART | go.EASING_OUTQUINT | go.EASING_OUTSINE — easing to use during animation. Either specify a constant, see the animation guide for a complete list, or a vmath.vector with a curve

• duration: number — duration of the animation in seconds

• delay?: number — delay before the animation starts in seconds

• complete_function?: function(self, url, property) — optional function to call when the animation has completed

self

object The current object.

url

url The game object or component instance for which the property is animated.

property

hash The id of the animated property.

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.

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

Parameters

• url: string | Hash | Url — url of the game object or component
• property?: string | Hash — optional id of the property to cancel

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

// This example demonstrates how to delete game objects:
// Delete the script's own game object.
go.delete();
// Delete a game object with the id "my_game_object".
const id = go.get_id("my_game_object");
go.delete(id);
// Delete a list of game objects.
const ids = [hash("/my_object_1"), hash("/my_object_2"), hash("/my_object_3")];
go.delete(ids);

// This example demonstrates how to delete game objects and their children
// (child-to-parent order):
// Delete the script's own game object and its children.
go.delete(true);
// Delete a game object with the id "my_game_object" and its children.
const id2 = go.get_id("my_game_object");
go.delete(id2, true);
// Delete a list of game objects and their children.
const ids2 = [hash("/my_object_1"), hash("/my_object_2"), hash("/my_object_3")];
go.delete(ids2, true);

Parameters

• id?: string | Hash | Url | Record<string | number, unknown> — optional id or table of id's of the instance(s) to delete, the instance of the calling script is deleted by default
• recursive?: boolean — optional boolean, set to true to recursively delete child hiearchy in child to parent order

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

// This example defines a property "health" in a script. The health is decreased
// whenever someone sends a "take_damage" message to the script.
go.property("health", 100);

export default defineScript({
  init(self) {
    // prints 100 to the output
    print(self.health);
  },

  on_message(self, message_id, message) {
    if (message_id === hash("take_damage")) {
      self.health = self.health - message.damage;
      print(`Ouch! My health is now: ${self.health}`);
    }
  },
});

Parameters

• name: string — the id of the property
• value: number | Hash | Url | Vector3 | Vector4 | Quaternion | Opaque<"resource"> | boolean — 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.

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

// Check if game object "my_game_object" exists in the current collection:
go.exists("/my_game_object");

// Check if game object exists in another collection:
go.exists("other_collection:/my_game_object");

Parameters

• url: string | Hash | Url — url of the game object to check

Returns

• exists: boolean — true if the game object exists

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

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

Parameters

• position: Vector3 — position which need to be converted
• url: string | Hash | Url — url of the game object which coordinate system convert to

Returns

• converted_postion: Vector3 — converted position

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

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

Parameters

• transformation: Matrix4 — transformation which need to be converted
• url: string | Hash | Url — url of the game object which coordinate system convert to

Returns

• converted_transform: Matrix4 — converted transformation

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.

export default defineScript({
  init() {
    // set up useful data
    return { my_value: 1 };
  },
});

Parameters

• self: Opaque<"userdata"> — reference to the script state to be used for storing data

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

export default defineScript({
  final(self) {
    // report finalization
    msg.post("my_friend_instance", "im_dead", { my_stats: self.some_value });
  },
});

Parameters

• self: Opaque<"userdata"> — reference to the script state to be used for storing data

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.

// This example demonstrates how to move a game object instance through the script component:
export default defineScript({
  init() {
    // set initial velocity to be 1 along world x-axis
    return { my_velocity: vmath.vector3(1, 0, 0) };
  },

  update(self, dt) {
    // move the game object instance
    go.set_position(go.get_position().add(self.my_velocity.mul(dt)));
  },
});

Parameters

• self: Opaque<"userdata"> — reference to the script state to be used for storing data
• dt: number — the time-step of the frame update

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

• self: Opaque<"userdata"> — reference to the script state to be used for storing data
• dt: number — the time-step of the frame update

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

• self: Opaque<"userdata"> — reference to the script state to be used for storing data
• dt: number — the time-step of the frame update

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.

// 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".

// a.script — Script of instance "a":
export default defineScript({
  init() {
    // let b know about some important data
    msg.post("b#script", "my_data", { important_value: 1 });
  },
});

// b.script — Script of instance "b":
export default defineScript({
  init() {
    // store the url of instance "a" for later use, by specifying undefined as socket we
    // automatically use our own socket
    return { a_url: msg.url(undefined, go.get_id("a"), "script") };
  },

  on_message(self, message_id, message, sender) {
    // check message and sender
    if (message_id === hash("my_data") && sender === self.a_url) {
      // use the data in some way
      self.important_value = message.important_value;
    }
  },
});

Parameters

• self: Opaque<"userdata"> — reference to the script state to be used for storing data
• message_id: Hash — id of the received message
• message: Record<string | number, unknown> — a table containing the message data
• sender: Url — address of the sender

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 and text input.

pressed If the input was pressed this frame. This is not present for mouse movement and text input.

released If the input was released this frame. This is not present for mouse movement and text input.

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 and text input.

x The x value of a pointer device, if present. This is not present for gamepad, key and text input.

y The y value of a pointer device, if present. This is not present for gamepad, key and text input.

screen_x The screen space x value of a pointer device, if present. This is not present for gamepad, key and text input.

screen_y The screen space y value of a pointer device, if present. This is not present for gamepad, key and text input.

dx The change in x value of a pointer device, if present. This is not present for gamepad, key and text input.

dy The change in y value of a pointer device, if present. This is not present for gamepad, key and text input.

screen_dx The change in screen space x value of a pointer device, if present. This is not present for gamepad, key and text input.

screen_dy The change in screen space y value of a pointer device, if present. This is not present for gamepad, key and text input.

gamepad The index of the gamepad device that provided the input. See table below about gamepad input.

touch List of touch input, one element per finger, if present. See table below about touch input

text Text input from a (virtual) keyboard or similar.

marked_text Sequence of entered symbols while entering a symbol combination, for example Japanese Kana.

Gamepad specific fields:

Field Description

gamepad The index of the gamepad device that provided the input.

userid Id of the user associated with the controller. Usually only relevant on consoles.

gamepad_unknown True if the inout originated from an unknown/unmapped gamepad.

gamepad_name Name of the gamepad

gamepad_axis List of gamepad axis values. For raw gamepad input only.

gamepadhats List of gamepad hat values. For raw gamepad input only.

gamepad_buttons List of gamepad button values. For raw gamepad input only.

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

// This example demonstrates how a game object instance can be moved as a response to user input.
export default defineScript({
  init() {
    // acquire input focus
    msg.post(".", "acquire_input_focus");
    return {
      // maximum speed the instance can be moved
      max_speed: 2,
      // velocity of the instance, initially zero
      velocity: vmath.vector3(),
    };
  },

  update(self, dt) {
    // move the instance
    go.set_position(go.get_position().add(self.velocity.mul(dt)));
  },

  on_input(self, action_id, action) {
    // check for movement input
    if (action_id === hash("right")) {
      if (action.released) {
        // reset velocity if input was released
        self.velocity = vmath.vector3();
      } else {
        // update velocity
        self.velocity = vmath.vector3(action.value * self.max_speed, 0, 0);
      }
    }
  },
});

Parameters

• self: Opaque<"userdata"> — reference to the script state to be used for storing data
• action_id: Hash — id of the received input action, as mapped in the input_binding-file
• action: Record<string | number, unknown> — a table containing the input data, see above for a description

Returns

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

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.

// This example demonstrates how to tweak the speed of a game object instance that is moved on user input.
export default defineScript({
  init() {
    // acquire input focus
    msg.post(".", "acquire_input_focus");
    return {
      // maximum speed the instance can be moved, this value is tweaked in the on_reload function below
      max_speed: 2,
      // velocity of the instance, initially zero
      velocity: vmath.vector3(),
    };
  },

  update(self, dt) {
    // move the instance
    go.set_position(go.get_position().add(self.velocity.mul(dt)));
  },

  on_input(self, action_id, action) {
    // check for movement input
    if (action_id === hash("right")) {
      if (action.released) {
        // reset velocity if input was released
        self.velocity = vmath.vector3();
      } else {
        // update velocity
        self.velocity = vmath.vector3(action.value * self.max_speed, 0, 0);
      }
    }
  },

  on_reload(self) {
    // edit this value and reload the script component
    self.max_speed = 100;
  },
});

Parameters

• self: Opaque<"userdata"> — reference to the script state to be used for storing data

no playback

once forward

once backward

once ping pong

loop forward

loop backward

ping pong loop

linear interpolation

in-quadratic

out-quadratic

in-out-quadratic

out-in-quadratic

in-cubic

out-cubic

in-out-cubic

out-in-cubic

in-quartic

out-quartic

in-out-quartic

out-in-quartic

in-quintic

out-quintic

in-out-quintic

out-in-quintic

in-sine

out-sine

in-out-sine

out-in-sine

in-exponential

out-exponential

in-out-exponential

out-in-exponential

in-circlic

out-circlic

in-out-circlic

out-in-circlic

in-elastic

out-elastic

in-out-elastic

out-in-elastic

in-back

out-back

in-out-back

out-in-back

in-bounce

out-bounce

in-out-bounce

out-in-bounce

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

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

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.

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