gui

Retrieves the node with the specified id.

// Gets a node by id and change its color:
const node = gui.get_node("my_node");
const red = vmath.vector4(1.0, 0.0, 0.0, 1.0);
gui.set_color(node, red);

Parameters

• id: string | Hash — id of the node to retrieve

Returns

• instance: Opaque<"node"> — a new node instance

Retrieves the id of the specified node.

// Gets the id of a node:
const node = gui.get_node("my_node");

const id = gui.get_id(node);
print(id); // => hash: [my_node]

Parameters

• node: Opaque<"node"> — the node to retrieve the id from

Returns

• id: Hash — the id of the node

gets the node type

Parameters

• node: Opaque<"node"> — node from which to get the type

Returns

• type: Opaque<"constant"> — type

• gui.TYPE_BOX

• gui.TYPE_TEXT

• gui.TYPE_PIE

• gui.TYPE_PARTICLEFX

• gui.TYPE_CUSTOM

• subtype: number | nil — id of the custom type

Set the id of the specicied node to a new value. Nodes created with the gui.new_*_node() functions get an empty id. This function allows you to give dynamically created nodes an id. No checking is done on the uniqueness of supplied ids. It is up to you to make sure you use unique ids.

// Create a new node and set its id:
const pos = vmath.vector3(100, 100, 0);
const size = vmath.vector3(100, 100, 0);
const node = gui.new_box_node(pos, size);
gui.set_id(node, "my_new_node");

Parameters

• node: Opaque<"node"> — node to set the id for
• id: string | Hash — id to set

Instead of using specific getters such as gui.get_position or gui.get_scale, you can use gui.get instead and supply the property as a string or a hash. While this function is similar to go.get, there are a few more restrictions when operating in the gui namespace. Most notably, only these explicitly named properties are supported:

• "position"

• "rotation"

• "euler"

• "scale"

• "color"

• "outline"

• "shadow"

• "size"

• "fill_angle" (pie)

• "inner_radius" (pie)

• "leading" (text)

• "tracking" (text)

• "slice9" (slice9)

The value returned will either be a vmath.vector4 or a single number, i.e getting the "position" property will return a vec4 while getting the "position.x" property will return a single value. You can also use this function to get material constants.

// Get properties on existing nodes:
const node = gui.get_node("my_box_node");
const node_position = gui.get(node, "position");

Parameters

• node: Opaque<"node"> — node to get the property for
• property: string | Hash | Opaque<"constant"> — the property to retrieve
• options?: Record<string | number, unknown> — optional options table (only applicable for material constants)
• index number index into array property (1 based)

Instead of using specific setteres such as gui.set_position or gui.set_scale, you can use gui.set instead and supply the property as a string or a hash. While this function is similar to go.get and go.set, there are a few more restrictions when operating in the gui namespace. Most notably, only these named properties identifiers are supported:

• "position"

• "rotation"

• "euler"

• "scale"

• "color"

• "outline"

• "shadow"

• "size"

• "fill_angle" (pie)

• "inner_radius" (pie)

• "leading" (text)

• "tracking" (text)

• "slice9" (slice9)

The value to set must either be a vmath.vector4, vmath.vector3, vmath.quat or a single number and depends on the property name you want to set. I.e when setting the "position" property, you need to use a vmath.vector4 and when setting a single component of the property, such as "position.x", you need to use a single value. Note: When setting the rotation using the "rotation" property, you need to pass in a vmath.quat. This behaviour is different than from the gui.set_rotation function, the intention is to move new functionality closer to go namespace so that migrating between gui and go is easier. To set the rotation using degrees instead, use the "euler" property instead. The rotation and euler properties are linked, changing one of them will change the backing data of the other. Similar to go.set, you can also use gui.set for setting material constant values on a node. E.g if a material has specified a constant called tint in the .material file, you can use gui.set to set the value of that constant by calling gui.set(node, "tint", vmath.vec4(1,0,0,1)), or gui.set(node, "matrix", vmath.matrix4()) if the constant is a matrix. Arrays are also supported by gui.set - to set an array constant, you need to pass in an options table with the 'index' key set. If the material has a constant array called 'tint_array' specified in the material, you can use gui.set(node, "tint_array", vmath.vec4(1,0,0,1), { index = 4}) to set the fourth array element to a different value.

// Updates the position property on an existing node:
const node = gui.get_node("my_box_node");
const node_position = gui.get(node, "position");
gui.set(node, "position.x", node_position.x + 128);

// Updates the rotation property on an existing node:
gui.set(node, "rotation", vmath.quat_rotation_z(math.rad(45)));
// this is equivalent to:
gui.set(node, "euler.z", 45);
// or using the entire vector:
gui.set(node, "euler", vmath.vector3(0, 0, 45));
// or using the set_rotation
gui.set_rotation(node, vmath.vector3(0, 0, 45));

// Sets various material constants for a node:
gui.set(node, "tint", vmath.vector4(1, 0, 0, 1));
// matrix4 is also supported
gui.set(node, "light_matrix", vmath.matrix4());
// update a constant in an array at position 4. the array is specified in the shader as:
// uniform vec4 tint_array[4]; // lua is 1 based, shader is 0 based
gui.set(node, "tint_array", vmath.vector4(1, 0, 0, 1), { index: 4 });
// update a matrix constant in an array at position 4. the array is specified in the shader as:
// uniform mat4 light_matrix_array[4];
gui.set(node, "light_matrix_array", vmath.matrix4(), { index: 4 });
// update a sub-element in a constant
gui.set(node, "tint.x", 1);
// update a sub-element in an array constant at position 4
gui.set(node, "tint_array.x", 1, { index: 4 });

