Lua

Defold

Extension

Version

GUI API documentation

Version: alpha

FUNCTION
gui.get_node()	gets the node with the specified id
gui.get_id()	gets the id of the specified node
gui.set_id()	sets the id of the specified node
gui.get_index()	gets the index of the specified node
gui.delete_node()	deletes a node
gui.animate()	animates a node property
gui.cancel_animation()	cancels an ongoing animation
gui.new_box_node()	creates a new box node
gui.new_text_node()	creates a new text node
gui.new_pie_node()	creates a new pie node
gui.new_spine_node()	creates a new spine node
gui.get_text()	gets the node text
gui.set_text()	sets the node text
gui.get_line_break()	get line-break mode
gui.set_line_break()	set line-break mode
gui.get_blend_mode()	gets the node blend mode
gui.set_blend_mode()	sets node blend mode
gui.get_texture()	gets node texture
gui.set_texture()	sets the node texture
gui.get_flipbook()	gets the node flipbook animation
gui.play_flipbook()	play node flipbook animation
gui.cancel_flipbook()	cancel a node flipbook animation
gui.new_texture()	create new texture
gui.delete_texture()	delete texture
gui.set_texture_data()	set the buffer data for a texture
gui.get_font()	gets the node font
gui.set_font()	sets the node font
gui.get_layer()	gets the node layer
gui.set_layer()	sets the node layer
gui.get_layout()	gets the scene current layout
gui.get_clipping_mode()	gets the node clipping mode
gui.set_clipping_mode()	sets node clipping mode state
gui.get_clipping_visible()	gets node clipping visibility state
gui.set_clipping_visible()	sets node clipping visibility
gui.get_clipping_inverted()	gets node clipping inverted state
gui.set_clipping_inverted()	sets node clipping inversion
gui.get_text_metrics_from_node()	get text metrics from node
gui.get_text_metrics()	get text metrics
gui.get_xanchor()	gets the x-anchor of a node
gui.set_xanchor()	sets the x-anchor of a node
gui.get_yanchor()	gets the y-anchor of a node
gui.set_yanchor()	sets the y-anchor of a node
gui.get_pivot()	gets the pivot of a node
gui.set_pivot()	sets the pivot of a node
gui.get_width()	gets the scene width
gui.get_height()	gets the scene height
gui.set_slice9()	set the slice9 configuration for the node
gui.get_slice9()	get the slice9 values for the node
gui.set_perimeter_vertices()	sets the number of generated vertices around the perimeter
gui.get_perimeter_vertices()	gets the number of generated vertices around the perimeter
gui.set_fill_angle()	sets the angle for the filled pie sector
gui.get_fill_angle()	gets the angle for the filled pie sector
gui.set_inner_radius()	sets the pie inner radius
gui.get_inner_radius()	gets the pie inner radius
gui.set_outer_bounds()	sets the pie node outer bounds mode
gui.get_outer_bounds()	gets the pie outer bounds mode
gui.set_leading()	sets the leading of the text node
gui.get_leading()	gets the leading of the text node
gui.set_tracking()	sets the tracking of the text node
gui.get_tracking()	gets the tracking of the text node
gui.pick_node()	determines if the node is pickable by the supplied coordinates
gui.is_enabled()	returns if a node is enabled or not
gui.set_enabled()	enables/disables a node
gui.get_adjust_mode()	gets the node adjust mode
gui.set_adjust_mode()	sets node adjust mode
gui.get_size_mode()	gets the node size mode
gui.set_size_mode()	sets node size mode
gui.move_above()	moves the first node above the second
gui.move_below()	moves the first node below the second
gui.get_parent()	gets the parent of the specified node
gui.set_parent()	sets the parent of the node
gui.clone()	clone a node
gui.clone_tree()	clone a node including its children
gui.reset_nodes()	resets all nodes to initial state
gui.set_render_order()	sets the render ordering for the current GUI scene
gui.show_keyboard()	shows the on-display keyboard if available
gui.hide_keyboard()	hides on-display keyboard if available
gui.reset_keyboard()	resets on-display keyboard if available
gui.get_position()	gets the node position
gui.set_position()	sets the node position
gui.get_rotation()	gets the node rotation
gui.set_rotation()	sets the node rotation
gui.get_scale()	gets the node scale
gui.set_scale()	sets the node scale
gui.get_color()	gets the node color
gui.set_color()	sets the node color
gui.get_outline()	gets the node outline color
gui.set_outline()	sets the node outline color
gui.get_shadow()	gets the node shadow color
gui.set_shadow()	sets the node shadow color
gui.set_size()	sets the node size
gui.get_size()	gets the node size
gui.get_screen_position()	gets the node screen position
gui.play_spine_anim()	play a spine animation
gui.cancel_spine()	cancel a spine animation
gui.get_spine_bone()	retrieve the GUI node corresponding to a spine skeleton bone
gui.set_spine_scene()	sets the spine scene of a node
gui.get_spine_scene()	gets the spine scene of a node
gui.set_spine_skin()	sets the spine skin
gui.get_spine_animation()	gets the playing animation on a spine node
gui.get_spine_skin()	gets the skin of a spine node
gui.set_spine_cursor()	sets the normalized cursor of the animation on a spine node
gui.get_spine_cursor()	gets the normalized cursor of the animation on a spine node
gui.get_flipbook_cursor()	gets the normalized cursor of the animation on a node with flipbook animation
gui.set_flipbook_cursor()	sets the normalized cursor of the animation on a node with flipbook animation
gui.get_flipbook_playback_rate()	gets the playback rate of the flipbook animation on a node
gui.set_flipbook_playback_rate()	sets the playback rate of the flipbook animation on a node
gui.set_spine_playback_rate()	sets the playback rate of the animation on a spine node
gui.get_spine_playback_rate()	gets the playback rate of the animation on a spine node
gui.new_particlefx_node()	creates a new particle fx node
gui.play_particlefx()	Plays a particle fx
gui.stop_particlefx()	Stops a particle fx
gui.set_particlefx()	Sets a particle fx
gui.get_particlefx()	Gets a particle fx
gui.get_inherit_alpha()	gets the node inherit alpha state
gui.set_inherit_alpha()	sets the node inherit alpha state
init()	called when a gui component is initialized
final()	called when a gui component is finalized
update()	called every frame to update the gui component
on_message()	called when a message has been sent to the gui component
on_input()	called when user input is received
on_reload()	called when the gui script is reloaded

