Functions

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.

gui.animate

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

property

string | constant 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

vector3 | vector4 target property value

easing

constant | vector easing to use during animation.
Either specify one of the gui.EASING_* constants or provide a
vector with a custom curve. See the animation guide for more information.

duration

number duration of the animation in seconds.

[delay]

number delay before the animation starts in seconds.

[complete_function]

function(self, node) function to call when the
animation has completed

[playback]

constant playback mode

gui.PLAYBACK_ONCE_FORWARD

gui.PLAYBACK_ONCE_BACKWARD

gui.PLAYBACK_ONCE_PINGPONG

gui.PLAYBACK_LOOP_FORWARD

gui.PLAYBACK_LOOP_BACKWARD

gui.PLAYBACK_LOOP_PINGPONG

node

node node to animate

property

string | constant 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

vector3 | vector4 target property value

easing

constant | vector easing to use during animation.
Either specify one of the gui.EASING_* constants or provide a
vector with a custom curve. See the animation guide for more information.

duration

number duration of the animation in seconds.

[delay]

number delay before the animation starts in seconds.

[complete_function]

function(self, node) function to call when the
animation has completed

[playback]

constant playback mode

gui.PLAYBACK_ONCE_FORWARD

gui.PLAYBACK_ONCE_BACKWARD

gui.PLAYBACK_ONCE_PINGPONG

gui.PLAYBACK_LOOP_FORWARD

gui.PLAYBACK_LOOP_BACKWARD

gui.PLAYBACK_LOOP_PINGPONG

Examples

How to start a simple color animation, where the node fades in to white during 0.5 seconds:

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:

localfunctionon_animation_done(self,node)-- fade out node, but wait 2 seconds before the animation startsgui.animate(node,gui.PROP_COLOR,vmath.vector4(0,0,0,0),gui.EASING_OUTQUAD,0.5,2.0)endfunctioninit(self)-- fetch the node we want to animatelocalmy_node=gui.get_node("my_node")-- node is initially set to fully transparentgui.set_color(my_node,vmath.vector4(0,0,0,0))-- animate the node immediately and call on_animation_done when the animation has completedgui.animate(my_node,gui.PROP_COLOR,vmath.vector4(1,1,1,1),gui.EASING_INOUTQUAD,0.5,0.0,on_animation_done)end

gui.cancel_animation

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

Parameters

node

node node that should have its animation canceled

property

string | constant property for which the animation should be canceled

"position"

"rotation"

"scale"

"color"

"outline"

"shadow"

"size"

"fill_angle" (pie)

"inner_radius" (pie)

"slice9" (slice9)

node

node node that should have its animation canceled

property

string | constant 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:

localnode=gui.get_node("my_node")-- animate to new positionlocalpos=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.cancel_flipbook

gui.cancel_flipbook(node)

Cancels any running flipbook animation on the specified node.

Parameters

node

node node cancel flipbook animation for

node

node node cancel flipbook animation for

Examples

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

gui.cancel_spine

gui.cancel_spine(node)

Parameters

node

node spine node that should cancel its animation

node

node spine node that should cancel its animation

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

node

node node to clone

Returns

clone

node the cloned node

clone

node 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

node root node to clone

node

node root node to clone

Returns

clones

table a table mapping node ids to the corresponding cloned nodes

clones

table a table mapping node ids to the corresponding cloned nodes

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

node

node node to delete

Examples

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

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

gui.delete_texture

gui.delete_texture(texture)

Delete a dynamically created texture.

Parameters

texture

string | hash texture id

texture

string | hash texture id

Examples

functioninit(self)-- Create a texture.ifgui.new_texture("temp_tx",10,10,"rgb",string.rep('\0',10*10*3))then-- Do something with the texture....-- Delete the texturegui.delete_texture("temp_tx")endend

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

node

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

Returns

adjust_mode

constant the current adjust mode

gui.ADJUST_FIT

gui.ADJUST_ZOOM

gui.ADJUST_STRETCH

adjust_mode

constant the current adjust mode

gui.ADJUST_FIT

gui.ADJUST_ZOOM

gui.ADJUST_STRETCH

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 node from which to get the blend mode

node

node node from which to get the blend mode

Returns

blend_mode

constant blend mode

gui.BLEND_ALPHA

gui.BLEND_ADD

gui.BLEND_ADD_ALPHA

gui.BLEND_MULT

blend_mode

constant blend mode

gui.BLEND_ALPHA

gui.BLEND_ADD

gui.BLEND_ADD_ALPHA

gui.BLEND_MULT

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

node

node node from which to get the clipping inverted state

Returns

inverted