// Set a named property
export default defineScript({
  on_message(self, message_id, message) {
    if (message_id === hash("set_font")) {
      gui.set(msg.url(), "fonts", message.font, { key: "my_font_name" });
      gui.set_font(gui.get_node("text"), "my_font_name");
    } else if (message_id === hash("set_texture")) {
      gui.set(msg.url(), "textures", message.texture, { key: "my_texture" });
      gui.set_texture(gui.get_node("box"), "my_texture");
      gui.play_flipbook(gui.get_node("box"), "logo_256");
    }
  },
});

Parameters

• node: Opaque<"node"> | Url — node to set the property for, or msg.url() to the gui itself
• property: string | Hash | Opaque<"constant"> — the property to set
• value: number | Vector4 | Vector3 | Quaternion — the property to set
• options?: Record<string | number, unknown> — optional options table (only applicable for material constants)
• index number index into array property (1 based)
• key hash name of internal property

Retrieve the index of the specified node among its siblings. The index defines the order in which a node appear in a GUI scene. Higher index means the node is drawn on top of lower indexed nodes.

// Compare the index order of two sibling nodes:
const node1 = gui.get_node("my_node_1");
const node2 = gui.get_node("my_node_2");

if (gui.get_index(node1) < gui.get_index(node2)) {
  // node1 is drawn below node2
} else {
  // node2 is drawn below node1
}

Parameters

• node: Opaque<"node"> — the node to retrieve the id from

Returns

• index: number — the index of the node

Deletes the specified node. Any child nodes of the specified node will be recursively deleted.

// Delete a particular node and any child nodes it might have:
const node = gui.get_node("my_node");
gui.delete_node(node);

Parameters

• node: Opaque<"node"> — node to delete

This starts an animation of a node property according to the specified parameters. If the node property is already being animated, that animation will be canceled and replaced by the new one. Note however that several different node properties can be animated simultaneously. Use gui.cancel_animations to stop the animation before it has completed. Composite properties of type vector3, vector4 or quaternion also expose their sub-components (x, y, z and w). You can address the components individually by suffixing the name with a dot '.' and the name of the component. For instance, "position.x" (the position x coordinate) or "color.w" (the color alpha value). 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 below for more information.

// How to start a simple color animation, where the node fades in to white during 0.5 seconds:
gui.set_color(node, vmath.vector4(0, 0, 0, 0)); // node is fully transparent
gui.animate(node, gui.PROP_COLOR, vmath.vector4(1, 1, 1, 1), gui.EASING_INOUTQUAD, 0.5); // start animation

// How to start a sequenced animation where the node fades in to white during 0.5
// seconds, stays visible for 2 seconds and then fades out:
function on_animation_done(self, node) {
  // fade out node, but wait 2 seconds before the animation starts
  gui.animate(node, gui.PROP_COLOR, vmath.vector4(0, 0, 0, 0), gui.EASING_OUTQUAD, 0.5, 2.0);
}

export default defineScript({
  init(self) {
    // fetch the node we want to animate
    const my_node = gui.get_node("my_node");
    // node is initially set to fully transparent
    gui.set_color(my_node, vmath.vector4(0, 0, 0, 0));
    // animate the node immediately and call on_animation_done when the animation has completed
    gui.animate(my_node, gui.PROP_COLOR, vmath.vector4(1, 1, 1, 1), gui.EASING_INOUTQUAD, 0.5, 0.0, on_animation_done);
  },
});

// How to animate a node's y position using a crazy custom easing curve:
export default defineScript({
  init(self) {
    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);
    const node = gui.get_node("box");
    gui.animate(node, "position.y", 100, vec, 4.0, 0, undefined, gui.PLAYBACK_LOOP_PINGPONG);
  },
});

Parameters

• node: Opaque<"node"> — node to animate

• property: string | Opaque<"constant"> — property to animate

• "position"

• "rotation"

• "euler"

• "scale"

• "color"

• "outline"

• "shadow"

• "size"

• "fill_angle" (pie)

• "inner_radius" (pie)

• "leading" (text)

• "tracking" (text)

• "slice9" (slice9)

The following property constants are defined equaling the corresponding property string names.

• gui.PROP_POSITION

• gui.PROP_ROTATION

• gui.PROP_EULER

• gui.PROP_SCALE

• gui.PROP_COLOR

• gui.PROP_OUTLINE

• gui.PROP_SHADOW

• gui.PROP_SIZE

• gui.PROP_FILL_ANGLE

• gui.PROP_INNER_RADIUS

• gui.PROP_LEADING

• gui.PROP_TRACKING

• gui.PROP_SLICE9

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

• easing: Opaque<"constant"> | Vector — easing to use during animation. Either specify one of the gui.EASING_* constants or provide a vector with a custom curve. See the animation guide for more information.

• duration: number — duration of the animation in seconds.

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

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

• playback?: Opaque<"constant"> — playback mode

• gui.PLAYBACK_ONCE_FORWARD

• gui.PLAYBACK_ONCE_BACKWARD

• gui.PLAYBACK_ONCE_PINGPONG

• gui.PLAYBACK_LOOP_FORWARD

• gui.PLAYBACK_LOOP_BACKWARD

• gui.PLAYBACK_LOOP_PINGPONG

If one or more animations of the specified node is currently running (started by gui.animate), they will immediately be canceled.

