local function emitter_state_change(self, node, emitter, state)
  if emitter == hash("exhaust") and state == particlefx.EMITTER_STATE_POSTSPAWN then
    -- exhaust is done spawning particles...
  end
end

function init(self)
    gui.play_particlefx(gui.get_node("particlefx"), emitter_state_change)
end

gui.reset_keyboard

void gui.reset_keyboard()

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

PARAMETERS

gui.reset_material

void gui.reset_material(node node)

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

PARAMETERS

EXAMPLES

local node = gui.get_node("my_node")
gui.reset_material(node)

gui.reset_nodes

void gui.reset_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.

PARAMETERS

gui.screen_to_local

vector3 gui.screen_to_local(node node, vector3 screen_position)

Convert the screen position to the local position of supplied node

PARAMETERS

RETURNS

gui.set

void gui.set(node node, stringhashconstant property, numbervector4vector3quat value, table [options])

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)

PARAMETERS

EXAMPLES

local node = gui.get_node("my_box_node")
local node_position = gui.get(node, "position")
gui.set(node, "position.x", node_position.x + 128)

local node = gui.get_node("my_box_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))

local node = gui.get_node("my_box_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})

gui.set_adjust_mode

void gui.set_adjust_mode(node node, constant adjust_mode)

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

gui.set_alpha

void gui.set_alpha(node node, number alpha)

sets the node alpha

PARAMETERS

gui.set_blend_mode

void gui.set_blend_mode(node node, constant blend_mode)

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

PARAMETERS

gui.set_clipping_inverted

void gui.set_clipping_inverted(node node, boolean inverted)

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

PARAMETERS

gui.set_clipping_mode

void gui.set_clipping_mode(node node, constant clipping_mode)

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

PARAMETERS

gui.set_clipping_visible

void gui.set_clipping_visible(node node, boolean visible)

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

gui.set_color

void gui.set_color(node node, vector3vector4 color)

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

PARAMETERS

gui.set_enabled

void gui.set_enabled(node node, boolean enabled)

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

PARAMETERS

gui.set_euler

void gui.set_euler(node node, vector3vector4 rotation)

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

PARAMETERS

gui.set_fill_angle

void gui.set_fill_angle(node node, number angle)

Set the sector angle of a pie node.

PARAMETERS

gui.set_flipbook_cursor

void gui.set_flipbook_cursor(node node, number cursor)

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

PARAMETERS

gui.set_flipbook_playback_rate

void gui.set_flipbook_playback_rate(node node, 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

gui.set_font

void gui.set_font(node node, stringhash font)

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

PARAMETERS

gui.set_id

void gui.set_id(node node, stringhash id)

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.

PARAMETERS

EXAMPLES

local pos = vmath.vector3(100, 100, 0)
local size = vmath.vector3(100, 100, 0)
local node = gui.new_box_node(pos, size)
gui.set_id(node, "my_new_node")

gui.set_inherit_alpha

void gui.set_inherit_alpha(node node, boolean inherit_alpha)

sets the node inherit alpha state

PARAMETERS

gui.set_inner_radius

void gui.set_inner_radius(node node, number radius)

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

PARAMETERS

gui.set_layer

void gui.set_layer(node node, stringhash layer)

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

PARAMETERS

gui.set_leading

void gui.set_leading(node node, number leading)

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

PARAMETERS

gui.set_line_break

void gui.set_line_break(node node, boolean line_break)

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

PARAMETERS

gui.set_material

void gui.set_material(node node, stringhash material)

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.

PARAMETERS

EXAMPLES

local node = gui.get_node("my_node")
gui.set_material(node, "my_material")

gui.set_outer_bounds

void gui.set_outer_bounds(node node, constant bounds_mode)

Sets the outer bounds mode for a pie node.

PARAMETERS

gui.set_outline

void gui.set_outline(node node, vector3vector4 color)

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

PARAMETERS

gui.set_parent

void gui.set_parent(node node, node [parent], boolean [keep_scene_transform])

Sets the parent node of the specified node.

PARAMETERS

gui.set_particlefx

void gui.set_particlefx(node node, hashstring particlefx)

Set the paricle fx for a gui node

PARAMETERS

gui.set_perimeter_vertices

void gui.set_perimeter_vertices(node node, number vertices)

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

PARAMETERS

gui.set_pivot

void gui.set_pivot(node node, constant pivot)

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

PARAMETERS

gui.set_position

void gui.set_position(node node, vector3vector4 position)

Sets the position of the supplied node.

PARAMETERS

gui.set_render_order

void gui.set_render_order(number order)

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

gui.set_rotation

void gui.set_rotation(node node, quaternionvector4 rotation)

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

PARAMETERS

gui.set_scale

void gui.set_scale(node node, vector3vector4 scale)

Sets the scaling of the supplied node.

PARAMETERS

gui.set_screen_position

void gui.set_screen_position(node node, vector3 screen_position)

Set the screen position to the supplied node

PARAMETERS

gui.set_shadow

void gui.set_shadow(node node, vector3vector4 color)

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

PARAMETERS

gui.set_size

void gui.set_size(node node, vector3vector4 size)

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

PARAMETERS

gui.set_size_mode

void gui.set_size_mode(node node, constant size_mode)

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

gui.set_slice9

void gui.set_slice9(node node, vector4 values)

Set the slice9 configuration values for the node.

PARAMETERS

gui.set_text

void gui.set_text(node node, stringnumber text)

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

PARAMETERS

gui.set_texture

void gui.set_texture(node node, stringhash texture)

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.

PARAMETERS

EXAMPLES

local node = gui.get_node("box_node")
gui.set_texture(node, "my_atlas")
gui.play_flipbook(node, "image")

local w = 200
local h = 300
-- A nice orange. String with the RGB values.
local orange = string.char(0xff) .. string.char(0x80) .. string.char(0x10)
-- Create the texture. Repeat the color string for each pixel.
if gui.new_texture("orange_tx", w, h, "rgb", string.rep(orange, w * h)) then
    local node = gui.get_node("box_node")
    gui.set_texture(node, "orange_tx")
end

gui.set_texture_data

boolean gui.set_texture_data(stringhash texture, number width, number height, stringconstant type, string buffer, boolean flip)

Set the texture buffer data for a dynamically created texture.

PARAMETERS

RETURNS

EXAMPLES

function init(self)
     local w = 200
     local h = 300

     -- Create a dynamic texture, all white.
     if gui.new_texture("dynamic_tx", w, h, "rgb", string.rep(string.char(0xff), w * h * 3)) then
         -- Create a box node and apply the texture to it.
         local 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.
         local orange = string.char(0xff) .. string.char(0x80) .. string.char(0x10)
         if gui.set_texture_data("dynamic_tx", w, h, "rgb", string.rep(orange, w * h)) then
             -- Go on and to more stuff
             ...
         end
     else
         -- Something went wrong
         ...
     end
end

gui.set_tracking

void gui.set_tracking(node node, number tracking)

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

PARAMETERS

gui.set_visible

void gui.set_visible(node node, boolean visible)

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

PARAMETERS

gui.set_xanchor

void gui.set_xanchor(node node, constant anchor)

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

PARAMETERS

gui.set_yanchor

void gui.set_yanchor(node node, constant anchor)

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

PARAMETERS

gui.show_keyboard

void gui.show_keyboard(constant type, boolean autoclose)

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

gui.stop_particlefx

void gui.stop_particlefx(node node, table [options])

Stops the particle fx for a gui node

PARAMETERS

init

void init(object self)

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.

PARAMETERS

EXAMPLES

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

on_input

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

This is a callback-function, which is called by the engine when user input is sent to the 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:

PARAMETERS

RETURNS

EXAMPLES

function on_input(self, action_id, action)
    -- check for input
    if action_id == hash("my_action") then
        -- take appropritate action
        self.my_value = action.value
    end
    -- consume input
    return true
end

on_message

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

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

on_reload

void on_reload(object self)

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.

PARAMETERS

EXAMPLES

function on_reload(self)
    -- restore some color (or similar)
    gui.set_color(gui.get_node("my_node"), self.my_original_color)
end

update

void update(object self, number dt)

This is a callback-function, which is called by the engine every frame to update the state of a gui component. It can be used to perform any kind of gui related tasks, e.g. animating nodes.

PARAMETERS

EXAMPLES

function 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
end

function 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 then
            self.current_score = self.target_score
        end
        -- update the score text node
        gui.set_text(self.score_node, "" .. math.floor(self.current_score))
    end
end

function on_message(self, message_id, message, sender)
    -- check the message
    if message_id == hash("set_score") then
        self.target_score = message.score
    end
end

Constants

gui.ADJUST_FIT

Adjust mode is used when the screen resolution differs from the project settings. The fit mode ensures that the entire node is visible in the adjusted gui scene.

gui.ADJUST_STRETCH

Adjust mode is used when the screen resolution differs from the project settings. The stretch mode ensures that the node is displayed as is in the adjusted gui scene, which might scale it non-uniformally.

gui.ADJUST_ZOOM

Adjust mode is used when the screen resolution differs from the project settings. The zoom mode ensures that the node fills its entire area and might make the node exceed it.

gui.ANCHOR_BOTTOM

bottom y-anchor

gui.ANCHOR_LEFT

left x-anchor

gui.ANCHOR_NONE

no anchor

gui.ANCHOR_RIGHT

right x-anchor

gui.ANCHOR_TOP

top y-anchor

gui.BLEND_ADD

additive blending

gui.BLEND_ADD_ALPHA

additive alpha blending

gui.BLEND_ALPHA

alpha blending

gui.BLEND_MULT

multiply blending

gui.BLEND_SCREEN

screen blending

gui.CLIPPING_MODE_NONE

clipping mode none

gui.CLIPPING_MODE_STENCIL

clipping mode stencil

gui.EASING_INBACK

in-back

gui.EASING_INBOUNCE

in-bounce

gui.EASING_INCIRC

in-circlic

gui.EASING_INCUBIC

in-cubic

gui.EASING_INELASTIC

in-elastic

gui.EASING_INEXPO

in-exponential

gui.EASING_INOUTBACK

in-out-back

gui.EASING_INOUTBOUNCE

in-out-bounce

gui.EASING_INOUTCIRC

in-out-circlic

gui.EASING_INOUTCUBIC

in-out-cubic

gui.EASING_INOUTELASTIC

in-out-elastic

gui.EASING_INOUTEXPO

in-out-exponential

gui.EASING_INOUTQUAD

in-out-quadratic

gui.EASING_INOUTQUART

in-out-quartic

gui.EASING_INOUTQUINT

in-out-quintic

gui.EASING_INOUTSINE

in-out-sine

gui.EASING_INQUAD

in-quadratic

gui.EASING_INQUART

in-quartic

gui.EASING_INQUINT

in-quintic

gui.EASING_INSINE

in-sine

gui.EASING_LINEAR

linear interpolation

gui.EASING_OUTBACK

out-back

gui.EASING_OUTBOUNCE

out-bounce

gui.EASING_OUTCIRC

out-circlic

gui.EASING_OUTCUBIC

out-cubic

gui.EASING_OUTELASTIC

out-elastic

gui.EASING_OUTEXPO

out-exponential

gui.EASING_OUTINBACK

out-in-back

gui.EASING_OUTINBOUNCE

out-in-bounce

gui.EASING_OUTINCIRC

out-in-circlic

gui.EASING_OUTINCUBIC

out-in-cubic

gui.EASING_OUTINELASTIC

out-in-elastic

gui.EASING_OUTINEXPO

out-in-exponential

gui.EASING_OUTINQUAD

out-in-quadratic

gui.EASING_OUTINQUART

out-in-quartic

gui.EASING_OUTINQUINT

out-in-quintic

gui.EASING_OUTINSINE

out-in-sine

gui.EASING_OUTQUAD

out-quadratic

gui.EASING_OUTQUART

out-quartic

gui.EASING_OUTQUINT

out-quintic

gui.EASING_OUTSINE

out-sine

gui.KEYBOARD_TYPE_DEFAULT

default keyboard

gui.KEYBOARD_TYPE_EMAIL

email keyboard

gui.KEYBOARD_TYPE_NUMBER_PAD

number input keyboard

gui.KEYBOARD_TYPE_PASSWORD

password keyboard

gui.PIEBOUNDS_ELLIPSE

elliptical pie node bounds

gui.PIEBOUNDS_RECTANGLE

rectangular pie node bounds

gui.PIVOT_CENTER

center pivot

gui.PIVOT_E

east pivot

gui.PIVOT_N

north pivot

gui.PIVOT_NE

north-east pivot

gui.PIVOT_NW

north-west pivot

gui.PIVOT_S

south pivot

gui.PIVOT_SE

south-east pivot

gui.PIVOT_SW

south-west pivot

gui.PIVOT_W

west pivot

gui.PLAYBACK_LOOP_BACKWARD

loop backward

gui.PLAYBACK_LOOP_FORWARD

loop forward

gui.PLAYBACK_LOOP_PINGPONG

ping pong loop

gui.PLAYBACK_ONCE_BACKWARD

once backward

gui.PLAYBACK_ONCE_FORWARD

once forward

gui.PLAYBACK_ONCE_PINGPONG

once forward and then backward

gui.PROP_COLOR

color property

gui.PROP_EULER

euler property

gui.PROP_FILL_ANGLE

fill_angle property

gui.PROP_INNER_RADIUS

inner_radius property

gui.PROP_LEADING

leading property

gui.PROP_OUTLINE

outline color property

gui.PROP_POSITION

position property

gui.PROP_ROTATION

rotation property

gui.PROP_SCALE

scale property

gui.PROP_SHADOW

shadow color property

gui.PROP_SIZE

size property

gui.PROP_SLICE9

slice9 property

gui.PROP_TRACKING

tracking property

gui.RESULT_DATA_ERROR

The provided data is not in the expected format or is in some other way incorrect, for instance the image data provided to gui.new_texture().

gui.RESULT_OUT_OF_RESOURCES

The system is out of resources, for instance when trying to create a new texture using gui.new_texture().

gui.RESULT_TEXTURE_ALREADY_EXISTS

The texture id already exists when trying to use gui.new_texture().

gui.SIZE_MODE_AUTO

The size of the node is determined by the currently assigned texture.