boolean true or false

inverted

boolean true or false

gui.get_clipping_mode

gui.get_clipping_mode(node)

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

Parameters

node

node node from which to get the clipping mode

node

node node from which to get the clipping mode

Returns

clipping_mode

constant clipping mode

gui.CLIPPING_MODE_NONE

gui.CLIPPING_MODE_STENCIL

clipping_mode

constant clipping mode

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

node

node node from which to get the clipping visibility state

Returns

visible

boolean true or false

visible

boolean true or false

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

node

node node to get the color from

Returns

color

vector4 node color

color

vector4 node color

gui.get_fill_angle

gui.get_fill_angle(node)

Returns the sector angle of a pie node.

Parameters

node

node node from which to get the fill angle

node

node node from which to get the fill angle

Returns

angle

number sector angle

angle

number sector angle

gui.get_flipbook

gui.get_flipbook(node)

Get node flipbook animation.

Parameters

node

node node to get flipbook animation from

node

node node to get flipbook animation from

Returns

animation

hash animation id

animation

hash animation id

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.

Returns

gui.get_texture

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

node

node node to get texture from

Returns

texture

hash texture id

texture

hash texture id

gui.get_tracking

gui.get_tracking(node)

Returns the tracking value of a text node.

Parameters

node

node node from where to get the tracking

node

node node from where to get the tracking

Returns

tracking

number tracking scaling number (default=0)

tracking

number tracking scaling number (default=0)

gui.get_width

gui.get_width()

Returns the scene width.

Returns

width

number scene width

width

number scene width

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

node

node node to get x-anchor from

Returns

anchor

constant anchor constant

gui.ANCHOR_NONE

gui.ANCHOR_LEFT

gui.ANCHOR_RIGHT

anchor

constant 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 node to get y-anchor from

node

node node to get y-anchor from

Returns

anchor

constant anchor constant

gui.ANCHOR_NONE

gui.ANCHOR_TOP

gui.ANCHOR_BOTTOM

anchor

constant anchor constant

gui.ANCHOR_NONE

gui.ANCHOR_TOP

gui.ANCHOR_BOTTOM

gui.hide_keyboard

gui.hide_keyboard()

Hides the on-display touch keyboard on the device.

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

node

node node to query

Returns

enabled

boolean whether the node is enabled or not

enabled

boolean whether the node is enabled or not

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

node to move

node

node | nil reference node above which the first node should be moved

node

node to move

node

node | nil 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

node to move

node

node | nil reference node below which the first node should be moved

node

node to move

node

node | nil reference node below which the first node should be moved

gui.new_box_node

gui.new_box_node(pos, size)

Dynamically create a new box node.

Parameters

pos

vector3 | vector4 node position

size

vector3 node size

pos

vector3 | vector4 node position

size

vector3 node size

Returns

node

node new box node

node

node new box node

gui.new_particlefx_node

gui.new_particlefx_node(pos, particlefx)

Dynamically create a particle fx node.

Parameters

pos

vector3 | vector4 node position

particlefx

hash | string particle fx resource name

pos

vector3 | vector4 node position

particlefx

hash | string particle fx resource name

Returns

node

node new particle fx node

node

node new particle fx node

gui.new_pie_node

gui.new_pie_node(pos, size)

Dynamically create a new pie node.

Parameters

pos

vector3 | vector4 node position

size

vector3 node size

pos

vector3 | vector4 node position

size

vector3 node size

Returns

node

node new box node

node

node new box node

gui.new_spine_node

gui.new_spine_node(pos, spine_scene)

Dynamically create a new spine node.

Parameters

pos

vector3 | vector4 node position

spine_scene

string | hash spine scene id

pos

vector3 | vector4 node position

spine_scene

string | hash spine scene id

Returns

node

node new spine node

node

node new spine node

gui.new_text_node

gui.new_text_node(pos, text)

Dynamically create a new text node.

Parameters

pos

vector3 | vector4 node position

text

string node text

pos

vector3 | vector4 node position

text

string node text

Returns

node

node new text node

node

node new text node

gui.new_texture

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

Dynamically create a new texture.

Parameters

texture

string | hash texture id

width

number texture width

height

number texture height

type

string | constant texture type

"rgb" - RGB

"rgba" - RGBA

"l" - LUMINANCE

buffer

string texture data

flip

boolean flip texture vertically

texture

string | hash texture id

width

number texture width

height

number texture height

type

string | constant texture type

"rgb" - RGB

"rgba" - RGBA

"l" - LUMINANCE

buffer

string texture data

flip

boolean flip texture vertically

Returns

success

boolean texture creation was successful

success