// Start an animation of the position property of a node, then cancel parts of
// the animation:
const node = gui.get_node("my_node");
// animate to new position
const pos = vmath.vector3(100, 100, 0);
gui.animate(node, "position", pos, go.EASING_LINEAR, 2);
// ...
// cancel animation of the x component.
gui.cancel_animations(node, "position.x");

// Cancels all property animations on a node in a single call:
// animate to new position and scale
gui.animate(node, "position", vmath.vector3(100, 100, 0), go.EASING_LINEAR, 5);
gui.animate(node, "scale", vmath.vector3(0.5), go.EASING_LINEAR, 5);
// ...
// cancel positioning and scaling at once
gui.cancel_animations(node);

Parameters

• node: Opaque<"node"> — node that should have its animation canceled

• property?: nil | string | Opaque<"constant"> — optional property for which the animation should be canceled

• "position"

• "rotation"

• "euler"

• "scale"

• "color"

• "outline"

• "shadow"

• "size"

• "fill_angle" (pie)

• "inner_radius" (pie)

• "leading" (text)

• "tracking" (text)

• "slice9" (slice9)

Dynamically create a new box node.

Parameters

• pos: Vector3 | Vector4 — node position
• size: Vector3 — node size

Returns

• node: Opaque<"node"> — new box node

Dynamically create a new text node.

Parameters

• pos: Vector3 | Vector4 — node position
• text: string — node text

Returns

• node: Opaque<"node"> — new text node

Dynamically create a new pie node.

Parameters

• pos: Vector3 | Vector4 — node position
• size: Vector3 — node size

Returns

• node: Opaque<"node"> — new pie node

Returns the text value of a text node. This is only useful for text nodes.

Parameters

• node: Opaque<"node"> — node from which to get the text

Returns

• text: string — text value

Set the text value of a text node. This is only useful for text nodes.

Parameters

• node: Opaque<"node"> — node to set text for
• text: string | number — text to set

Returns whether a text node is in line-break mode or not. This is only useful for text nodes.

Parameters

• node: Opaque<"node"> — node from which to get the line-break for

Returns

• line_break: boolean — true or false

Sets the line-break mode on a text node. This is only useful for text nodes.

Parameters

• node: Opaque<"node"> — node to set line-break for
• line_break: boolean — true or false

Returns the blend mode of a node. Blend mode defines how the node will be blended with the background.

Parameters

• node: Opaque<"node"> — node from which to get the blend mode

Returns

• blend_mode: Opaque<"constant"> — blend mode

• gui.BLEND_ALPHA

• gui.BLEND_ADD

• gui.BLEND_ADD_ALPHA

• gui.BLEND_MULT

• gui.BLEND_SCREEN

Set the blend mode of a node. Blend mode defines how the node will be blended with the background.

Parameters

• node: Opaque<"node"> — node to set blend mode for

• blend_mode: Opaque<"constant"> — blend mode to set

• gui.BLEND_ALPHA

• gui.BLEND_ADD

• gui.BLEND_ADD_ALPHA

• gui.BLEND_MULT

• gui.BLEND_SCREEN

Returns the texture of a node. This is currently only useful for box or pie nodes. The texture must be mapped to the gui scene in the gui editor.

Parameters

• node: Opaque<"node"> — node to get texture from

Returns

• texture: Hash — texture id

Set the texture on a box or pie node. The texture must be mapped to the gui scene in the gui editor. The function points out which texture the node should render from. If the texture is an atlas, further information is needed to select which image/animation in the atlas to render. In such cases, use gui.play_flipbook() in addition to this function.

// To set a texture (or animation) from an atlas:
const node = gui.get_node("box_node");
gui.set_texture(node, "my_atlas");
gui.play_flipbook(node, "image");

// Set a dynamically created texture to a node. Note that there is only
// one texture image in this case so gui.set_texture() is sufficient.
const w = 200;
const h = 300;
// A nice orange. String with the RGB values.
const orange = String.fromCharCode(0xff, 0x80, 0x10);
// Create the texture. Repeat the color string for each pixel.
if (gui.new_texture("orange_tx", w, h, "rgb", orange.repeat(w * h))) {
  gui.set_texture(node, "orange_tx");
}

Parameters

• node: Opaque<"node"> — node to set texture for
• texture: string | Hash — texture id

Get node flipbook animation.

Parameters

• node: Opaque<"node"> — node to get flipbook animation from

Returns

• animation: Hash — animation id

Play flipbook animation on a box or pie node. The current node texture must contain the animation. Use this function to set one-frame still images on the node.

// Set the texture of a node to a flipbook animation from an atlas:
function anim_callback(self, node) {
  // Take action after animation has played.
}

export default defineScript({
  init(self) {
    // Create a new node and set the texture to a flipbook animation
    const node = gui.get_node("button_node");
    gui.set_texture(node, "gui_sprites");
    gui.play_flipbook(node, "animated_button");
  },
});

// Set the texture of a node to an image from an atlas:
// Create a new node and set the texture to a "button.png" from atlas
const node = gui.get_node("button_node");
gui.set_texture(node, "gui_sprites");
gui.play_flipbook(node, "button");

Parameters

• node: Opaque<"node"> — node to set animation for
• animation: string | Hash — animation id
• complete_function?: function(self, node) — optional function to call when the animation has completed

self

object The current object.

node

node The node that is animated.

• play_properties?: Record<string | number, unknown> — optional table with properties

offset number The normalized initial value of the animation cursor when the animation starts playing playback_rate number The rate with which the animation will be played. Must be positive