CONSTANT
gui.PLAYBACK_ONCE_FORWARD	once forward
gui.PLAYBACK_ONCE_BACKWARD	once backward
gui.PLAYBACK_ONCE_PINGPONG	once forward and then backward
gui.PLAYBACK_LOOP_FORWARD	loop forward
gui.PLAYBACK_LOOP_BACKWARD	loop backward
gui.PLAYBACK_LOOP_PINGPONG	ping pong loop
gui.EASING_LINEAR	linear interpolation
gui.EASING_INQUAD	in-quadratic
gui.EASING_OUTQUAD	out-quadratic
gui.EASING_INOUTQUAD	in-out-quadratic
gui.EASING_OUTINQUAD	out-in-quadratic
gui.EASING_INCUBIC	in-cubic
gui.EASING_OUTCUBIC	out-cubic
gui.EASING_INOUTCUBIC	in-out-cubic
gui.EASING_OUTINCUBIC	out-in-cubic
gui.EASING_INQUART	in-quartic
gui.EASING_OUTQUART	out-quartic
gui.EASING_INOUTQUART	in-out-quartic
gui.EASING_OUTINQUART	out-in-quartic
gui.EASING_INQUINT	in-quintic
gui.EASING_OUTQUINT	out-quintic
gui.EASING_INOUTQUINT	in-out-quintic
gui.EASING_OUTINQUINT	out-in-quintic
gui.EASING_INSINE	in-sine
gui.EASING_OUTSINE	out-sine
gui.EASING_INOUTSINE	in-out-sine
gui.EASING_OUTINSINE	out-in-sine
gui.EASING_INEXPO	in-exponential
gui.EASING_OUTEXPO	out-exponential
gui.EASING_INOUTEXPO	in-out-exponential
gui.EASING_OUTINEXPO	out-in-exponential
gui.EASING_INCIRC	in-circlic
gui.EASING_OUTCIRC	out-circlic
gui.EASING_INOUTCIRC	in-out-circlic
gui.EASING_OUTINCIRC	out-in-circlic
gui.EASING_INELASTIC	in-elastic
gui.EASING_OUTELASTIC	out-elastic
gui.EASING_INOUTELASTIC	in-out-elastic
gui.EASING_OUTINELASTIC	out-in-elastic
gui.EASING_INBACK	in-back
gui.EASING_OUTBACK	out-back
gui.EASING_INOUTBACK	in-out-back
gui.EASING_OUTINBACK	out-in-back
gui.EASING_INBOUNCE	in-bounce
gui.EASING_OUTBOUNCE	out-bounce
gui.EASING_INOUTBOUNCE	in-out-bounce
gui.EASING_OUTINBOUNCE	out-in-bounce
gui.KEYBOARD_TYPE_DEFAULT	default keyboard
gui.KEYBOARD_TYPE_NUMBER_PAD	number input keyboard
gui.KEYBOARD_TYPE_EMAIL	email keyboard
gui.KEYBOARD_TYPE_PASSWORD	password keyboard
gui.PROP_POSITION	position property
gui.PROP_ROTATION	rotation property
gui.PROP_SCALE	scale property
gui.PROP_COLOR	color property
gui.PROP_OUTLINE	outline color property
gui.PROP_SHADOW	shadow color property
gui.PROP_SIZE	size property
gui.PROP_FILL_ANGLE	fill_angle property
gui.PROP_INNER_RADIUS	inner_radius property
gui.PROP_SLICE9	slice9 property
gui.BLEND_ALPHA	alpha blending
gui.BLEND_ADD	additive blending
gui.BLEND_ADD_ALPHA	additive alpha blending
gui.BLEND_MULT	multiply blending
gui.CLIPPING_MODE_NONE	clipping mode none
gui.CLIPPING_MODE_STENCIL	clipping mode stencil
gui.ANCHOR_LEFT	left x-anchor
gui.ANCHOR_RIGHT	right x-anchor
gui.ANCHOR_TOP	top y-anchor
gui.ANCHOR_BOTTOM	bottom y-anchor
gui.ANCHOR_NONE	no anchor
gui.PIVOT_CENTER	center pivot
gui.PIVOT_N	north pivot
gui.PIVOT_NE	north-east pivot
gui.PIVOT_E	east pivot
gui.PIVOT_SE	south-east pivot
gui.PIVOT_S	south pivot
gui.PIVOT_SW	south-west pivot
gui.PIVOT_W	west pivot
gui.PIVOT_NW	north-west pivot
gui.ADJUST_FIT	fit adjust mode
gui.ADJUST_ZOOM	zoom adjust mode
gui.ADJUST_STRETCH	stretch adjust mode
gui.PIEBOUNDS_ELLIPSE	elliptical pie node bounds
gui.PIEBOUNDS_RECTANGLE	rectangular pie node bounds
gui.SIZE_MODE_MANUAL	manual size mode
gui.SIZE_MODE_AUTO	automatic size mode