boolean texture creation was successful

Examples

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

functioninit(self)localw=200localh=300-- A nice orange. String with the RGB values.localorange=string.char(0xff)..string.char(0x80)..string.char(0x10)-- Create the texture. Repeat the color string for each pixel.ifgui.new_texture("orange_tx",w,h,"rgb",string.rep(orange,w*h))then-- Create a box node and apply the texture to it.localn=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......endend

Returns

gui.play_flipbook

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

animation

string | hash animation id

[complete_function]

function(self, node) optional function to call when the animation has completed

self

object The current object.

node

node The node that is animated.

node

node node to set animation for

animation

string | hash animation id

[complete_function]

function(self, node) optional function to call when the animation has completed

self

object The current object.

node

node The node that is animated.

Examples

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

localfunctionanim_callback(self,node)-- Take action after animation has played.endfunctioninit(self)-- Create a new node and set the texture to a flipbook animationlocalnode=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 atlaslocalnode=gui.get_node("button_node")gui.set_texture(node,"gui_sprites")gui.play_flipbook(node,"button")

gui.play_particlefx

gui.play_particlefx(node, [emitter_state_function])

Plays the paricle fx for a gui node

Parameters

node

node node to play particle fx for

[emitter_state_function]

function(self, node, emitter, state) optional callback function that will be called when an emitter attached to this particlefx changes state.

self

object The current object

id

hash The id of the particle fx component

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

node

node node to play particle fx for

[emitter_state_function]

function(self, node, emitter, state) optional callback function that will be called when an emitter attached to this particlefx changes state.

self

object The current object

id

hash The id of the particle fx component

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

gui.set_inner_radius

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

Parameters

node

node node to set the inner radius for

radius

number inner radius

node

node node to set the inner radius for

radius

number inner radius

gui.set_layer

gui.set_layer(node, layer)

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

Parameters

node

node node for which to set the layer

layer

string | hash layer id

node

node node for which to set the layer

layer

string | hash layer id

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 node for which to set the leading

leading

number a scaling value for the line spacing (default=1)

node

node node for which to set the leading

leading

number a scaling value for the line spacing (default=1)

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 node to set line-break for

line_break

boolean true or false

node

node node to set line-break for

line_break

boolean true or false

gui.set_outer_bounds

gui.set_outer_bounds(node, bounds_mode)

Sets the outer bounds mode for a pie node.

Parameters

node

node node for which to set the outer bounds mode

bounds_mode

constant the outer bounds mode of the pie node:

gui.PIEBOUNDS_RECTANGLE

gui.PIEBOUNDS_ELLIPSE

node

node node for which to set the outer bounds mode

bounds_mode

constant the outer bounds mode of the pie node:

gui.PIEBOUNDS_RECTANGLE

gui.PIEBOUNDS_ELLIPSE

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 node to set the outline color for

color

vector3 | vector4 new outline color

node

node node to set the outline color for

color

vector3 | vector4 new outline color

gui.set_parent

gui.set_parent(node, parent, keep_scene_transform)

Sets the parent node of the specified node.

Parameters

node

node node for which to set its parent

parent

node parent node to set

keep_scene_transform

boolean optional flag to make the scene position being perserved

node

node node for which to set its parent

parent

node parent node to set

keep_scene_transform

boolean optional flag to make the scene position being perserved

gui.set_particlefx

gui.set_particlefx(node, particlefx)

Set the paricle fx for a gui node

Parameters

node

node node to set particle fx for

particlefx

hash | string particle fx id

node

node node to set particle fx for

particlefx

hash | string particle fx id

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

node pie node

vertices

number vertex count

node

node pie node

vertices

number vertex count

gui.set_pivot

gui.set_pivot(node, pivot)

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

Parameters

node

node node to set pivot for

pivot

constant pivot constant

gui.PIVOT_CENTER

gui.PIVOT_N

gui.PIVOT_NE

gui.PIVOT_E

gui.PIVOT_SE

gui.PIVOT_S

gui.PIVOT_SW

gui.PIVOT_W

gui.PIVOT_NW

node

node node to set pivot for

pivot

constant pivot constant

gui.PIVOT_CENTER

gui.PIVOT_N

gui.PIVOT_NE

gui.PIVOT_E

gui.PIVOT_SE

gui.PIVOT_S

gui.PIVOT_SW

gui.PIVOT_W

gui.PIVOT_NW

gui.set_position

gui.set_position(node, position)

Sets the position of the supplied node.

Parameters

node

node node to set the position for

position

vector3 | vector4 new position

node

node node to set the position for

position

vector3 | vector4 new position

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