Cancels any running flipbook animation on the specified node.

const node = gui.get_node("anim_node");
gui.cancel_flipbook(node);

Parameters

• node: Opaque<"node"> — node cancel flipbook animation for

Dynamically create a new texture.

// How to create a texture and apply it to a new box node:
export default defineScript({
  init(self) {
    const w = 200;
    const h = 300;

    // A nice orange. String with the RGB values.
    const orange = String.fromCharCode(0xff, 0x80, 0x10);

    // Create the texture. Repeat the color string for each pixel.
    const [ok, reason] = gui.new_texture("orange_tx", w, h, "rgb", orange.repeat(w * h));
    if (ok) {
      // Create a box node and apply the texture to it.
      const n = gui.new_box_node(vmath.vector3(200, 200, 0), vmath.vector3(w, h, 0));
      gui.set_texture(n, "orange_tx");
    } else {
      // Could not create texture for some reason...
      if (reason === gui.RESULT_TEXTURE_ALREADY_EXISTS) {
        // ...
      } else {
        // ...
      }
    }
  },
});

// How to create a texture using .astc format
const path = "/assets/images/logo_4x4.astc";
const buffer = sys.load_resource(path);
const n = gui.new_box_node(pos, vmath.vector3(size, size, 0));
// size is read from the .astc buffer
// flip is not supported
gui.new_texture(path, 0, 0, "astc", buffer, false);
gui.set_texture(n, path);

Parameters

• texture_id: string | Hash — texture id

• width: number — texture width

• height: number — texture height

• type: string | Opaque<"constant"> — texture type

• "rgb" - RGB

• "rgba" - RGBA

• "l" - LUMINANCE

• "astc" - ASTC compressed format

• buffer: string — texture data

• flip: boolean — flip texture vertically

Returns

• success: boolean — texture creation was successful
• code: number — one of the gui.RESULT_* codes if unsuccessful

Delete a dynamically created texture.

export default defineScript({
  init(self) {
    // Create a texture.
    if (gui.new_texture("temp_tx", 10, 10, "rgb", "\0".repeat(10 * 10 * 3))) {
      // Do something with the texture.
      // ...

      // Delete the texture
      gui.delete_texture("temp_tx");
    }
  },
});

Parameters

• texture: string | Hash — texture id

Set the texture buffer data for a dynamically created texture.

export default defineScript({
  init(self) {
    const w = 200;
    const h = 300;

    // Create a dynamic texture, all white.
    if (gui.new_texture("dynamic_tx", w, h, "rgb", String.fromCharCode(0xff).repeat(w * h * 3))) {
      // Create a box node and apply the texture to it.
      const n = gui.new_box_node(vmath.vector3(200, 200, 0), vmath.vector3(w, h, 0));
      gui.set_texture(n, "dynamic_tx");

      // ...

      // Change the data in the texture to a nice orange.
      const orange = String.fromCharCode(0xff, 0x80, 0x10);
      if (gui.set_texture_data("dynamic_tx", w, h, "rgb", orange.repeat(w * h))) {
        // Go on and to more stuff
        // ...
      }
    } else {
      // Something went wrong
      // ...
    }
  },
});

Parameters

• texture: string | Hash — texture id

• width: number — texture width

• height: number — texture height

• type: string | Opaque<"constant"> — texture type

• "rgb" - RGB

• "rgba" - RGBA

• "l" - LUMINANCE

• "astc" - ASTC compressed format

• buffer: string — texture data

• flip: boolean — flip texture vertically

Returns

• success: boolean — setting the data was successful

Returns the material of a node. The material must be mapped to the gui scene in the gui editor.

// Getting the material for a node, and assign it to another node:
const node1 = gui.get_node("my_node");
const node2 = gui.get_node("other_node");
const node1_material = gui.get_material(node1);
gui.set_material(node2, node1_material);

Parameters

• node: Opaque<"node"> — node to get the material for

Returns

• materal: Hash — material id

Set the material on a node. The material must be mapped to the gui scene in the gui editor, and assigning a material is supported for all node types. To set the default material that is assigned to the gui scene node, use gui.reset_material(node_id) instead.

// Assign an existing material to a node:
const node = gui.get_node("my_node");
gui.set_material(node, "my_material");

Parameters

• node: Opaque<"node"> — node to set material for
• material: string | Hash — material id

Resets the node material to the material assigned in the gui scene.

// Resetting the material for a node:
const node = gui.get_node("my_node");
gui.reset_material(node);

Parameters

• node: Opaque<"node"> — node to reset the material for

This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.

Parameters

• node: Opaque<"node"> — node from which to get the font

Returns

• font: Hash — font id

This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.

// Get the text metrics for a text
export default defineScript({
  init(self) {
    const node = gui.get_node("name");
    const font_name = gui.get_font(node);
    const font = gui.get_font_resource(font_name);
    const metrics = resource.get_text_metrics(font, "The quick brown fox\n jumps over the lazy dog");
  },
});

Parameters

• font_name: Hash | string — font of which to get the path hash

Returns

• hash: Hash — path hash to resource

This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.

Parameters

• node: Opaque<"node"> — node for which to set the font
• font: string | Hash — font id

The layer must be mapped to the gui scene in the gui editor.

Parameters

• node: Opaque<"node"> — node from which to get the layer

Returns

• layer: Hash — layer id

The layer must be mapped to the gui scene in the gui editor.

Parameters

• node: Opaque<"node"> — node for which to set the layer
• layer: string | Hash — layer id

gets the scene current layout

Returns

