GUI API documentation
The main material (the default material assigned to a GUI) used when rendering the gui. The type of the property is hash.
How to set material using a script property (see resource.material)
go.property("desaturate_material", resource.material("/desaturate.material"))
function init(self)
go.set("#gui", "material", self.desaturate_material)
end
The materials used when rendering the gui. The type of the property is hash. Key must be specified in options table.
How to change a named material resource using a script property from a script
go.property("my_material", resource.material("/my_material.material"))
function init(self)
-- this will update the "my_gui_material" entry in the GUI to use the material
-- specified in the "my_material" script property.
go.set("#gui", "materials", self.my_material, { key = "my_gui_material" })
end
The textures used in the gui. The type of the property is hash. Key must be specified in options table.
How to set texture using a script property (see resource.atlas)
go.property("cards_red", resource.atlas("/cards_red.atlas"))
go.property("cards_blue", resource.atlas("/cards_blue.atlas"))
function init(self)
go.set("#gui", "textures", self.cards_red, {key = "cards"})
end
The fonts used in the gui. The type of the property is hash. Key must be specified in options table.
How to set font using a script property (see resource.font)
go.property("title_latin", resource.font("/open_sans.font"))
go.property("title_cyrillic", resource.font("/open_sans_cyrillic.font"))
function init(self)
go.set("#gui", "fonts", self.title_cyrillic, {key = "title"})
end
Retrieves the node with the specified id.
id - id of the node to retrieve
instance - 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)
Retrieves the id of the specified node.
node - the node to retrieve the id from
id - 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]
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 to set the id for
id - 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")
Instead of using specific getters such as gui.get_position or gui.get_scale, you can use gui.get instead and supply the property as a string or a hash. While this function is similar to go.get, there are a few more restrictions when operating in the gui namespace. Most notably, only these propertie identifiers are supported:
"position"
"rotation"
"euler"
"scale"
"color"
"outline"
"shadow"
"size"
"fill_angle"
(pie)"inner_radius"
(pie)"slice9"
(slice9)node - node to get the property for
property - the property to retrieve
Get properties on existing nodes:
local node = gui.get_node("my_box_node")
local node_position = gui.get(node, "position")
Instead of using specific setteres such as gui.set_position or gui.set_scale, you can use gui.set instead and supply the property as a string or a hash. While this function is similar to go.get and go.set, there are a few more restrictions when operating in the gui namespace. Most notably, only these propertie identifiers are supported:
"position"
"rotation"
"euler"
"scale"
"color"
"outline"
"shadow"
"size"
"fill_angle"
(pie)"inner_radius"
(pie)"slice9"
(slice9)node - node to set the property for
property - the property to set
value - the property to set
Updates the position property on an existing node:
local node = gui.get_node("my_box_node")
local node_position = gui.get(node, "position")
gui.set(node, "position.x", node_position.x + 128)
local node = gui.get_node("my_box_node")
gui.set(node, "rotation", vmath.quat_rotation_z(math.rad(45)))
-- this is equivalent to:
gui.set(node, "euler.z", 45)
-- or using the entire vector:
gui.set(node, "euler", vmath.vector3(0,0,45))
-- or using the set_rotation
gui.set_rotation(node, vmath.vector3(0,0,45))
Retrieve the index of the specified node among its siblings. 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 - the node to retrieve the id from
index - the index of the node
Compare the index order of two sibling 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
Deletes the specified node. Any child nodes of the specified node will be recursively deleted.
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)
once forward
once backward
once forward and then backward
loop forward
loop backward
ping pong loop
linear interpolation
in-quadratic
out-quadratic
in-out-quadratic
out-in-quadratic
in-cubic
out-cubic
in-out-cubic
out-in-cubic
in-quartic
out-quartic
in-out-quartic
out-in-quartic
in-quintic
out-quintic
in-out-quintic
out-in-quintic
in-sine
out-sine
in-out-sine
out-in-sine
in-exponential
out-exponential
in-out-exponential
out-in-exponential
in-circlic
out-circlic
in-out-circlic
out-in-circlic
in-elastic
out-elastic
in-out-elastic
out-in-elastic
in-back
out-back
in-out-back
out-in-back
in-bounce
out-bounce
in-out-bounce
out-in-bounce
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 to animate
property - property to animate
"position"
"rotation"
"euler"
"scale"
"color"
"outline"
"shadow"
"size"
"fill_angle"
(pie)"inner_radius"
(pie)"slice9"
(slice9)gui.PROP_POSITION
gui.PROP_ROTATION
gui.PROP_EULER
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
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
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
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
If an animation of the specified node is currently running (started by gui.animate
), it will immediately be canceled.
node - node that should have its animation canceled
property - property for which the animation should be canceled
"position"
"rotation"
"euler"
"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")
Dynamically create a new box node.
pos - node position
size - node size
node - new box node
Dynamically create a new text node.
pos - node position
text - node text
node - new text node
Dynamically create a new pie node.
pos - node position
size - node size
node - new pie node
Returns the text value of a text node. This is only useful for text nodes.
node - node from which to get the text
text - text value
Set the text value of a text node. This is only useful for text nodes.
node - node to set text for
text - text to set
Returns whether a text node is in line-break mode or not. This is only useful for text nodes.
node - node from which to get the line-break for
line_break - true
or false
Sets the line-break mode on a text node. This is only useful for text nodes.
node - node to set line-break for
line_break - true or false
Returns the blend mode of a node. Blend mode defines how the node will be blended with the background.
node - node from which to get the blend mode
blend_mode - blend mode
gui.BLEND_ALPHA
gui.BLEND_ADD
gui.BLEND_ADD_ALPHA
gui.BLEND_MULT
gui.BLEND_SCREEN
Set the blend mode of a node. Blend mode defines how the node will be blended with the background.
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.BLEND_SCREEN
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 to get texture from
texture - texture id
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 to set texture for
texture - 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")
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
Get node flipbook animation.
node - node to get flipbook animation from
animation - animation id
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 to set animation for
animation - animation id
[complete_function] - optional function to call when the animation has completed
self
node
[play_properties] - optional table with properties
offset
playback_rate
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
-- 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")
Cancels any running flipbook animation on the specified node.
node - node cancel flipbook animation for
local node = gui.get_node("anim_node")
gui.cancel_flipbook(node)
Dynamically create a new texture.
texture_id - texture id
width - texture width
height - texture height
type - texture type
"rgb"
- RGB"rgba"
- RGBA"l"
- LUMINANCEbuffer - texture data
flip - flip texture vertically
success - texture creation was successful
code - one of the gui.RESULT_* codes if unsuccessful
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.
local ok, reason = gui.new_texture("orange_tx", w, h, "rgb", string.rep(orange, w * h))
if ok 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 for some reason...
if reason == gui.RESULT_TEXTURE_ALREADY_EXISTS then
...
else
...
end
end
end
Delete a dynamically created texture.
texture - 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
Set the texture buffer data for a dynamically created texture.
texture - texture id
width - texture width
height - texture height
type - texture type
"rgb"
- RGB"rgba"
- RGBA"l"
- LUMINANCEbuffer - texture data
flip - flip texture vertically
success - 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
Returns the material of a node. The material must be mapped to the gui scene in the gui editor.
node - node to get the material for
Getting the material for a node, and assign it to another node:
local node1 = gui.get_node("my_node")
local node2 = gui.get_node("other_node")
local node1_material = gui.get_material(node1)
gui.set_material(node2, node1_material)
Set the material on a node. The material must be mapped to the gui scene in the gui editor,
and assigning a material is supported for all node types. To set the default material that
is assigned to the gui scene node, use gui.reset_material(node_id)
instead.
node - node to set material for
material - material id
Assign an existing material to a node:
local node = gui.get_node("my_node")
gui.set_material(node, "my_material")
Resets the node material to the material assigned in the gui scene.
node - node to reset the material for
Resetting the material for a node:
local node = gui.get_node("my_node")
gui.reset_material(node)
This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.
node - node from which to get the font
font - font id
This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.
font_name - font of which to get the path hash
hash - path hash to resource
Get the text metrics for a text
function init(self)
local node = gui.get_node("name")
local font_name = gui.get_font(node)
local font = gui.get_font_resource(font_name)
local metrics = resource.get_text_metrics(font, "The quick brown fox\n jumps over the lazy dog")
end
This is only useful for text nodes. The font must be mapped to the gui scene in the gui editor.
node - node for which to set the font
font - font id
The layer must be mapped to the gui scene in the gui editor.
node - node from which to get the layer
layer - layer id
The layer must be mapped to the gui scene in the gui editor.
node - node for which to set the layer
layer - layer id
gets the scene current layout
layout - layout id
Clipping mode defines how the node will clip it's children nodes
node - node from which to get the clipping mode
clipping_mode - clipping mode
gui.CLIPPING_MODE_NONE
gui.CLIPPING_MODE_STENCIL
Clipping mode defines how the node will clip it's children nodes
node - node to set clipping mode for
clipping_mode - clipping mode to set
gui.CLIPPING_MODE_NONE
gui.CLIPPING_MODE_STENCIL
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 from which to get the clipping visibility state
visible - true or false
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 to set clipping visibility for
visible - true or false
If node is set as an inverted clipping node, it will clip anything inside as opposed to outside.
node - node from which to get the clipping inverted state
inverted - true or false
If node is set as an inverted clipping node, it will clip anything inside as opposed to outside.
node - node to set clipping inverted state for
inverted - true or false
The x-anchor specifies how the node is moved when the game is run in a different resolution.
node - node to get x-anchor from
anchor - anchor constant
gui.ANCHOR_NONE
gui.ANCHOR_LEFT
gui.ANCHOR_RIGHT
The x-anchor specifies how the node is moved when the game is run in a different resolution.
node - node to set x-anchor for
anchor - anchor constant
gui.ANCHOR_NONE
gui.ANCHOR_LEFT
gui.ANCHOR_RIGHT
The y-anchor specifies how the node is moved when the game is run in a different resolution.
node - node to get y-anchor from
anchor - anchor constant
gui.ANCHOR_NONE
gui.ANCHOR_TOP
gui.ANCHOR_BOTTOM
The y-anchor specifies how the node is moved when the game is run in a different resolution.
node - node to set y-anchor for
anchor - anchor constant
gui.ANCHOR_NONE
gui.ANCHOR_TOP
gui.ANCHOR_BOTTOM
The pivot specifies how the node is drawn and rotated from its position.
node - node to get pivot from
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
The pivot specifies how the node is drawn and rotated from its position.
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
Returns the scene width.
width - scene width
Returns the scene height.
height - scene height
Set the slice9 configuration values for the node.
node - node to manipulate
values - new values
Returns the slice9 configuration values for the node.
node - node to manipulate
values - configuration values
Sets the number of generated vertices around the perimeter of a pie node.
node - pie node
vertices - vertex count
Returns the number of generated vertices around the perimeter of a pie node.
node - pie node
vertices - vertex count
Set the sector angle of a pie node.
node - node to set the fill angle for
angle - sector angle
Returns the sector angle of a pie node.
node - node from which to get the fill angle
angle - sector angle
Sets the inner radius of a pie node. The radius is defined along the x-axis.
node - node to set the inner radius for
radius - inner radius
Returns the inner radius of a pie node. The radius is defined along the x-axis.
node - node from where to get the inner radius
radius - inner radius
Sets the outer bounds mode for a pie node.
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
Returns the outer bounds mode for a pie node.
node - node from where to get the outer bounds mode
bounds_mode - the outer bounds mode of the pie node:
gui.PIEBOUNDS_RECTANGLE
gui.PIEBOUNDS_ELLIPSE
Sets the leading value for a text node. This value is used to scale the line spacing of text.
node - node for which to set the leading
leading - a scaling value for the line spacing (default=1)
Returns the leading value for a text node.
node - node from where to get the leading
leading - leading scaling value (default=1)
Sets the tracking value of a text node. This value is used to adjust the vertical spacing of characters in the text.
node - node for which to set the tracking
tracking - a scaling number for the letter spacing (default=0)
Returns the tracking value of a text node.
node - node from where to get the tracking
tracking - tracking scaling number (default=0)
Tests whether a coordinate is within the bounding box of a node.
node - node to be tested for picking
x - x-coordinate (see on_input )
y - y-coordinate (see on_input )
pickable - pick result
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 to query
recursive - check hierarchy recursively
enabled - whether the node is enabled or not
Sets a node to the disabled or enabled state. Disabled nodes are not rendered and animations acting on them are not evaluated.
node - node to be enabled/disabled
enabled - whether the node should be enabled or not
Returns true
if a node is visible and false
if it's not.
Invisible nodes are not rendered.
node - node to query
visible - whether the node is visible or not
Set if a node should be visible or not. Only visible nodes are rendered.
node - node to be visible or not
visible - whether the node should be visible or not
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 from which to get the adjust mode (node)
adjust_mode - the current adjust mode
gui.ADJUST_FIT
gui.ADJUST_ZOOM
gui.ADJUST_STRETCH
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 to set adjust mode for
adjust_mode - adjust mode to set
gui.ADJUST_FIT
gui.ADJUST_ZOOM
gui.ADJUST_STRETCH
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. Particle fx and Text nodes will ignore any size mode setting.
node - node from which to get the size mode (node)
size_mode - the current size mode
gui.SIZE_MODE_MANUAL
gui.SIZE_MODE_AUTO
Sets the size mode of a node. The size mode defines how the node will adjust itself in size. Automatic size mode alters the node size based on the node's content. Automatic size mode works for Box nodes and Pie nodes which will both adjust their size to match the assigned image. Particle fx and Text nodes will ignore any size mode setting.
node - node to set size mode for
size_mode - size mode to set
gui.SIZE_MODE_MANUAL
gui.SIZE_MODE_AUTO
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 - to move
reference - reference node above which the first node should be moved
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 - to move
reference - reference node below which the first node should be moved
Returns the parent node of the specified node.
If the supplied node does not have a parent, nil
is returned.
node - the node from which to retrieve its parent
parent - parent instance or nil
Sets the parent node of the specified node.
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
Make a clone instance of a node. The cloned node will be identical to the original node, except the id which is generated as the string "node" plus a sequential unsigned integer value. This function does not clone the supplied node's children nodes. Use gui.clone_tree for that purpose.
node - node to clone
clone - the cloned node
Make a clone instance of a node and all its children. Use gui.clone to clone a node excluding its children.
node - root node to clone
clones - a table mapping node ids to the corresponding cloned nodes
Get a node and all its children as a Lua table.
node - root node to get node tree from
clones - a table mapping node ids to the corresponding 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.
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 - rendering order (0-15)
default keyboard
number input keyboard
email keyboard
password keyboard
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 - 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
Hides the on-display touch keyboard on the device.
Resets the input context of keyboard. This will clear marked text.
Returns the position of the supplied node.
node - node to get the position from
position - node position
Sets the position of the supplied node.
node - node to set the position for
position - new position
Returns the rotation of the supplied node. The rotation is expressed as a quaternion
node - node to get the rotation from
rotation - node rotation
Sets the rotation of the supplied node. The rotation is expressed as a quaternion
node - node to set the rotation for
rotation - new rotation
Returns the rotation of the supplied node. The rotation is expressed in degree Euler angles.
node - node to get the rotation from
rotation - node rotation
Sets the rotation of the supplied node. The rotation is expressed in degree Euler angles.
node - node to set the rotation for
rotation - new rotation
Returns the scale of the supplied node.
node - node to get the scale from
scale - node scale
Sets the scaling of the supplied node.
node - node to set the scale for
scale - new scale
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 to get the color from
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 |
node - node to set the color for
color - new color
Returns the outline color of the supplied node. See gui.get_color for info how vectors encode color values.
node - node to get the outline color from
color - outline color
Sets the outline color of the supplied node. See gui.set_color for info how vectors encode color values.
node - node to set the outline color for
color - new outline color
Returns the shadow color of the supplied node. See gui.get_color for info how vectors encode color values.
node - node to get the shadow color from
color - node shadow color
Sets the shadow color of the supplied node. See gui.set_color for info how vectors encode color values.
node - node to set the shadow color for
color - new shadow color
Sets the size of the supplied node. You can only set size on nodes with size mode set to SIZE_MODE_MANUAL
node - node to set the size for
size - new size
Returns the size of the supplied node.
node - node to get the size from
size - node size
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 to get the screen position from
position - node screen position
Set the screen position to the supplied node
node - node to set the screen position to
screen_position - screen position
Convert the screen position to the local position of supplied node
node - node used for getting local transformation matrix
screen_position - screen position
local_position - local position
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 - cursor value
This is only useful nodes with flipbook animations. The cursor is normalized.
node - node to set the cursor for
cursor - cursor value
This is only useful nodes with flipbook animations. Gets the playback rate of the flipbook animation on a node.
node - node to set the cursor for
rate - playback rate
This is only useful nodes with flipbook animations. Sets the playback rate of the flipbook animation on a node. Must be positive.
node - node to set the cursor for
playback_rate - playback rate
Dynamically create a particle fx node.
pos - node position
particlefx - particle fx resource name
node - new particle fx node
Plays the paricle fx for a gui node
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
node
nil
if the node was deletedemitter
state
particlefx.EMITTER_STATE_SLEEPING
particlefx.EMITTER_STATE_PRESPAWN
particlefx.EMITTER_STATE_SPAWNING
particlefx.EMITTER_STATE_POSTSPAWN
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
Stops the particle fx for a gui node
node - node to stop particle fx for
options - options when stopping the particle fx. Supported options:
clear
: instantly clear spawned particlesSet the paricle fx for a gui node
node - node to set particle fx for
particlefx - particle fx id
Get the paricle fx for a gui node
node - node to get particle fx for
particlefx - particle fx id
gets the node inherit alpha state
node - node from which to get the inherit alpha state
sets the node inherit alpha state
node - node from which to set the inherit alpha state
inherit_alpha - true or false
gets the node alpha
node - node from which to get alpha
sets the node alpha
node - node for which to set alpha
alpha - 0..1 alpha color
position property
rotation property
euler property
scale property
color property
outline color property
shadow color property
size property
fill_angle property
inner_radius property
slice9 property
alpha blending
additive blending
additive alpha blending
multiply blending
screen blending
clipping mode none
clipping mode stencil
left x-anchor
right x-anchor
top y-anchor
bottom y-anchor
no anchor
center pivot
north pivot
north-east pivot
east pivot
south-east pivot
south pivot
south-west pivot
west pivot
north-west pivot
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.
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.
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.
elliptical pie node bounds
rectangular pie node bounds
The size of the node is determined by the size set in the editor, the constructor or by gui.set_size()
The size of the node is determined by the currently assigned texture.
The texture id already exists when trying to use gui.new_texture().
The system is out of resources, for instance when trying to create a new texture using gui.new_texture().
The provided data is not in the expected format or is in some other way incorrect, for instance the image data provided to gui.new_texture().
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 - reference to the script state to be used for storing data
function init(self)
-- set up useful data
self.my_value = 1
end
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 - 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
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 - reference to the script state to be used for storing data
dt - 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
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 - 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
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 |
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 - 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
consume - 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
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 - 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
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
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