MESSAGE
layout_changed	reports a layout change

PROPERTIES
material	hash gui material

Functions

gui.get_node()

gui.get_node(id)

Retrieves the node with the specified id.

PARAMETERS

`id`	id of the node to retrieve

RETURNS

instance a new node instance

EXAMPLES

Gets a node by id and change its color:

local node = gui.get_node("my_node")
local red = vmath.vector4(1.0, 0.0, 0.0, 1.0)
gui.set_color(node, red)

gui.get_id()

gui.get_id(node)

Retrieves the id of the specified node.

PARAMETERS

node the node to retrieve the id from

RETURNS

`id`	the id of the node

EXAMPLES

Gets the id of a node:

local node = gui.get_node("my_node")

local id = gui.get_id(node)
print(id) --> hash: [my_node]

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

`node`	node to set the id for
`id`	id to set

EXAMPLES

Create a new node and set its id:

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

gui.get_index(node)

Retrieve the index of the specified node. 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.

PARAMETERS

node the node to retrieve the id from

RETURNS

index the index of the node

EXAMPLES

Compare the index order of two nodes:

local node1 = gui.get_node("my_node_1")
local node2 = gui.get_node("my_node_2")

if gui.get_index(node1) < gui.get_index(node2) then
    -- node1 is drawn below node2
else
    -- node2 is drawn below node1
end

gui.delete_node()

gui.delete_node(node)

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

PARAMETERS

node node to delete

EXAMPLES

Delete a particular node and any child nodes it might have:

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

gui.animate()

gui.animate(node,property,to,easing,duration,[delay],[complete_function],[playback])

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

PARAMETERS

`node`	node to animate
`property`	property to animate `"position"` `"rotation"` `"scale"` `"color"` `"outline"` `"shadow"` `"size"` `"fill_angle"` (pie) `"inner_radius"` (pie) `"slice9"` (slice9) The following property constants are defined equaling the corresponding property string names. `gui.PROP_POSITION` `gui.PROP_ROTATION` `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_SLICE9`
`to`	target property value
`easing`	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`	duration of the animation in seconds.
`[delay]`	delay before the animation starts in seconds.
`[complete_function]`	function to call when the animation has completed
`[playback]`	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`

EXAMPLES

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:

local 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)
end

function init(self)
    -- fetch the node we want to animate
    local 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)
end

How to animate a node's y position using a crazy custom easing curve:

function init(self)
    local values = { 0, 0, 0, 0, 0, 0, 0, 0,
                     1, 1, 1, 1, 1, 1, 1, 1,
                     0, 0, 0, 0, 0, 0, 0, 0,
                     1, 1, 1, 1, 1, 1, 1, 1,
                     0, 0, 0, 0, 0, 0, 0, 0,
                     1, 1, 1, 1, 1, 1, 1, 1,
                     0, 0, 0, 0, 0, 0, 0, 0,
                     1, 1, 1, 1, 1, 1, 1, 1 }
    local vec = vmath.vector(values)
    local node = gui.get_node("box")
    gui.animate(node, "position.y", 100, vec, 4.0, 0, nil, gui.PLAYBACK_LOOP_PINGPONG)