• layout: Hash — layout id

Applies a named layout on the GUI scene. This re-applies per-layout node descriptors and, if a matching Display Profile exists, updates the scene resolution. Emits the "layout_changed" message to the scene script when the layout actually changes.

Parameters

• layout: string | Hash — the layout id to apply

Returns

• boolean — true if the layout exists in the scene and was applied, false otherwise

Returns a table mapping each layout id hash to a vector3(width, height, 0). For the default layout, the current scene resolution is returned. If a layout name is not present in the Display Profiles (or when no display profiles are assigned), the width/height pair is 0.

Returns

• Record<string | number, unknown> — layout_id_hash -> vmath.vector3(width, height, 0)

Clipping mode defines how the node will clip it's children nodes

Parameters

• node: Opaque<"node"> — node from which to get the clipping mode

Returns

• clipping_mode: Opaque<"constant"> — clipping mode

• gui.CLIPPING_MODE_NONE

• gui.CLIPPING_MODE_STENCIL

Clipping mode defines how the node will clip it's children nodes

Parameters

• node: Opaque<"node"> — node to set clipping mode for

• clipping_mode: Opaque<"constant"> — clipping mode to set

• gui.CLIPPING_MODE_NONE

• gui.CLIPPING_MODE_STENCIL

If node is set as visible clipping node, it will be shown as well as clipping. Otherwise, it will only clip but not show visually.

Parameters

• node: Opaque<"node"> — node from which to get the clipping visibility state

Returns

• visible: boolean — true or false

If node is set as an visible clipping node, it will be shown as well as clipping. Otherwise, it will only clip but not show visually.

Parameters

• node: Opaque<"node"> — node to set clipping visibility for
• visible: boolean — true or false

If node is set as an inverted clipping node, it will clip anything inside as opposed to outside.

Parameters

• node: Opaque<"node"> — node from which to get the clipping inverted state

Returns

• inverted: boolean — true or false

If node is set as an inverted clipping node, it will clip anything inside as opposed to outside.

Parameters

• node: Opaque<"node"> — node to set clipping inverted state for
• inverted: boolean — true or false

The x-anchor specifies how the node is moved when the game is run in a different resolution.

Parameters

• node: Opaque<"node"> — node to get x-anchor from

Returns

• anchor: Opaque<"constant"> — anchor constant

• gui.ANCHOR_NONE

• gui.ANCHOR_LEFT

• gui.ANCHOR_RIGHT

The x-anchor specifies how the node is moved when the game is run in a different resolution.

Parameters

• node: Opaque<"node"> — node to set x-anchor for

• anchor: Opaque<"constant"> — anchor constant

• gui.ANCHOR_NONE

• gui.ANCHOR_LEFT

• gui.ANCHOR_RIGHT

The y-anchor specifies how the node is moved when the game is run in a different resolution.

Parameters

• node: Opaque<"node"> — node to get y-anchor from

Returns

• anchor: Opaque<"constant"> — anchor constant

• gui.ANCHOR_NONE

• gui.ANCHOR_TOP

• gui.ANCHOR_BOTTOM

The y-anchor specifies how the node is moved when the game is run in a different resolution.

Parameters

• node: Opaque<"node"> — node to set y-anchor for

• anchor: Opaque<"constant"> — anchor constant

• gui.ANCHOR_NONE

• gui.ANCHOR_TOP

• gui.ANCHOR_BOTTOM

The pivot specifies how the node is drawn and rotated from its position.

Parameters

• node: Opaque<"node"> — node to get pivot from

Returns

• pivot: Opaque<"constant"> — pivot constant

• gui.PIVOT_CENTER

• gui.PIVOT_N

• gui.PIVOT_NE

• gui.PIVOT_E

• gui.PIVOT_SE

• gui.PIVOT_S

• gui.PIVOT_SW

• gui.PIVOT_W

• gui.PIVOT_NW

The pivot specifies how the node is drawn and rotated from its position.

Parameters

• node: Opaque<"node"> — node to set pivot for

• pivot: Opaque<"constant"> — pivot constant

• gui.PIVOT_CENTER

• gui.PIVOT_N

• gui.PIVOT_NE

• gui.PIVOT_E

• gui.PIVOT_SE

• gui.PIVOT_S

• gui.PIVOT_SW

• gui.PIVOT_W

• gui.PIVOT_NW

Returns the scene width.

Returns

• width: number — scene width

Returns the scene height.

Returns

• height: number — scene height

Set the slice9 configuration values for the node.

Parameters

• node: Opaque<"node"> — node to manipulate
• values: Vector4 — new values

Returns the slice9 configuration values for the node.

Parameters

• node: Opaque<"node"> — node to manipulate

Returns

• values: Vector4 — configuration values

Sets the number of generated vertices around the perimeter of a pie node.

Parameters

• node: Opaque<"node"> — pie node
• vertices: number — vertex count

Returns the number of generated vertices around the perimeter of a pie node.

Parameters

• node: Opaque<"node"> — pie node

Returns

• vertices: number — vertex count

Set the sector angle of a pie node.

Parameters

• node: Opaque<"node"> — node to set the fill angle for
• angle: number — sector angle

Returns the sector angle of a pie node.

Parameters

• node: Opaque<"node"> — node from which to get the fill angle

Returns

• angle: number — sector angle

Sets the inner radius of a pie node. The radius is defined along the x-axis.

Parameters

• node: Opaque<"node"> — node to set the inner radius for
• radius: number — inner radius

Returns the inner radius of a pie node. The radius is defined along the x-axis.

