GUI core hooks, functions, messages, properties and constants for creation and manipulation of GUI nodes. The "gui" namespace is accessible only from gui scripts.
called when a gui component is finalized
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.
self -
object reference to the script state to be used for storing data
function final(self) -- report finalization msg.post("my_friend_instance", "im_dead", {my_stats = self.some_value}) end
fit adjust mode
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.
stretch adjust mode
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.
zoom adjust mode
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.
bottom y-anchor
left x-anchor
right x-anchor
top y-anchor
additive blending
additive alpha blending
alpha blending
multiply blending
clipping mode none
clipping mode stencil
in-back
in-bounce
in-circlic
in-cubic
in-elastic
in-exponential
in-out-back
in-out-bounce
in-out-circlic
in-out-cubic
in-out-elastic
in-out-exponential
in-out-quadratic
in-out-quartic
in-out-quintic
in-out-sine
in-quadratic
in-quartic
in-quintic
in-sine
linear interpolation
out-back
out-bounce
out-circlic
out-cubic
out-elastic
out-exponential
out-in-back
out-in-bounce
out-in-circlic
out-in-cubic
out-in-elastic
out-in-exponential
out-in-quadratic
out-in-quartic
out-in-quintic
out-in-sine
out-quadratic
out-quartic
out-quintic
out-sine
default keyboard
email keyboard
number input keyboard
password keyboard
elliptical pie node bounds
rectangular pie node bounds
center pivor
east pivot
north pivot
north-east pivot
north-west pivot
south pivot
south-east pivot
south-west pivot
west pivot
loop backward
loop forward
ping pong loop
once backward
once forward
once forward and then backward
color property
fill_angle property
inner_radius property
outline color property
position property
rotation property
scale property
shadow color property
size property
slice9 property
automatic size mode
The size of the node is determined by the currently assigned texture.
manual size mode
The size of the node is determined by the size set in the editor, the constructor or by gui.set_size()
animates a node property
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.
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_POSITIONgui.PROP_ROTATIONgui.PROP_SCALEgui.PROP_COLORgui.PROP_OUTLINEgui.PROP_SHADOWgui.PROP_SIZEgui.PROP_FILL_ANGLEgui.PROP_INNER_RADIUSgui.PROP_SLICE9to -
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_FORWARDgui.PLAYBACK_ONCE_BACKWARDgui.PLAYBACK_ONCE_PINGPONGgui.PLAYBACK_LOOP_FORWARDgui.PLAYBACK_LOOP_BACKWARDgui.PLAYBACK_LOOP_PINGPONGHow 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
cancels an ongoing animation
If an animation of the specified node is currently running (started by gui.animate), it will immediately be canceled.
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)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")
cancel a node flipbook animation
Cancels any running flipbook animation on the specified node.
node -
node node cancel flipbook animation for
local node = gui.get_node("anim_node") gui.cancel_flipbook(node)
cancel a spine animation
node -
node spine node that should cancel its animation
clone a 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.
node -
node node to clone
clone -
node the cloned node
clone a node including its children
Make a clone instance of a node and all its children. Use gui.clone to clone a node excluding its children.
node -
node root node to clone
clones -
table a table mapping node ids to the corresponding cloned nodes
deletes a node
Deletes the specified node. Any child nodes of the specified node will be recursively deleted.
node -
node node to delete
Delete a particular node and any child nodes it might have:
local node = gui.get_node("my_node") gui.delete_node(node)
delete texture
Delete a dynamically created texture.
texture -
string | hash texture id
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
gets the node adjust mode
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.
node -
node node from which to get the adjust mode (node)
adjust_mode -
constant the current adjust mode
gui.ADJUST_FITgui.ADJUST_ZOOMgui.ADJUST_STRETCHgets the node blend mode
Returns the blend mode of a node. Blend mode defines how the node will be blended with the background.
node -
node node from which to get the blend mode
blend_mode -
constant blend mode
gui.BLEND_ALPHAgui.BLEND_ADDgui.BLEND_ADD_ALPHAgui.BLEND_MULTgets node clipping inverted state
If node is set as an inverted clipping node, it will clip anything inside as opposed to outside.
node -
node node from which to get the clipping inverted state
inverted -
boolean true or false
gets the node clipping mode
Clipping mode defines how the node will clipping it's children nodes
node -
node node from which to get the clipping mode
clipping_mode -
constant clipping mode
gui.CLIPPING_MODE_NONEgui.CLIPPING_MODE_STENCILgets node clipping visibility state
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.
node -
node node from which to get the clipping visibility state
visible -
boolean true or false
gets the node color
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 |
node -
node node to get the color from
color -
vector4 node color
gets the angle for the filled pie sector
Returns the sector angle of a pie node.
node -
node node from which to get the fill angle
angle -
number sector angle
gets the node flipbook animation
Get node flipbook animation.
node -
node node to get flipbook animation from
animation -
hash animation id
gets the normalized cursor of the animation on a node with flipbook animation
This is only useful nodes with flipbook animations. Gets the normalized cursor of the flipbook animation on a node.
node -
node to get the cursor for (node)
cursor -
value number cursor value
gets the playback rate of the flipbook animation on a node
This is only useful nodes with flipbook animations. Gets the playback rate of the flipbook animation on a node.
node -
node node to set the cursor for
rate -
number playback rate
gets the node font
This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.
node -
node node from which to get the font
font -
hash font id
gets the scene height
Returns the scene height.
height -
number scene height
gets the id of the specified node
Retrieves the id of the specified node.
node -
node the node to retrieve the id from
id -
hash the id of the node
Gets the id of a node:
local node = gui.get_node("my_node") local id = gui.get_id(node) print(id) --> hash: [my_node]
gets the index of the specified 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.
node -
node the node to retrieve the id from
index -
number the index of the node
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
gets the node inherit alpha state
node -
node node from which to get the inherit alpha state
gets the pie inner radius
Returns the inner radius of a pie node. The radius is defined along the x-axis.
node -
node node from where to get the inner radius
radius -
number inner radius
gets the node layer
The layer must be mapped to the gui scene in the gui editor.
node -
node node from which to get the layer
layer -
hash layer id
gets the scene current layout
layout -
hash layout id
gets the leading of the text node
Returns the leading value for a text node.
node -
node node from where to get the leading
leading -
number leading scaling value (default=1)
get line-break mode
Returns whether a text node is in line-break mode or not. This is only useful for text nodes.
node -
node node from which to get the line-break for
line_break -
boolean true or false
gets the node with the specified id
Retrieves the node with the specified id.
id -
string | hash id of the node to retrieve
instance -
node a new node instance
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)
gets the pie outer bounds mode
Returns the outer bounds mode for a pie node.
node -
node node from where to get the outer bounds mode
bounds_mode -
constant the outer bounds mode of the pie node:
gui.PIEBOUNDS_RECTANGLEgui.PIEBOUNDS_ELLIPSEgets the node outline color
Returns the outline color of the supplied node. See gui.get_color for info how vectors encode color values.
node -
node node to get the outline color from
color -
vector4 outline color
gets the parent of the specified node
Returns the parent node of the specified node.
If the supplied node does not have a parent, nil is returned.
node -
node the node from which to retrieve its parent
parent -
node parent instance or nil
Gets a particle fx
Get the paricle fx for a gui node
node -
node node to get particle fx for
[type:hash] -
particle fx id
gets the number of generated vertices around the perimeter
Returns the number of generated vertices around the perimeter of a pie node.
node -
node pie node
vertices -
number vertex count
gets the pivot of a node
The pivot specifies how the node is drawn and rotated from its position.
node -
node node to get pivot from
pivot -
constant pivot constant
gui.PIVOT_CENTERgui.PIVOT_Ngui.PIVOT_NEgui.PIVOT_Egui.PIVOT_SEgui.PIVOT_Sgui.PIVOT_SWgui.PIVOT_Wgui.PIVOT_NWgets the node position
Returns the position of the supplied node.
node -
node node to get the position from
position -
vector3 node position
gets the node rotation
Returns the rotation of the supplied node. The rotation is expressed in degree Euler angles.
node -
node node to get the rotation from
rotation -
vector3 node rotation
gets the node scale
Returns the scale of the supplied node.
node -
node node to get the scale from
scale -
vector3 node scale
gets the node screen position
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.
node -
node node to get the screen position from
position -
vector3 node screen position
gets the node shadow color
Returns the shadow color of the supplied node. See gui.get_color for info how vectors encode color values.
node -
node node to get the shadow color from
color -
vector4 node shadow color
gets the node size
Returns the size of the supplied node.
node -
node node to get the size from
size -
vector3 node size
gets the node size mode
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.
node -
node node from which to get the size mode (node)
size_mode -
constant the current size mode
gui.SIZE_MODE_MANUALgui.SIZE_MODE_AUTOget the slice9 values for the node
Returns the slice9 configuration values for the node.
node -
node node to manipulate
values -
vector4 configuration values
gets the playing animation on a spine node
Gets the playing animation on a spine node
node -
node node to get spine skin from
id -
hash spine animation id, 0 if no animation is playing
retrieve the GUI node corresponding to a spine skeleton bone
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.
node -
node spine node to query for bone node
bone_id -
string | hash id of the corresponding bone
bone -
node node corresponding to the spine bone
gets the normalized cursor of the animation on a spine node
This is only useful for spine nodes. Gets the normalized cursor of the animation on a spine node.
node -
spine node to get the cursor for (node)
cursor -
value number cursor value
gets the playback rate of the animation on a spine node
This is only useful for spine nodes. Gets the playback rate of the animation on a spine node.
node -
node spine node to set the cursor for
rate -
number playback rate
gets the spine scene of a 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.
node -
node node to get texture from
spine_scene -
hash spine scene id
gets the skin of a spine node
Gets the spine skin of a spine node
node -
node node to get spine skin from
id -
hash spine skin id, 0 if no explicit skin is set
gets the node text
Returns the text value of a text node. This is only useful for text nodes.
node -
node node from which to get the text
text -
string text value
get text metrics
Get text metrics given the provided font, text and parameters.
font -
string | hash font id
text -
string text to measure
width -
number max-width. Use for line-breaks (default=FLT_MAX)
line_break -
boolean true to break lines accordingly to width (default=false)
leading -
number scale value for line spacing (default=1)
tracking -
number scale value for letter spacing (default=0)
metrics -
table a table with the following fields:
get text metrics from node
Get the text metrics from a text node.
node -
node text node to measure text from
metrics -
table a table with the following fields:
gets node 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.
node -
node node to get texture from
texture -
hash texture id
gets the tracking of the text node
Returns the tracking value of a text node.
node -
node node from where to get the tracking
tracking -
number tracking scaling number (default=0)
gets the scene width
Returns the scene width.
width -
number scene width
gets the x-anchor of a node
The x-anchor specifies how the node is moved when the game is run in a different resolution.
node -
node node to get x-anchor from
anchor -
constant anchor constant
gui.ANCHOR_NONEgui.ANCHOR_LEFTgui.ANCHOR_RIGHTgets the y-anchor of a node
The y-anchor specifies how the node is moved when the game is run in a different resolution.
node -
node node to get y-anchor from
anchor -
constant anchor constant
gui.ANCHOR_NONEgui.ANCHOR_TOPgui.ANCHOR_BOTTOMhides on-display keyboard if available
Hides the on-display touch keyboard on the device.
returns if a node is enabled or not
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.
node -
node node to query
enabled -
boolean whether the node is enabled or not
moves the first node above the second
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.
node -
node to move
node -
node | nil reference node above which the first node should be moved
moves the first node below the second
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.
node -
node to move
node -
node | nil reference node below which the first node should be moved
creates a new box node
Dynamically create a new box node.
pos -
vector3 | vector4 node position
size -
vector3 node size
node -
node new box node
creates a new particle fx node
Dynamically create a particle fx node.
pos -
vector3 | vector4 node position
particlefx -
hash | string particle fx resource name
node -
node new particle fx node
creates a new pie node
Dynamically create a new pie node.
pos -
vector3 | vector4 node position
size -
vector3 node size
node -
node new box node
creates a new spine node
Dynamically create a new spine node.
pos -
vector3 | vector4 node position
spine_scene -
string | hash spine scene id
node -
node new spine node
creates a new text node
Dynamically create a new text node.
pos -
vector3 | vector4 node position
text -
string node text
node -
node new text node
create new texture
Dynamically create a new texture.
texture -
string | hash texture id
width -
number texture width
height -
number texture height
type -
string | constant texture type
"rgb" - RGB"rgba" - RGBA"l" - LUMINANCEbuffer -
string texture data
flip -
boolean flip texture vertically
success -
boolean texture creation was successful
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
determines if the node is pickable by the supplied coordinates
Tests whether a coordinate is within the bounding box of a node.
node -
node node to be tested for picking
x -
number x-coordinate (see on_input )
y -
number y-coordinate (see on_input )
pickable -
boolean pick result
play node flipbook animation
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.
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
selfobject The current object.
nodenode The node that is animated.
[play_properties] -
table optional table with properties
offsetplayback_rateSet 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")
Plays a particle fx
Plays the paricle fx for a gui node
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.
selfnodenil if the node was deletedemitterstateparticlefx.EMITTER_STATE_SLEEPINGparticlefx.EMITTER_STATE_PRESPAWNparticlefx.EMITTER_STATE_SPAWNINGparticlefx.EMITTER_STATE_POSTSPAWNHow 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
play a spine animation
Starts a spine animation.
node -
node spine node that should play the animation
animation_id -
string | hash id of the animation to play
playback -
constant playback mode
gui.PLAYBACK_ONCE_FORWARDgui.PLAYBACK_ONCE_BACKWARDgui.PLAYBACK_ONCE_PINGPONGgui.PLAYBACK_LOOP_FORWARDgui.PLAYBACK_LOOP_BACKWARDgui.PLAYBACK_LOOP_PINGPONG[play_properties] -
table optional table with properties
blend_durationoffsetplayback_rate[complete_function] -
function(self, node) function to call when the animation has completed
resets on-display keyboard if available
Resets the input context of keyboard. This will clear marked text.
resets all nodes to initial state
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.
sets 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.
node -
node node to set adjust mode for
adjust_mode -
constant adjust mode to set
gui.ADJUST_FITgui.ADJUST_ZOOMgui.ADJUST_STRETCHsets node blend mode
Set the blend mode of a node. Blend mode defines how the node will be blended with the background.
node -
node node to set blend mode for
blend_mode -
constant blend mode to set
gui.BLEND_ALPHAgui.BLEND_ADDgui.BLEND_ADD_ALPHAgui.BLEND_MULTsets node clipping inversion
If node is set as an inverted clipping node, it will clip anything inside as opposed to outside.
node -
node node to set clipping inverted state for
inverted -
boolean true or false
sets node clipping mode state
Clipping mode defines how the node will clipping it's children nodes
node -
node node to set clipping mode for
clipping_mode -
constant clipping mode to set
gui.CLIPPING_MODE_NONEgui.CLIPPING_MODE_STENCILsets node clipping visibility
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.
node -
node node to set clipping visibility for
visible -
boolean true or false
sets the 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 |
node -
node node to set the color for
color -
vector3 | vector4 new color
enables/disables a node
Sets a node to the disabled or enabled state. Disabled nodes are not rendered and animations acting on them are not evaluated.
node -
node node to be enabled/disabled
enabled -
boolean whether the node should be enabled or not
sets the angle for the filled pie sector
Set the sector angle of a pie node.
node -
node node to set the fill angle for
angle -
number sector angle
sets the normalized cursor of the animation on a node with flipbook animation
This is only useful nodes with flipbook animations. The cursor is normalized.
node -
node node to set the cursor for
cursor -
number cursor value
sets the playback rate of the flipbook animation on a node
This is only useful nodes with flipbook animations. Sets the playback rate of the flipbook animation on a node. Must be positive.
node -
node node to set the cursor for
playback_rate -
number playback rate
sets the node font
This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.
node -
node node for which to set the font
font -
string | hash font id
sets the id of the specified 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.
node -
node node to set the id for
id -
string | hash id to set
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")
sets the node inherit alpha state
node -
node node from which to set the inherit alpha state
inherit_alpha -
boolean true or false
sets the pie inner radius
Sets the inner radius of a pie node. The radius is defined along the x-axis.
node -
node node to set the inner radius for
radius -
number inner radius
sets the node layer
The layer must be mapped to the gui scene in the gui editor.
node -
node node for which to set the layer
layer -
string | hash layer id
sets the leading of the text node
Sets the leading value for a text node. This value is used to scale the line spacing of text.
node -
node node for which to set the leading
leading -
number a scaling value for the line spacing (default=1)
set line-break mode
Sets the line-break mode on a text node. This is only useful for text nodes.
node -
node node to set line-break for
line_break -
boolean true or false
sets the pie node outer bounds mode
Sets the outer bounds mode for a pie node.
node -
node node for which to set the outer bounds mode
bounds_mode -
constant the outer bounds mode of the pie node:
gui.PIEBOUNDS_RECTANGLEgui.PIEBOUNDS_ELLIPSEsets the node outline color
Sets the outline color of the supplied node. See gui.set_color for info how vectors encode color values.
node -
node node to set the outline color for
color -
vector3 | vector4 new outline color
sets the parent of the node
Sets the parent node of the specified node.
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
Sets a particle fx
Set the paricle fx for a gui node
node -
node node to set particle fx for
particlefx -
hash | string particle fx id
sets the number of generated vertices around the perimeter
Sets the number of generated vertices around the perimeter of a pie node.
node -
node pie node
vertices -
number vertex count
sets the pivot of a node
The pivot specifies how the node is drawn and rotated from its position.
node -
node node to set pivot for
pivot -
constant pivot constant
gui.PIVOT_CENTERgui.PIVOT_Ngui.PIVOT_NEgui.PIVOT_Egui.PIVOT_SEgui.PIVOT_Sgui.PIVOT_SWgui.PIVOT_Wgui.PIVOT_NWsets the node position
Sets the position of the supplied node.
node -
node node to set the position for
position -
vector3 | vector4 new position
sets the render ordering for the current GUI scene
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.
order -
number rendering order (0-15)
sets the node rotation
Sets the rotation of the supplied node. The rotation is expressed in degree Euler angles.
node -
node node to set the rotation for
rotation -
vector3 | vector4 new rotation
sets the node scale
Sets the scaling of the supplied node.
node -
node node to set the scale for
scale -
vector3 | vector4 new scale
sets the node shadow color
Sets the shadow color of the supplied node. See gui.set_color for info how vectors encode color values.
node -
node node to set the shadow color for
color -
vector3 | vector4 new shadow color
sets the node size
Sets the size of the supplied node.
You can only set size on nodes with size mode set to SIZE_MODE_MANUAL
node -
node node to set the size for
size -
vector3 | vector4 new size
sets 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.
node -
node node to set size mode for
size_mode -
constant size mode to set
gui.SIZE_MODE_MANUALgui.SIZE_MODE_AUTOset the slice9 configuration for the node
Set the slice9 configuration values for the node.
node -
node node to manipulate
values -
vector4 new values
sets the normalized cursor of the animation on a spine node
This is only useful for spine nodes. The cursor is normalized.
node -
node spine node to set the cursor for
cursor -
number cursor value
sets the playback rate of the animation on a spine node
This is only useful for spine nodes. Sets the playback rate of the animation on a spine node. Must be positive.
node -
node spine node to set the cursor for
playback_rate -
number playback rate
sets the spine scene of a node
Set the spine scene on a spine node. The spine scene must be mapped to the gui scene in the gui editor.
node -
node node to set spine scene for
spine_scene -
string | hash spine scene id
sets the spine skin
Sets the spine skin on a spine node.
node -
node node to set the spine skin on
spine_skin -
string | hash spine skin id
[spine_slot] -
string | hash optional slot id to only change a specific slot
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
sets the node text
Set the text value of a text node. This is only useful for text nodes.
node -
node node to set text for
text -
string text to set
sets the 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.
node -
node node to set texture for
texture -
string | hash texture id
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
set the buffer data for a texture
Set the texture buffer data for a dynamically created texture.
texture -
string | hash texture id
width -
number texture width
height -
number texture height
type -
string | constant texture type
"rgb" - RGB"rgba" - RGBA"l" - LUMINANCEbuffer -
string texture data
flip -
boolean flip texture vertically
success -
boolean setting the data was successful
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
sets the tracking of the text node
Sets the tracking value of a text node. This value is used to adjust the vertical spacing of characters in the text.
node -
node node for which to set the tracking
tracking -
number a scaling number for the letter spacing (default=0)
sets the x-anchor of a node
The x-anchor specifies how the node is moved when the game is run in a different resolution.
node -
node node to set x-anchor for
anchor -
constant anchor constant
gui.ANCHOR_NONEgui.ANCHOR_LEFTgui.ANCHOR_RIGHTsets the y-anchor of a node
The y-anchor specifies how the node is moved when the game is run in a different resolution.
node -
node node to set y-anchor for
anchor -
constant anchor constant
gui.ANCHOR_NONEgui.ANCHOR_TOPgui.ANCHOR_BOTTOMshows the on-display keyboard if available
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. .
type -
constant keyboard type
gui.KEYBOARD_TYPE_DEFAULTgui.KEYBOARD_TYPE_EMAILgui.KEYBOARD_TYPE_NUMBER_PADgui.KEYBOARD_TYPE_PASSWORDautoclose -
boolean if the keyboard should automatically close when clicking outside
Stops a particle fx
Stops the particle fx for a gui node
node -
node node to stop particle fx for
called when a gui component is initialized
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.
self -
object reference to the script state to be used for storing data
function init(self) -- set up useful data self.my_value = 1 end
reports a layout change
This message is broadcast to every GUI component when a layout change has been initiated on device.
id -
hash the id of the layout the engine is changing to
previous_id -
hash the id of the layout the engine is changing from
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
called when user input is received
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). |
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
[consume] -
boolean optional boolean to signal if the input should be consumed (not passed on to others) or not, default is false
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
called when a message has been sent to the gui component
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.
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
called when the gui script is reloaded
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.
self -
object reference to the script state to be used for storing data
function on_reload(self) -- restore some color (or similar) gui.set_color(gui.get_node("my_node"), self.my_original_color) end
called every frame to update the gui component
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.
self -
object reference to the script state to be used for storing data
dt -
number the time-step of the frame update
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