end

gui.cancel_animation()

gui.cancel_animation(node,property)

If an animation of the specified node is currently running (started by gui.animate), it will immediately be canceled.

PARAMETERS

`node`	node that should have its animation canceled
`property`	property for which the animation should be canceled `"position"` `"rotation"` `"scale"` `"color"` `"outline"` `"shadow"` `"size"` `"fill_angle"` (pie) `"inner_radius"` (pie) `"slice9"` (slice9)

EXAMPLES

Start an animation of the position property of a node, then cancel parts of the animation:

local node = gui.get_node("my_node")
-- animate to new position
local pos = vmath.vector3(100, 100, 0)
gui.animate(node, "position", pos, go.EASING_LINEAR, 2)
...
-- cancel animation of the x component.
gui.cancel_animation(node, "position.x")

gui.new_box_node()

gui.new_box_node(pos,size)

Dynamically create a new box node.

PARAMETERS

`pos`	node position
`size`	node size

RETURNS

node new box node

gui.new_text_node()

gui.new_text_node(pos,text)

Dynamically create a new text node.

PARAMETERS

`pos`	node position
`text`	node text

RETURNS

node new text node

gui.new_pie_node()

gui.new_pie_node(pos,size)

Dynamically create a new pie node.

PARAMETERS

`pos`	node position
`size`	node size

RETURNS

node new pie node

gui.new_spine_node()

gui.new_spine_node(pos,spine_scene)

Dynamically create a new spine node.

PARAMETERS

`pos`	node position
`spine_scene`	spine scene id

RETURNS

node new spine node

gui.get_text()

gui.get_text(node)

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

PARAMETERS

node node from which to get the text

RETURNS

text text value

gui.set_text()

gui.set_text(node,text)

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

PARAMETERS

`node`	node to set text for
`text`	text to set

gui.get_line_break()

gui.get_line_break(node)

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

PARAMETERS

node node from which to get the line-break for

RETURNS

line_break true or false

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

`node`	node to set line-break for
`line_break`	true or false

gui.get_blend_mode()

gui.get_blend_mode(node)

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

PARAMETERS

node node from which to get the blend mode

RETURNS

blend_mode

blend mode

gui.BLEND_ALPHA
gui.BLEND_ADD
gui.BLEND_ADD_ALPHA
gui.BLEND_MULT

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

`node`	node to set blend mode for
`blend_mode`	blend mode to set `gui.BLEND_ALPHA` `gui.BLEND_ADD` `gui.BLEND_ADD_ALPHA` `gui.BLEND_MULT`

gui.get_texture()

gui.get_texture(node)

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 node to get texture from

RETURNS

texture texture id

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

`node`	node to set texture for
`texture`	texture id

EXAMPLES

To set a texture (or animation) from an atlas:

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

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

gui.get_flipbook(node)

Get node flipbook animation.

PARAMETERS

node node to get flipbook animation from

RETURNS

animation animation id

gui.play_flipbook()

gui.play_flipbook(node,animation,[complete_function],[play_properties])

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.

PARAMETERS

`node`	node to set animation for
`animation`	animation id
`[complete_function]`	optional function to call when the animation has completed `self` object The current object. `node` node The node that is animated.
`[play_properties]`	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

EXAMPLES

Set the texture of a node to a flipbook animation from an atlas:

local function anim_callback(self, node)
    -- Take action after animation has played.
end

function init(self)
    -- Create a new node and set the texture to a flipbook animation
    local node = gui.get_node("button_node")
    gui.set_texture(node, "gui_sprites")
    gui.play_flipbook(node, "animated_button")
end

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
local node = gui.get_node("button_node")
gui.set_texture(node, "gui_sprites")
gui.play_flipbook(node, "button")

gui.cancel_flipbook()

gui.cancel_flipbook(node)

Cancels any running flipbook animation on the specified node.

PARAMETERS

node node cancel flipbook animation for

EXAMPLES

local node = gui.get_node("anim_node")
gui.cancel_flipbook(node)

gui.new_texture()

gui.new_texture(texture,width,height,type,buffer,flip)

Dynamically create a new texture.

PARAMETERS

`texture`	texture id
`width`	texture width
`height`	texture height
`type`	texture type `"rgb"` - RGB `"rgba"` - RGBA `"l"` - LUMINANCE
`buffer`	texture data
`flip`	flip texture vertically

RETURNS

success texture creation was successful

EXAMPLES

How to create a texture and apply it to a new box node:

function init(self)
     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
         -- 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, "orange_tx")
     else
         -- Could not create texture...
         ...
     end
end

gui.delete_texture()

gui.delete_texture(texture)

Delete a dynamically created texture.

PARAMETERS

texture texture id

EXAMPLES