Parameters

• node: Opaque<"node"> — node from where to get the inner radius

Returns

• radius: number — inner radius

Sets the outer bounds mode for a pie node.

Parameters

• node: Opaque<"node"> — node for which to set the outer bounds mode

• bounds_mode: Opaque<"constant"> — the outer bounds mode of the pie node:

• gui.PIEBOUNDS_RECTANGLE

• gui.PIEBOUNDS_ELLIPSE

Returns the outer bounds mode for a pie node.

Parameters

• node: Opaque<"node"> — node from where to get the outer bounds mode

Returns

• bounds_mode: Opaque<"constant"> — the outer bounds mode of the pie node:

• gui.PIEBOUNDS_RECTANGLE

• gui.PIEBOUNDS_ELLIPSE

Sets the leading value for a text node. This value is used to scale the line spacing of text.

Parameters

• node: Opaque<"node"> — node for which to set the leading
• leading: number — a scaling value for the line spacing (default=1)

Returns the leading value for a text node.

Parameters

• node: Opaque<"node"> — node from where to get the leading

Returns

• leading: number — leading scaling value (default=1)

Sets the tracking value of a text node. This value is used to adjust the vertical spacing of characters in the text.

Parameters

• node: Opaque<"node"> — node for which to set the tracking
• tracking: number — a scaling number for the letter spacing (default=0)

Returns the tracking value of a text node.

Parameters

• node: Opaque<"node"> — node from where to get the tracking

Returns

• tracking: number — tracking scaling number (default=0)

Tests whether a coordinate is within the bounding box of a node.

Parameters

• node: Opaque<"node"> — node to be tested for picking
• x: number — x-coordinate (see on_input )
• y: number — y-coordinate (see on_input )

Returns

• pickable: boolean — pick result

Returns true if a node is enabled and false if it's not. Disabled nodes are not rendered and animations acting on them are not evaluated.

Parameters

• node: Opaque<"node"> — node to query
• recursive?: boolean — check hierarchy recursively

Returns

• enabled: boolean — whether the node is enabled or not

Sets a node to the disabled or enabled state. Disabled nodes are not rendered and animations acting on them are not evaluated.

Parameters

• node: Opaque<"node"> — node to be enabled/disabled
• enabled: boolean — whether the node should be enabled or not

Returns true if a node is visible and false if it's not. Invisible nodes are not rendered.

Parameters

• node: Opaque<"node"> — node to query

Returns

• visible: boolean — whether the node is visible or not

Set if a node should be visible or not. Only visible nodes are rendered.

Parameters

• node: Opaque<"node"> — node to be visible or not
• visible: boolean — whether the node should be visible or not

Returns the adjust mode of a node. The adjust mode defines how the node will adjust itself to screen resolutions that differs from the one in the project settings.

Parameters

• node: Opaque<"node"> — node from which to get the adjust mode (node)

Returns

• adjust_mode: Opaque<"constant"> — the current adjust mode

• gui.ADJUST_FIT

• gui.ADJUST_ZOOM

• gui.ADJUST_STRETCH

Sets the adjust mode on a node. The adjust mode defines how the node will adjust itself to screen resolutions that differs from the one in the project settings.

Parameters

• node: Opaque<"node"> — node to set adjust mode for

• adjust_mode: Opaque<"constant"> — adjust mode to set

• gui.ADJUST_FIT

• gui.ADJUST_ZOOM

• gui.ADJUST_STRETCH

Sets how the safe area is applied to this gui scene.

Parameters

• mode: Opaque<"constant"> — safe area mode

• gui.SAFE_AREA_NONE

• gui.SAFE_AREA_LONG

• gui.SAFE_AREA_SHORT

• gui.SAFE_AREA_BOTH

Returns the size of a node. The size mode defines how the node will adjust itself in size. Automatic size mode alters the node size based on the node's content. Automatic size mode works for Box nodes and Pie nodes which will both adjust their size to match the assigned image. Particle fx and Text nodes will ignore any size mode setting.

Parameters

• node: Opaque<"node"> — node from which to get the size mode (node)

Returns

• size_mode: Opaque<"constant"> — the current size mode

• gui.SIZE_MODE_MANUAL

• gui.SIZE_MODE_AUTO

Sets the size mode of a node. The size mode defines how the node will adjust itself in size. Automatic size mode alters the node size based on the node's content. Automatic size mode works for Box nodes and Pie nodes which will both adjust their size to match the assigned image. Particle fx and Text nodes will ignore any size mode setting.

Parameters

• node: Opaque<"node"> — node to set size mode for

• size_mode: Opaque<"constant"> — size mode to set

• gui.SIZE_MODE_MANUAL

• gui.SIZE_MODE_AUTO

Alters the ordering of the two supplied nodes by moving the first node above the second. If the second argument is nil the first node is moved to the top.

Parameters

• node: Opaque<"node"> — to move
• reference: Opaque<"node"> | nil — reference node above which the first node should be moved

Alters the ordering of the two supplied nodes by moving the first node below the second. If the second argument is nil the first node is moved to the bottom.

Parameters

• node: Opaque<"node"> — to move
• reference: Opaque<"node"> | nil — reference node below which the first node should be moved

Returns the parent node of the specified node. If the supplied node does not have a parent, nil is returned.

Parameters

• node: Opaque<"node"> — the node from which to retrieve its parent

Returns

• parent: Opaque<"node"> | nil — parent instance or nil

Sets the parent node of the specified node.

Parameters