number rendering order (0-15)

order

number rendering order (0-15)

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 node to set the rotation for

rotation

vector3 | vector4 new rotation

node

node node to set the rotation for

rotation

vector3 | vector4 new rotation

gui.set_scale

gui.set_scale(node, scale)

Sets the scaling of the supplied node.

Parameters

node

node node to set the scale for

scale

vector3 | vector4 new scale

node

node node to set the scale for

scale

vector3 | vector4 new scale

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 node to set the shadow color for

color

vector3 | vector4 new shadow color

node

node node to set the shadow color for

color

vector3 | vector4 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 node to set the size for

size

vector3 | vector4 new size

node

node node to set the size for

size

vector3 | vector4 new size

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.

Parameters

node

node node to set size mode for

size_mode

constant size mode to set

gui.SIZE_MODE_MANUAL

gui.SIZE_MODE_AUTO

node

node node to set size mode for

size_mode

constant size mode to set

gui.SIZE_MODE_MANUAL

gui.SIZE_MODE_AUTO

gui.set_slice9

gui.set_slice9(node, values)

Set the slice9 configuration values for the node.

Parameters

node

node node to manipulate

values

vector4 new values

node

node node to manipulate

values

vector4 new values

gui.set_spine_cursor

gui.set_spine_cursor(node, cursor)

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

Parameters

node

node spine node to set the cursor for

cursor

number cursor value

node

node spine node to set the cursor for

cursor

number cursor value

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

node spine node to set the cursor for

playback_rate

number playback rate

node

node spine node to set the cursor for

playback_rate

number playback rate

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.

Examples

functionmonster_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.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 node to set text for

text

string text to set

node

node node to set text for

text

string text to set

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.

Examples

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.

localw=200localh=300-- A nice orange. String with the RGB values.localorange=string.char(0xff)..string.char(0x80)..string.char(0x10)-- Create the texture. Repeat the color string for each pixel.ifgui.new_texture("orange_tx",w,h,"rgb",string.rep(orange,w*h))thenlocalnode=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

texture

string | hash texture id

width

number texture width

height

number texture height

type

string | constant texture type

"rgb" - RGB

"rgba" - RGBA

"l" - LUMINANCE

buffer

string texture data

flip

boolean flip texture vertically

texture

string | hash texture id

width

number texture width

height

number texture height

type

string | constant texture type

"rgb" - RGB

"rgba" - RGBA

"l" - LUMINANCE

buffer

string texture data

flip

boolean flip texture vertically

Returns

success

boolean setting the data was successful

success

boolean setting the data was successful

Examples

functioninit(self)localw=200localh=300-- Create a dynamic texture, all white.ifgui.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.localn=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.localorange=string.char(0xff)..string.char(0x80)..string.char(0x10)ifgui.set_texture_data("dynamic_tx",w,h,"rgb",string.rep(orange,w*h))then-- Go on and to more stuff...endelse-- Something went wrong...endend

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 node for which to set the tracking

tracking

number a scaling number for the letter spacing (default=0)

node

node node for which to set the tracking

tracking

number a scaling number for the letter spacing (default=0)

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 node to set x-anchor for

anchor

constant anchor constant

gui.ANCHOR_NONE

gui.ANCHOR_LEFT

gui.ANCHOR_RIGHT

node

node node to set x-anchor for

anchor

constant anchor constant

gui.ANCHOR_NONE

gui.ANCHOR_LEFT

gui.ANCHOR_RIGHT

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 node to set y-anchor for

anchor

constant anchor constant

gui.ANCHOR_NONE

gui.ANCHOR_TOP

gui.ANCHOR_BOTTOM

node

node node to set y-anchor for

anchor

constant anchor constant

gui.ANCHOR_NONE

gui.ANCHOR_TOP

gui.ANCHOR_BOTTOM

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

constant keyboard type

gui.KEYBOARD_TYPE_DEFAULT

gui.KEYBOARD_TYPE_EMAIL

gui.KEYBOARD_TYPE_NUMBER_PAD

gui.KEYBOARD_TYPE_PASSWORD

autoclose

boolean if the keyboard should automatically close when clicking outside

type

constant keyboard type

gui.KEYBOARD_TYPE_DEFAULT

gui.KEYBOARD_TYPE_EMAIL

gui.KEYBOARD_TYPE_NUMBER_PAD

gui.KEYBOARD_TYPE_PASSWORD

autoclose

boolean if the keyboard should automatically close when clicking outside

gui.stop_particlefx

gui.stop_particlefx(node)

Stops the particle fx for a gui node

Parameters

node

node node to stop particle fx for

node

node node to stop particle fx for

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

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