function init(self)
     -- Create a texture.
     if gui.new_texture("temp_tx", 10, 10, "rgb", string.rep('\0', 10 * 10 * 3)) then
         -- Do something with the texture.
         ...

         -- Delete the texture
         gui.delete_texture("temp_tx")
     end
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

`texture`	texture id
`width`	texture width
`height`	texture height
`type`	texture type `"rgb"` - RGB `"rgba"` - RGBA `"l"` - LUMINANCE
`buffer`	texture data
`flip`	flip texture vertically

RETURNS

success setting the data was successful

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

gui.get_font(node)

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

PARAMETERS

node node from which to get the font

RETURNS

font font id

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

`node`	node for which to set the font
`font`	font id

gui.get_layer()

gui.get_layer(node)

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

PARAMETERS

node node from which to get the layer

RETURNS

layer layer id

gui.set_layer()

gui.set_layer(node,layer)

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

PARAMETERS

`node`	node for which to set the layer
`layer`	layer id

gui.get_layout()

gui.get_layout()

gets the scene current layout

PARAMETERS

RETURNS

layout layout id

gui.get_clipping_mode()

gui.get_clipping_mode(node)

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

PARAMETERS

node node from which to get the clipping mode

RETURNS

clipping_mode

clipping mode

gui.CLIPPING_MODE_NONE
gui.CLIPPING_MODE_STENCIL

gui.set_clipping_mode()

gui.set_clipping_mode(node,clipping_mode)

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

PARAMETERS

`node`	node to set clipping mode for
`clipping_mode`	clipping mode to set `gui.CLIPPING_MODE_NONE` `gui.CLIPPING_MODE_STENCIL`

gui.get_clipping_visible()

gui.get_clipping_visible(node)

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 node from which to get the clipping visibility state

RETURNS

visible true or false

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

`node`	node to set clipping visibility for
`visible`	true or false

gui.get_clipping_inverted()

gui.get_clipping_inverted(node)

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

PARAMETERS

node node from which to get the clipping inverted state

RETURNS

inverted true or false

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

`node`	node to set clipping inverted state for
`inverted`	true or false

gui.get_text_metrics_from_node()

gui.get_text_metrics_from_node(node)

Get the text metrics from a text node.

PARAMETERS

node text node to measure text from

RETURNS

metrics

a table with the following fields:

width
height
max_ascent
max_descent

gui.get_text_metrics()

gui.get_text_metrics(font,text,width,line_break,leading,tracking)

Get text metrics given the provided font, text and parameters.

PARAMETERS

`font`	font id
`text`	text to measure
`width`	max-width. Use for line-breaks (default=FLT_MAX)
`line_break`	true to break lines accordingly to width (default=false)
`leading`	scale value for line spacing (default=1)
`tracking`	scale value for letter spacing (default=0)

RETURNS

metrics

a table with the following fields:

width
height
max_ascent
max_descent

gui.get_xanchor()

gui.get_xanchor(node)

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

PARAMETERS

node node to get x-anchor from

RETURNS

anchor

anchor constant

gui.ANCHOR_NONE
gui.ANCHOR_LEFT
gui.ANCHOR_RIGHT

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

`node`	node to set x-anchor for
`anchor`	anchor constant `gui.ANCHOR_NONE` `gui.ANCHOR_LEFT` `gui.ANCHOR_RIGHT`

gui.get_yanchor()

gui.get_yanchor(node)

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

PARAMETERS

node node to get y-anchor from

RETURNS

anchor

anchor constant

gui.ANCHOR_NONE
gui.ANCHOR_TOP
gui.ANCHOR_BOTTOM

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

`node`	node to set y-anchor for
`anchor`	anchor constant `gui.ANCHOR_NONE` `gui.ANCHOR_TOP` `gui.ANCHOR_BOTTOM`

gui.get_pivot()

gui.get_pivot(node)

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

PARAMETERS

node node to get pivot from

RETURNS

pivot

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

gui.set_pivot()

gui.set_pivot(node,pivot)

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

PARAMETERS

