Menus and HUDs#

What a player sees on top of the game: a health bar, a score, a menu, a shop.

You can make one without writing any code. A HUD is part of your world: you draw it in the editor, it is saved with the world, and the world shows it to players. A script is only needed for the parts that are about your game: what a purchase costs, when the score goes up.

Making one#

Open the editor, then the Interface tab in the bar at the top.

The middle of the page is the player's screen: your world, at the size a player sees it, with the HUD over it. On the left are this world's HUDs, the pages of the one that is open and the pieces on the page. On the right is whatever you selected.

1. Press + New HUD and pick a starting point: Health bar, Score, Menu, Shop, Notice or Blank.
2. Click a piece on the screen to change it on the right. Drag it to move it; drag a corner to resize it.
3. Add pieces from the bar above the screen: click one to drop it in the middle, or drag it to exactly where you want it.

There is no Save button. Every change is saved into the world as you make it, and the top bar says so.

When it appears#

With nothing selected, the right side shows the HUD itself. When it appears has two answers:

• Always: every player gets it the moment they enter. A health bar, a score. No script at all.
• When a script says: hidden until a script shows it. A shop that opens at the counter, a victory screen.

Darken the game behind it is for menus: the game dims, and the mouse is free to click the HUD until it closes.

Where things stay on other screens#

Players have different screens. Each piece holds on to a corner, an edge or the centre of the screen, and keeps its distance to it. You do not have to set this: the editor picks it from where you drop the piece. A health bar dropped near the top-left corner stays near that corner on a small laptop and on a wide monitor.

When you select a piece, a dot on the screen shows what it holds on to, and a dashed line connects it. To choose yourself, click a square in Holds on to; the piece stays where it is. Check the result with Screen under the player's screen, which shows the HUD at other sizes.

Panels#

A panel is a box that holds other pieces. Drop a piece on a panel and it goes inside. A panel can arrange what it holds:

When a panel arranges its pieces, their order is the order in the list on the left: right-click a piece there to bring it forward or send it back.

Pages#

A HUD can have several pages: a menu and its options, a shop and its confirmation. Add one under Pages on the left. A button opens another page with When clicked → Open a page, and Go back a page returns. Changing page happens on the player's machine, instantly.

Values#

Values are numbers and words a HUD shows and changes: the health, the coins, the chosen option. Add them in the HUD's own settings (click an empty spot on the screen).

• A text shows one with braces: Coins: {coins}.
• A bar or a round bar can show one.
• A switch, a slider, a text box and a drop-down each change one.

Testing#

Press Test in the top bar. The HUD works as it will for a player: buttons work, pages change, switches switch. What the buttons tell the scripts is listed on the right. Nothing reaches the world. Esc stops.

Connecting it to a script#

The editor shows what this HUD needs under Use it in a script, filled in with its own names. These are the four things a script does with a HUD.

Showing it#

A HUD set to When a script says appears when a script shows it to someone:

local self = require("self") self:on_touch(function(player)    player:show_hud("shop")end)

The second argument sets values as it opens, and the ones you do not name keep what the HUD says:

player:show_hud("shop", { coins = 40 })

Changing a value while it is on screen#

Push new values without rebuilding anything. Only the values you name change:

player:update_hud("health", { hp = 35 })

A HUD set to Always is already on everybody's screen, so a script that keeps the health up to date only ever needs this line.

Hearing its buttons#

A button set to When clicked → Tell the scripts sends a message, with any details you gave it. Every script in the world can listen by the HUD's name:

local world = require("world") world:on_hud("shop", function(player, event, data)    if event == "buy" then        print(player.name .. " wants " .. tostring(data.item))    endend)

It is the only action that reaches the server. Opening pages, changing values and closing the HUD all happen on the player's machine.

Trust event and the player, not data. The details are whatever the button carried; check the price and the item before handing anything over.

Taking it off the screen#

player:hide_hud("shop")

Writing a HUD in code#

A HUD can also be written entirely in a script, as a table. It is the same HUD, drawn by the same thing; it lives in the script instead of in the world. It suits HUDs that are built from data, like a hand of cards, a list of players.

--!strictlocal self = require("self") self:on_touch(function(p)    p:show_hud({        id = "sign",        anchor = "center",        modal = true,        pages = { main = {            { "text", "Mind the step", size = 22, bold = true },            { "text", "The floor below is being repaired.", wrap = true },            { "button", "Understood", close = true },        } },    })    p:show_cursor()end)

A HUD written this way reports its buttons to self:on_hud in the script that showed it:

local self = require("self") self:on_hud(function(p, event, data)    if event ~= "take" then return end    print(p.name .. " took " .. tostring(data.item))end)

Every node and style key is in the HUD reference.

Common mistakes#

See also#

• HUD reference has every node and key
• show_hud · world:on_hud

Updated 17 October 2026