GUI API documentation

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

gui.reset_keyboard()

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

PARAMETERS

None

gui.reset_material()

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

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

None

gui.screen_to_local()

gui.screen_to_local(node,screen_position)

Convert the screen position to the local position of supplied node

PARAMETERS

RETURNS

gui.set()

gui.set(node,property,value,[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()

gui.set_adjust_mode(node,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()

gui.set_alpha(node,alpha)

sets the node alpha

PARAMETERS

gui.set_blend_mode()

gui.set_blend_mode(node,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()

gui.set_clipping_inverted(node,inverted)

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

PARAMETERS

gui.set_clipping_mode()

gui.set_clipping_mode(node,clipping_mode)

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

PARAMETERS

gui.set_clipping_visible()

gui.set_clipping_visible(node,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()

gui.set_color(node,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()

gui.set_enabled(node,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()

gui.set_euler(node,rotation)

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

PARAMETERS

gui.set_fill_angle()

gui.set_fill_angle(node,angle)

Set the sector angle of a pie node.

PARAMETERS

gui.set_flipbook_cursor()

gui.set_flipbook_cursor(node,cursor)

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

PARAMETERS

gui.set_flipbook_playback_rate()

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

gui.set_font(node,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()

gui.set_id(node,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()

gui.set_inherit_alpha(node,inherit_alpha)

sets the node inherit alpha state

PARAMETERS

gui.set_inner_radius()

gui.set_inner_radius(node,radius)

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

PARAMETERS

gui.set_layer()

gui.set_layer(node,layer)

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

PARAMETERS

gui.set_leading()

gui.set_leading(node,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()

gui.set_line_break(node,line_break)

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

PARAMETERS

gui.set_material()

gui.set_material(node,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()

gui.set_outer_bounds(node,bounds_mode)

Sets the outer bounds mode for a pie node.

PARAMETERS

gui.set_outline()

gui.set_outline(node,color)

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

PARAMETERS

gui.set_parent()

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

Sets the parent node of the specified node.

PARAMETERS

gui.set_particlefx()

gui.set_particlefx(node,particlefx)

Set the paricle fx for a gui node

PARAMETERS

gui.set_perimeter_vertices()

gui.set_perimeter_vertices(node,vertices)

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

PARAMETERS

gui.set_pivot()

gui.set_pivot(node,pivot)

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

PARAMETERS

gui.set_position()

gui.set_position(node,position)

Sets the position of the supplied node.

PARAMETERS

gui.set_render_order()

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

gui.set_rotation(node,rotation)

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

PARAMETERS

gui.set_scale()

gui.set_scale(node,scale)

Sets the scaling of the supplied node.

PARAMETERS

gui.set_screen_position()

gui.set_screen_position(node,screen_position)

Set the screen position to the supplied node

PARAMETERS

gui.set_shadow()

gui.set_shadow(node,color)

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

PARAMETERS

gui.set_size()

gui.set_size(node,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()

gui.set_size_mode(node,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()

gui.set_slice9(node,values)

Set the slice9 configuration values for the node.

PARAMETERS

gui.set_text()

gui.set_text(node,text)

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

PARAMETERS

gui.set_texture()

gui.set_texture(node,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()

gui.set_texture_data(texture,width,height,type,buffer,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()

gui.set_tracking(node,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()

gui.set_visible(node,visible)

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

PARAMETERS

gui.set_xanchor()

gui.set_xanchor(node,anchor)

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

PARAMETERS

gui.set_yanchor()

gui.set_yanchor(node,anchor)

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

PARAMETERS

gui.show_keyboard()

gui.show_keyboard(type,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()

gui.stop_particlefx(node,[options])

Stops the particle fx for a gui node

PARAMETERS

init()

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

on_input(self,action_id,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()

on_message(self,message_id,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()

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

update(self,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.

gui.SIZE_MODE_MANUAL

The size of the node is determined by the size set in the editor, the constructor or by gui.set_size()

Messages

layout_changed

This message is broadcast to every GUI component when a layout change has been initiated on device.

EXAMPLES

function on_message(self, message_id, message, sender)
   if message_id == hash("layout_changed") and message.id == hash("Landscape") then
       -- switching layout to "Landscape"...
       ...
   end
end

Properties

fonts

The fonts used in the gui. The type of the property is hash. Key must be specified in options table.

EXAMPLES

go.property("title_latin", resource.font("/open_sans.font"))
go.property("title_cyrillic", resource.font("/open_sans_cyrillic.font"))

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

material

The main material (the default material assigned to a GUI) used when rendering the gui. The type of the property is hash.

EXAMPLES

go.property("desaturate_material", resource.material("/desaturate.material"))

function init(self)
  go.set("#gui", "material", self.desaturate_material)
end

materials

The materials used when rendering the gui. The type of the property is hash. Key must be specified in options table.

EXAMPLES

go.property("my_material", resource.material("/my_material.material"))

function init(self)
  -- this will update the "my_gui_material" entry in the GUI to use the material
  -- specified in the "my_material" script property.
  go.set("#gui", "materials", self.my_material, { key = "my_gui_material" })
end

textures

The textures used in the gui. The type of the property is hash. Key must be specified in options table.

EXAMPLES

go.property("cards_red", resource.atlas("/cards_red.atlas"))
go.property("cards_blue", resource.atlas("/cards_blue.atlas"))

function init(self)
  go.set("#gui", "textures", self.cards_red, {key = "cards"})
end