• node: Opaque<"node"> — node for which to set its parent
• parent?: Opaque<"node"> — parent node to set, pass nil to remove parent
• keep_scene_transform?: boolean — optional flag to make the scene position being perserved

Make a clone instance of a node. The cloned node will be identical to the original node, except the id which is generated as the string "node" plus a sequential unsigned integer value. This function does not clone the supplied node's children nodes. Use gui.clone_tree for that purpose.

Parameters

• node: Opaque<"node"> — node to clone

Returns

• clone: Opaque<"node"> — the cloned node

Make a clone instance of a node and all its children. Use gui.clone to clone a node excluding its children.

Parameters

• node: Opaque<"node"> — root node to clone

Returns

• clones: Record<string | number, unknown> — a table mapping node ids to the corresponding cloned nodes

Get a node and all its children as a Lua table.

Parameters

• node: Opaque<"node"> — root node to get node tree from

Returns

• clones: Record<string | number, unknown> — a table mapping node ids to the corresponding nodes

Resets all nodes in the current GUI scene to their initial state. The reset only applies to static node loaded from the scene. Nodes that are created dynamically from script are not affected.

Set the order number for the current GUI scene. The number dictates the sorting of the "gui" render predicate, in other words in which order the scene will be rendered in relation to other currently rendered GUI scenes. The number must be in the range 0 to 15.

Parameters

• order: number — rendering order (0-15)

Shows the on-display touch keyboard. The specified type of keyboard is displayed if it is available on the device. This function is only available on iOS and Android. .

Parameters

• type: Opaque<"constant"> — keyboard type

• gui.KEYBOARD_TYPE_DEFAULT

• gui.KEYBOARD_TYPE_EMAIL

• gui.KEYBOARD_TYPE_NUMBER_PAD

• gui.KEYBOARD_TYPE_PASSWORD

• autoclose: boolean — if the keyboard should automatically close when clicking outside

Hides the on-display touch keyboard on the device.

Resets the input context of keyboard. This will clear marked text.

Returns the position of the supplied node.

Parameters

• node: Opaque<"node"> — node to get the position from

Returns

• position: Vector3 — node position

Sets the position of the supplied node.

Parameters

• node: Opaque<"node"> — node to set the position for
• position: Vector3 | Vector4 — new position

Returns the rotation of the supplied node. The rotation is expressed as a quaternion

Parameters

• node: Opaque<"node"> — node to get the rotation from

Returns

• rotation: Quaternion — node rotation

Sets the rotation of the supplied node. The rotation is expressed as a quaternion

Parameters

• node: Opaque<"node"> — node to set the rotation for
• rotation: Quaternion | Vector4 — new rotation

Returns the rotation of the supplied node. The rotation is expressed in degree Euler angles.

Parameters

• node: Opaque<"node"> — node to get the rotation from

Returns

• rotation: Vector3 — node rotation

Sets the rotation of the supplied node. The rotation is expressed in degree Euler angles.

Parameters

• node: Opaque<"node"> — node to set the rotation for
• rotation: Vector3 | Vector4 — new rotation

Returns the scale of the supplied node.

Parameters

• node: Opaque<"node"> — node to get the scale from

Returns

• scale: Vector3 — node scale

Sets the scaling of the supplied node.

Parameters

• node: Opaque<"node"> — node to set the scale for
• scale: Vector3 | Vector4 — new scale

Returns the color of the supplied node. The components of the returned vector4 contains the color channel values:

Component Color value

x Red value

y Green value

z Blue value

w Alpha value

Parameters

• node: Opaque<"node"> — node to get the color from

Returns

• color: Vector4 — node color

Sets the color of the supplied node. The components of the supplied vector3 or vector4 should contain the color channel values:

Component Color value

x Red value

y Green value

z Blue value

w vector4 Alpha value

Parameters

• node: Opaque<"node"> — node to set the color for
• color: Vector3 | Vector4 — new color

Returns the outline color of the supplied node. See gui.get_color for info how vectors encode color values.

Parameters

• node: Opaque<"node"> — node to get the outline color from

Returns

• color: Vector4 — outline color

Sets the outline color of the supplied node. See gui.set_color for info how vectors encode color values.

Parameters

• node: Opaque<"node"> — node to set the outline color for
• color: Vector3 | Vector4 — new outline color

Returns the shadow color of the supplied node. See gui.get_color for info how vectors encode color values.

Parameters

• node: Opaque<"node"> — node to get the shadow color from

Returns

• color: Vector4 — node shadow color

Sets the shadow color of the supplied node. See gui.set_color for info how vectors encode color values.

Parameters

• node: Opaque<"node"> — node to set the shadow color for
• color: Vector3 | Vector4 — new shadow color

Sets the size of the supplied node. You can only set size on nodes with size mode set to SIZE_MODE_MANUAL

Parameters

• node: Opaque<"node"> — node to set the size for
• size: Vector3 | Vector4 — new size

Returns the size of the supplied node.

Parameters

• node: Opaque<"node"> — node to get the size from

Returns

• size: Vector3 — node size

Returns the screen position of the supplied node. This function returns the calculated transformed position of the node, taking into account any parent node transforms.

Parameters

• node: Opaque<"node"> — node to get the screen position from

Returns

• position: Vector3 — node screen position

Set the screen position to the supplied node

Parameters

• node: Opaque<"node"> — node to set the screen position to
• screen_position: Vector3 — screen position

Convert the screen position to the local position of supplied node

Parameters

• node: Opaque<"node"> — node used for getting local transformation matrix
• screen_position: Vector3 — screen position