`node`	node to set pivot for
`pivot`	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`

gui.get_width()

gui.get_width()

Returns the scene width.

PARAMETERS

RETURNS

width scene width

gui.get_height()

gui.get_height()

Returns the scene height.

PARAMETERS

RETURNS

height scene height

gui.set_slice9()

gui.set_slice9(node,values)

Set the slice9 configuration values for the node.

PARAMETERS

`node`	node to manipulate
`values`	new values

gui.get_slice9()

gui.get_slice9(node)

Returns the slice9 configuration values for the node.

PARAMETERS

node node to manipulate

RETURNS

values configuration values

gui.set_perimeter_vertices()

gui.set_perimeter_vertices(node,vertices)

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

PARAMETERS

`node`	pie node
`vertices`	vertex count

gui.get_perimeter_vertices()

gui.get_perimeter_vertices(node)

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

PARAMETERS

node pie node

RETURNS

vertices vertex count

gui.set_fill_angle()

gui.set_fill_angle(node,angle)

Set the sector angle of a pie node.

PARAMETERS

`node`	node to set the fill angle for
`angle`	sector angle

gui.get_fill_angle()

gui.get_fill_angle(node)

Returns the sector angle of a pie node.

PARAMETERS

node node from which to get the fill angle

RETURNS

angle sector angle

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

`node`	node to set the inner radius for
`radius`	inner radius

gui.get_inner_radius()

gui.get_inner_radius(node)

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

PARAMETERS

node node from where to get the inner radius

RETURNS

radius inner radius

gui.set_outer_bounds()

gui.set_outer_bounds(node,bounds_mode)

Sets the outer bounds mode for a pie node.

PARAMETERS

`node`	node for which to set the outer bounds mode
`bounds_mode`	the outer bounds mode of the pie node: `gui.PIEBOUNDS_RECTANGLE` `gui.PIEBOUNDS_ELLIPSE`

gui.get_outer_bounds()

gui.get_outer_bounds(node)

Returns the outer bounds mode for a pie node.

PARAMETERS

node node from where to get the outer bounds mode

RETURNS

bounds_mode

the outer bounds mode of the pie node:

gui.PIEBOUNDS_RECTANGLE
gui.PIEBOUNDS_ELLIPSE

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

`node`	node for which to set the leading
`leading`	a scaling value for the line spacing (default=1)

gui.get_leading()

gui.get_leading(node)

Returns the leading value for a text node.

PARAMETERS

node node from where to get the leading

RETURNS

leading leading scaling value (default=1)

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

`node`	node for which to set the tracking
`tracking`	a scaling number for the letter spacing (default=0)

gui.get_tracking()

gui.get_tracking(node)

Returns the tracking value of a text node.

PARAMETERS

node node from where to get the tracking

RETURNS

tracking tracking scaling number (default=0)

gui.pick_node()

gui.pick_node(node,x,y)

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

PARAMETERS

`node`	node to be tested for picking
`x`	x-coordinate (see on_input )
`y`	y-coordinate (see on_input )

RETURNS

pickable pick result

gui.is_enabled()

gui.is_enabled(node)

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 node to query

RETURNS

enabled whether the node is enabled or not

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

`node`	node to be enabled/disabled
`enabled`	whether the node should be enabled or not

gui.get_adjust_mode()

gui.get_adjust_mode(node)

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 node from which to get the adjust mode (node)

RETURNS

adjust_mode

the current adjust mode

gui.ADJUST_FIT
gui.ADJUST_ZOOM
gui.ADJUST_STRETCH

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

`node`	node to set adjust mode for
`adjust_mode`	adjust mode to set `gui.ADJUST_FIT` `gui.ADJUST_ZOOM` `gui.ADJUST_STRETCH`

gui.get_size_mode()

gui.get_size_mode(node)

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. Spine, Particle fx and Text nodes will ignore any size mode setting.

PARAMETERS

node node from which to get the size mode (node)

RETURNS

size_mode

the current size mode

gui.SIZE_MODE_MANUAL
gui.SIZE_MODE_AUTO

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. Spine, Particle fx and Text nodes will ignore any size mode setting.

PARAMETERS

`node`	node to set size mode for
`size_mode`	size mode to set `gui.SIZE_MODE_MANUAL` `gui.SIZE_MODE_AUTO`

gui.move_above()

gui.move_above(node,node)

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`	to move
`node`	reference node above which the first node should be moved

gui.move_below()