self

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

Examples

functioninit(self)-- set up useful dataself.my_value=1end

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.

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

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

action_id

hash id of the received input action, as mapped in the input_binding-file

action

table a table containing the input data, see above for a description

self

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

action_id

hash id of the received input action, as mapped in the input_binding-file

action

table a table containing the input data, see above for a description

Returns

[consume]

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

[consume]

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

Examples

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

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

message_id

hash id of the received message

message

table a table containing the message data

self

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

message_id

hash id of the received message

message

table a table containing the message data

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.

Examples

update

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

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

dt

number the time-step of the frame update

self

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

dt

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

functioninit(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 farself.current_score=0-- keep track of the target score we should count up toself.target_score=0-- how fast we will update the score, in score/secondself.score_update_speed=1endfunctionupdate(self,dt)-- check if target score is more than current scoreifself.current_score<self.target_score-- increment current score according to the speedself.current_score=self.current_score+dt*self.score_update_speed-- check if we went past the target score, clamp current score in that caseifself.current_score>self.target_scorethenself.current_score=self.target_scoreend-- update the score text nodegui.set_text(self.score_node,""..math.floor(self.current_score))endendfunctionon_message(self,message_id,message,sender)-- check the messageifmessage_id==hash("set_score")thenself.target_score=message.scoreendend

Messages

layout_changed

"layout_changed", { id=…, previous_id=… }

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

Examples

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

gui.ANCHOR_LEFT

gui.ANCHOR_RIGHT

gui.ANCHOR_TOP

gui.BLEND_ADD

gui.BLEND_ADD_ALPHA

gui.BLEND_ALPHA

gui.BLEND_MULT

gui.CLIPPING_MODE_NONE

gui.CLIPPING_MODE_STENCIL

gui.EASING_INBACK

gui.EASING_INBOUNCE

gui.EASING_INCIRC

gui.EASING_INCUBIC

gui.EASING_INELASTIC

gui.EASING_INEXPO

gui.EASING_INOUTBACK

gui.EASING_INOUTBOUNCE

gui.EASING_INOUTCIRC

gui.EASING_INOUTCUBIC

gui.EASING_INOUTELASTIC

gui.EASING_INOUTEXPO

gui.EASING_INOUTQUAD

gui.EASING_INOUTQUART

gui.EASING_INOUTQUINT

gui.EASING_INOUTSINE

gui.EASING_INQUAD

gui.EASING_INQUART

gui.EASING_INQUINT

gui.EASING_INSINE

gui.EASING_LINEAR

gui.EASING_OUTBACK

gui.EASING_OUTBOUNCE

gui.EASING_OUTCIRC

gui.EASING_OUTCUBIC

gui.EASING_OUTELASTIC

gui.EASING_OUTEXPO

gui.EASING_OUTINBACK

gui.EASING_OUTINBOUNCE

gui.EASING_OUTINCIRC

gui.EASING_OUTINCUBIC

gui.EASING_OUTINELASTIC

gui.EASING_OUTINEXPO

gui.EASING_OUTINQUAD

gui.EASING_OUTINQUART

gui.EASING_OUTINQUINT

gui.EASING_OUTINSINE

gui.EASING_OUTQUAD

gui.EASING_OUTQUART

gui.EASING_OUTQUINT

gui.EASING_OUTSINE

gui.KEYBOARD_TYPE_DEFAULT

gui.KEYBOARD_TYPE_EMAIL

gui.KEYBOARD_TYPE_NUMBER_PAD

gui.KEYBOARD_TYPE_PASSWORD

gui.PIEBOUNDS_ELLIPSE

gui.PIEBOUNDS_RECTANGLE

gui.PIVOT_CENTER

gui.PIVOT_E

gui.PIVOT_N

gui.PIVOT_NE

gui.PIVOT_NW

gui.PIVOT_S

gui.PIVOT_SE

gui.PIVOT_SW

gui.PIVOT_W

gui.PLAYBACK_LOOP_BACKWARD

gui.PLAYBACK_LOOP_FORWARD

gui.PLAYBACK_LOOP_PINGPONG

gui.PLAYBACK_ONCE_BACKWARD

gui.PLAYBACK_ONCE_FORWARD

gui.PLAYBACK_ONCE_PINGPONG

gui.PROP_COLOR

gui.PROP_FILL_ANGLE

gui.PROP_INNER_RADIUS

gui.PROP_OUTLINE

gui.PROP_POSITION

gui.PROP_ROTATION

gui.PROP_SCALE

gui.PROP_SHADOW

gui.PROP_SIZE

gui.PROP_SLICE9

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