User interface
The UI plugin lets you build menus, HUDs and dialogs from plain tables. Every piece of interface is an entity (a
node) laid out with flexbox, drawn on top of the game, in pixels of the view. Nothing has a fixed look: a button is
any node that has a button part, whatever else it holds.
The UI exists on the client only. Turn it on in project.luau:
if engine.isClient then
engine.settings.plugins = { "rtype.Ui" }
end
rtype.Ui brings rtype.graphics, rtype.Input and rtype.Text with it. You still need a font for any text, see
Setup forms.
A first menu
local font = engine.assets.font("fonts/orbitron.json")
engine.ecs.system("game.SpawnMenu", {
phase = "Startup",
side = "client",
query = {},
run = function(ctx)
engine.ui.spawn(ctx.commands, {
style = { width = "100%", height = "100%", justify = "center", alignItems = "center" },
children = {
{
style = { padding = 16, alignItems = "center" },
background = { color = { 0.1, 0.1, 0.2, 1 }, radius = 8 },
button = { action = "menu.play", hovered = { 0.2, 0.2, 0.4, 1 } },
children = { { style = { ignorePointer = true }, text = { text = "Play", font = font, size = 24 } } },
},
},
})
end,
})
engine.ecs.system("game.ReadMenu", {
phase = "Update",
side = "client",
query = {},
events = { read = { "rtype.UiClicked" } },
run = function(ctx)
for click in ctx.events.read("rtype.UiClicked") do
if click.action == "menu.play" then
print("let's play")
end
end
end,
})
A complete menu with every widget is in examples/plugins/ui/game/.
engine.ui.spawn
engine.ui.spawn(commands, spec, parent) spawns a tree of nodes and returns the root entity (or nil on a server).
commands is ctx.commands; parent is optional. Every key of spec adds one component to the node; any other key
is an error that names the form.
| Key | Component | Fields |
|---|---|---|
style |
rtype.UiNode |
the layout, see Layout |
background |
rtype.UiBackground |
color, radius, borderColor, borderWidth |
image |
rtype.UiImage |
texture, source, color, slice, sliceScale |
text |
rtype.UiText |
text, font, size, color, align ("left", "center", "right"), wrap |
button |
rtype.UiButton |
action, normal, hovered, pressed, disabled (colors) |
toggle |
rtype.UiToggle |
action, checked, mark (color), inset |
slider |
rtype.UiSlider |
action, min, max, value, step, track, fill, handle (colors), trackHeight, handleRadius |
input |
rtype.UiTextInput |
action, placeholder, maxLength, caret (color) |
scroll |
rtype.UiScroll |
speed; also sets overflow = "scroll" |
interaction |
rtype.UiInteraction |
disabled, focusable |
components |
any | your own components, as in ctx.commands:spawn |
children |
a list of specs, spawned as children of this node |
Notes:
- Colors are
{ r, g, b, a }(the alpha may be left out and is then 1). They are linear, like every color of the engine: on an sRGB window0.25looks lighter than#404040. image.sliceis a number (the same border on four sides) or{ left, top, right, bottom }, for a nine-patch.- A button, toggle, slider or input also gets an
rtype.UiInteraction, so it can be hovered and focused. - An
inputneeds atext; it is added for you when you leave it out, and the typed text is read from it.
Layout
A style is a plain table, so sharing one is sharing a table. A list of styles is merged in order, the last one
winning:
local row = { direction = "row", alignItems = "center", gap = 12 }
style = { row, { padding = 16 } }
Lengths are a number of pixels, a percentage such as "50%", or "auto".
| Style | Values |
|---|---|
direction |
"column" (default), "column-reverse", "row", "row-reverse" |
justify |
"start", "center", "end", "space-between", "space-around", "space-evenly" |
alignItems, alignSelf, alignContent |
"auto", "start", "center", "end", "stretch", "baseline", and for alignContent the "space-*" ones |
wrap |
"nowrap", "wrap", "wrap-reverse" |
grow, shrink, aspectRatio |
numbers |
basis, width, height, minWidth, minHeight, maxWidth, maxHeight |
lengths |
position |
"relative" (default), "absolute"; with left, top, right, bottom (lengths) |
margin, marginX, marginY, marginLeft, marginTop, marginRight, marginBottom |
lengths |
padding, paddingX, paddingY, paddingLeft, paddingTop, paddingRight, paddingBottom |
lengths |
gap, rowGap, columnGap, border |
pixels |
overflow |
"visible" (default), "hidden", "scroll" |
display |
"flex" (default), "none" |
zIndex |
draw order among siblings |
ignorePointer |
true lets the pointer through to what is below |
There are no anchors: an absolute node with insets is one. { position = "absolute", right = 16, top = 16 } stays in
the top-right corner of its parent, whatever the size of the window.
A node with no parent node is a root and is laid out over the whole view. The result of the layout (position, size) is
in the node's rtype.UiComputed component, which you can read.
Reacting
A widget reports with the action you gave it: the name is yours, and one system can serve a whole menu. The UI runs
in PreUpdate, so a system in Update reads what happened in the same frame.
| Event | Sent by | Fields |
|---|---|---|
rtype.UiClicked |
a button | entity, action |
rtype.UiValueChanged |
a slider, a toggle (0 or 1) |
entity, action, value |
rtype.UiTextChanged |
a text input | entity, action; the text is in its rtype.UiText |
rtype.UiTextSubmitted |
a text input, on Enter | entity, action |
Declare them under events = { read = {...} } as in the first menu. For anything the widgets do not cover, any node can
carry an rtype.UiInteraction (hovered, pressed, focused, clicked) that a system reads.
Two resources help the gameplay get out of the UI's way; read them with resources = { read = {...} }:
| Resource | Fields |
|---|---|
rtype.UiPointer |
position (view pixels), overUi, hovered, pressed, clicked |
rtype.UiFocus |
focused, typing, activated, adjust |
The UI blocks nothing by itself. A game that shoots on a click checks overUi first, and ignores the keyboard while
typing is true.
Keyboard and gamepad
Every widget works with the pointer, the keyboard and a gamepad.
| Input | Effect |
|---|---|
| Tab, Shift+Tab | The next or previous widget, in draw order |
| Arrows, directional pad | The nearest widget in that direction; left and right adjust a slider |
| Enter, Space, South button | Activates the focused widget |
| Escape, East button | Drops the focus |
Pitfalls
- Text is drawn with a font atlas: a
textwithout afontshows nothing. Make the font withengine.assets.font. - A label inside a button swallows the click unless it has
style = { ignorePointer = true }. - The UI is drawn on the screen only: not in the world, and not in perspective.
- A text input is a single line, with no selection or clipboard, and wider text overflows the field. A slider is horizontal, and a scroll area has no scroll bar. Wrapped text breaks between words only.
- An unknown style name or value is an error such as
unknown justify 'middle', raised when the system runs.
See also
Systems for phases and events, Setup forms for fonts and textures, Project settings for the plugin list.