Returns

• local_position: Vector3 — local position

This is only useful nodes with flipbook animations. Gets the normalized cursor of the flipbook animation on a node.

Parameters

• node: Opaque<"node"> — node to get the cursor for (node)

Returns

• cursor: number — cursor value

This is only useful nodes with flipbook animations. The cursor is normalized.

Parameters

• node: Opaque<"node"> — node to set the cursor for
• cursor: number — cursor value

This is only useful nodes with flipbook animations. Gets the playback rate of the flipbook animation on a node.

Parameters

• node: Opaque<"node"> — node to set the cursor for

Returns

• rate: number — playback rate

This is only useful nodes with flipbook animations. Sets the playback rate of the flipbook animation on a node. Must be positive.

Parameters

• node: Opaque<"node"> — node to set the cursor for
• playback_rate: number — playback rate

Dynamically create a particle fx node.

Parameters

• pos: Vector3 | Vector4 — node position
• particlefx: Hash | string — particle fx resource name

Returns

• node: Opaque<"node"> — new particle fx node

Plays the paricle fx for a gui node

// How to play a particle fx when a gui node is created.
// The callback receives the gui node, the hash of the id
// of the emitter, and the new state of the emitter as particlefx.EMITTER_STATE_.
function emitter_state_change(self, node, emitter, state) {
  if (emitter === hash("exhaust") && state === particlefx.EMITTER_STATE_POSTSPAWN) {
    // exhaust is done spawning particles...
  }
}

export default defineScript({
  init(self) {
    gui.play_particlefx(gui.get_node("particlefx"), emitter_state_change);
  },
});

Parameters

• node: Opaque<"node"> — node to play particle fx for
• emitter_state_function?: function(self, node, emitter, state) — optional callback function that will be called when an emitter attached to this particlefx changes state.

self object The current object node hash The particle fx node, or nil if the node was deleted emitter hash The id of the emitter state constant the new state of the emitter:

• particlefx.EMITTER_STATE_SLEEPING

• particlefx.EMITTER_STATE_PRESPAWN

• particlefx.EMITTER_STATE_SPAWNING

• particlefx.EMITTER_STATE_POSTSPAWN

Stops the particle fx for a gui node

Parameters

• node: Opaque<"node"> — node to stop particle fx for

• options?: Record<string | number, unknown> — options when stopping the particle fx. Supported options:

• boolean clear: instantly clear spawned particles

Set the paricle fx for a gui node

Parameters

• node: Opaque<"node"> — node to set particle fx for
• particlefx: Hash | string — particle fx id

Get the paricle fx for a gui node

Parameters

• node: Opaque<"node"> — node to get particle fx for

Returns

• particlefx: Hash — particle fx id

gets the node inherit alpha state

Parameters

• node: Opaque<"node"> — node from which to get the inherit alpha state

Returns

• inherit_alpha: boolean — true or false

sets the node inherit alpha state

Parameters

• node: Opaque<"node"> — node from which to set the inherit alpha state
• inherit_alpha: boolean — true or false

gets the node alpha

Parameters

• node: Opaque<"node"> — node from which to get alpha

Returns

• alpha: number — alpha

sets the node alpha

Parameters

• node: Opaque<"node"> — node for which to set alpha
• alpha: number — 0..1 alpha color

This is a callback-function, which is called by the engine when a gui component is initialized. It can be used to set the initial state of the script and gui scene.

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 gui component is finalized (destroyed). It can be used to e.g. take some last action, report the finalization to other game object instances or release user input focus (see release_input_focus). There is no use in starting any animations or similar from this function since the gui component is about to be destroyed.

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 gui component. It can be used to perform any kind of gui related tasks, e.g. animating nodes.

// This example demonstrates how to update a text node that displays game score
// in a counting fashion. It is assumed that the gui component receives messages
// from the game when a new score is to be shown.
export default defineGuiScript({
  init(self) {
    // fetch the score text node for later use (assumes it is called "score")
    self.score_node = gui.get_node("score");
    // keep track of the current score counted up so far
    self.current_score = 0;
    // keep track of the target score we should count up to
    self.target_score = 0;
    // how fast we will update the score, in score/second
    self.score_update_speed = 1;
  },

  update(self, dt) {
    // check if target score is more than current score
    if (self.current_score < self.target_score) {
      // increment current score according to the speed
      self.current_score = self.current_score + dt * self.score_update_speed;
      // check if we went past the target score, clamp current score in that case
      if (self.current_score > self.target_score) {
        self.current_score = self.target_score;
      }
      // update the score text node
      gui.set_text(self.score_node, "" + math.floor(self.current_score));
    }
  },

  on_message(self, message_id, message) {
    // check the message
    if (message_id === hash("set_score")) {
      self.target_score = message.score;
    }
  },
});

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 gui component. It can be used to take action on the message, e.g. update the gui or 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. See the update function for examples on how to use this callback-function.

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

This is a callback-function, which is called by the engine when user input is sent to the instance of the gui component. It can be used to take action on the input, e.g. modify the gui 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).

export default defineScript({
  on_input(self, action_id, action) {
    // check for input
    if (action_id === hash("my_action")) {
      // take appropriate action
      self.my_value = action.value;
    }
    // consume input
    return true;
  },
});

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 gui script 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 script.

export default defineGuiScript({
  on_reload(self) {
    // restore some color (or similar)
    gui.set_color(gui.get_node("my_node"), self.my_original_color);
  },
});

Parameters

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

once forward

once backward

once forward and then backward

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