gui.move_below(node,node)

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`	to move
`node`	reference node below which the first node should be moved

gui.get_parent()

gui.get_parent(node)

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

PARAMETERS

node the node from which to retrieve its parent

RETURNS

parent parent instance or nil

gui.set_parent()

gui.set_parent(node,parent,keep_scene_transform)

Sets the parent node of the specified node.

PARAMETERS

`node`	node for which to set its parent
`parent`	parent node to set
`keep_scene_transform`	optional flag to make the scene position being perserved

gui.clone()

gui.clone(node)

Make a clone instance of a node. This function does not clone the supplied node's children nodes. Use gui.clone_tree for that purpose.

PARAMETERS

node node to clone

RETURNS

clone the cloned node

gui.clone_tree()

gui.clone_tree(node)

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

PARAMETERS

node root node to clone

RETURNS

clones a table mapping node ids to the corresponding cloned nodes

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

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

order rendering order (0-15)

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

`type`	keyboard type `gui.KEYBOARD_TYPE_DEFAULT` `gui.KEYBOARD_TYPE_EMAIL` `gui.KEYBOARD_TYPE_NUMBER_PAD` `gui.KEYBOARD_TYPE_PASSWORD`
`autoclose`	if the keyboard should automatically close when clicking outside

gui.hide_keyboard()

gui.hide_keyboard()

Hides the on-display touch keyboard on the device.

PARAMETERS

gui.reset_keyboard()

gui.reset_keyboard()

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

PARAMETERS

gui.get_position()

gui.get_position(node)

Returns the position of the supplied node.

PARAMETERS

node node to get the position from

RETURNS

position node position

gui.set_position()

gui.set_position(node,position)

Sets the position of the supplied node.

PARAMETERS

`node`	node to set the position for
`position`	new position

gui.get_rotation()

gui.get_rotation(node)

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

PARAMETERS

node node to get the rotation from

RETURNS

rotation node rotation

gui.set_rotation()

gui.set_rotation(node,rotation)

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

PARAMETERS

`node`	node to set the rotation for
`rotation`	new rotation

gui.get_scale()

gui.get_scale(node)

Returns the scale of the supplied node.

PARAMETERS

node node to get the scale from

RETURNS

scale node scale

gui.set_scale()

gui.set_scale(node,scale)

Sets the scaling of the supplied node.

PARAMETERS

`node`	node to set the scale for
`scale`	new scale

gui.get_color()

gui.get_color(node)

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 node to get the color from

RETURNS

color node color

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:

Component	Color value
x	Red value
y	Green value
z	Blue value
w vector4	Alpha value

PARAMETERS

`node`	node to set the color for
`color`	new color

gui.get_outline()

gui.get_outline(node)

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

PARAMETERS

node node to get the outline color from

RETURNS

color outline color

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

`node`	node to set the outline color for
`color`	new outline color

gui.get_shadow()

gui.get_shadow(node)

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

PARAMETERS

node node to get the shadow color from

RETURNS

color node shadow color

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

`node`	node to set the shadow color for
`color`	new shadow color

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

`node`	node to set the size for
`size`	new size

gui.get_size()

gui.get_size(node)

Returns the size of the supplied node.

PARAMETERS

node node to get the size from

RETURNS

size node size

gui.get_screen_position()

gui.get_screen_position(node)

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 node to get the screen position from

RETURNS

position node screen position

gui.play_spine_anim()

gui.play_spine_anim(node,animation_id,playback,[play_properties],[complete_function])

Starts a spine animation.

PARAMETERS

`node`	spine node that should play the animation
`animation_id`	id of the animation to play
`playback`	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`
`[play_properties]`	optional table with properties `blend_duration` number The duration of a linear blend between the current and new animation `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
`[complete_function]`	function to call when the animation has completed

gui.cancel_spine()

gui.cancel_spine(node)

cancel a spine animation

PARAMETERS

node spine node that should cancel its animation

gui.get_spine_bone()

gui.get_spine_bone(node,bone_id)

The returned node can be used for parenting and transform queries. This function has complexity O(n), where n is the number of bones in the spine model skeleton.

PARAMETERS

`node`	spine node to query for bone node
`bone_id`	id of the corresponding bone

RETURNS

bone node corresponding to the spine bone

gui.set_spine_scene()

gui.set_spine_scene(node,spine_scene)

Set the spine scene on a spine node. The spine scene must be mapped to the gui scene in the gui editor.

PARAMETERS

`node`	node to set spine scene for
`spine_scene`	spine scene id

gui.get_spine_scene()

gui.get_spine_scene(node)

Returns the spine scene id of the supplied node. This is currently only useful for spine nodes. The returned spine scene must be mapped to the gui scene in the gui editor.

PARAMETERS

node node to get texture from

RETURNS

spine_scene spine scene id

gui.set_spine_skin()

gui.set_spine_skin(node,spine_skin,[spine_slot])

Sets the spine skin on a spine node.

PARAMETERS

`node`	node to set the spine skin on
`spine_skin`	spine skin id
`[spine_slot]`	optional slot id to only change a specific slot

EXAMPLES

Change skin of a Spine node

function init(self)
  gui.set_spine_skin(gui.get_node("spine_node"), "monster")
end

Change only part of the Spine to a different skin.

function monster_transform_arm(self)
  -- The player is transforming into a monster, begin with changing the arm.
  gui.set_spine_skin(gui.get_node("spine_node"), "monster", "left_arm_slot")
end

gui.get_spine_animation()

gui.get_spine_animation(node)

Gets the playing animation on a spine node

PARAMETERS

node node to get spine skin from

RETURNS

`id`	spine animation id, 0 if no animation is playing

gui.get_spine_skin()

gui.get_spine_skin(node)

Gets the spine skin of a spine node

PARAMETERS

node node to get spine skin from

RETURNS

`id`	spine skin id, 0 if no explicit skin is set

gui.set_spine_cursor()

gui.set_spine_cursor(node,cursor)

This is only useful for spine nodes. The cursor is normalized.

PARAMETERS

`node`	spine node to set the cursor for
`cursor`	cursor value

gui.get_spine_cursor()

gui.get_spine_cursor(node)

This is only useful for spine nodes. Gets the normalized cursor of the animation on a spine node.

PARAMETERS

node spine node to get the cursor for (node)

RETURNS

cursor value number cursor value

gui.get_flipbook_cursor()

gui.get_flipbook_cursor(node)

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

PARAMETERS

node node to get the cursor for (node)

RETURNS

cursor value number cursor value

gui.set_flipbook_cursor()

gui.set_flipbook_cursor(node,cursor)

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

PARAMETERS

`node`	node to set the cursor for
`cursor`	cursor value

gui.get_flipbook_playback_rate()

gui.get_flipbook_playback_rate(node)

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

PARAMETERS

node node to set the cursor for

RETURNS

rate playback rate

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

`node`	node to set the cursor for
`playback_rate`	playback rate

gui.set_spine_playback_rate()

gui.set_spine_playback_rate(node,playback_rate)

This is only useful for spine nodes. Sets the playback rate of the animation on a spine node. Must be positive.

PARAMETERS

`node`	spine node to set the cursor for
`playback_rate`	playback rate

gui.get_spine_playback_rate()

gui.get_spine_playback_rate(node)

This is only useful for spine nodes. Gets the playback rate of the animation on a spine node.

PARAMETERS

node spine node to set the cursor for

RETURNS

rate playback rate

gui.new_particlefx_node()

gui.new_particlefx_node(pos,particlefx)

Dynamically create a particle fx node.

PARAMETERS

`pos`	node position
`particlefx`	particle fx resource name

RETURNS

node new particle fx node

gui.play_particlefx()

gui.play_particlefx(node,[emitter_state_function])

Plays the paricle fx for a gui node

PARAMETERS

node node to play particle fx for

[emitter_state_function]

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

EXAMPLES

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

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

gui.stop_particlefx(node)

Stops the particle fx for a gui node

PARAMETERS

node node to stop particle fx for

gui.set_particlefx()

gui.set_particlefx(node,particlefx)

Set the paricle fx for a gui node

PARAMETERS

`node`	node to set particle fx for
`particlefx`	particle fx id

gui.get_particlefx()

gui.get_particlefx(node)

Get the paricle fx for a gui node

PARAMETERS

node node to get particle fx for

RETURNS

particle fx id

gui.get_inherit_alpha()

gui.get_inherit_alpha(node)

gets the node inherit alpha state

PARAMETERS

node node from which to get the inherit alpha state

gui.set_inherit_alpha()

gui.set_inherit_alpha(node,inherit_alpha)

sets the node inherit alpha state

PARAMETERS

`node`	node from which to set the inherit alpha state
`inherit_alpha`	true or false

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

self reference to the script state to be used for storing data

EXAMPLES

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

final()

final(self)

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.

PARAMETERS

self reference to the script state to be used for storing data

EXAMPLES

function final(self)
    -- report finalization
    msg.post("my_friend_instance", "im_dead", {my_stats = self.some_value})
end

update()

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

`self`	reference to the script state to be used for storing data
`dt`	the time-step of the frame update

EXAMPLES

This example demonstrates how to 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.

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

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

`self`	reference to the script state to be used for storing data
`message_id`	id of the received message
`message`	a table containing the message data

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:

Field	Description
`value`	The amount of input given by the user. This is usually 1 for buttons and 0-1 for analogue inputs. This is not present for mouse movement.
`pressed`	If the input was pressed this frame. This is not present for mouse movement.
`released`	If the input was released this frame. This is not present for mouse movement.
`repeated`	If the input was repeated this frame. This is similar to how a key on a keyboard is repeated when you hold it down. This is not present for mouse movement.
`x`	The x value of a pointer device, if present.
`y`	The y value of a pointer device, if present.
`screen_x`	The screen space x value of a pointer device, if present.
`screen_y`	The screen space y value of a pointer device, if present.
`dx`	The change in x value of a pointer device, if present.
`dy`	The change in y value of a pointer device, if present.
`screen_dx`	The change in screen space x value of a pointer device, if present.
`screen_dy`	The change in screen space y value of a pointer device, if present.
`gamepad`	The index of the gamepad device that provided the input.
`touch`	List of touch input, one element per finger, if present. See table below about touch input

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

PARAMETERS

`self`	reference to the script state to be used for storing data
`action_id`	id of the received input action, as mapped in the input_binding-file
`action`	a table containing the input data, see above for a description

RETURNS

[consume] optional boolean to signal if the input should be consumed (not passed on to others) or not, default is false

EXAMPLES

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_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

self reference to the script state to be used for storing data

EXAMPLES

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

Messages

layout_changed

reports a layout change

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

`id`	the id of the layout the engine is changing to
`previous_id`	the id of the layout the engine is changing from

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

material

The material used when rendering the gui. The type of the property is hash.

hash gui material

EXAMPLES

How to set material using a script property (see resource.material)

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

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

GUI API documentation

Functions

Constants