Overlays
A panel that stays on screen while you play.
An overlay is a panel pinned to the screen. It stays up while you play, and it never takes the mouse. Clicks go through it. Use it for things you only read, such as your position or a health bar.

local hud = ui.Overlay({ title = "Status", anchor = "top-left" })
local map = hud:Field("Map", game.MapName or "none")
local position = hud:Field("Position", "", { mono = true })
local oxygen = hud:Progress("Oxygen", 0.8)An overlay is a container, like a window. Add controls to it the same way. Nobody can click an overlay, so
use controls that show things: Label, Heading, Field, Progress, Icon, Separator.
Keep it up to date
The example above shows values that never change. Use a task to update them.
local hud = ui.Overlay({ title = "Status", anchor = "top-left" })
local map = hud:Field("Map", game.MapName or "none")
local position = hud:Field("Position", "", { mono = true })
local function where_am_i()
local character = game.Character
if not character then
return "no character"
end
local at = character:K2_GetActorLocation()
return ("%.0f, %.0f, %.0f"):format(at.X, at.Y, at.Z)
end
task.spawn(function()
while true do
position:Set(where_am_i())
task.wait(0.5)
end
end)
game.MapChanged:Connect(function(name)
map:Set(name)
end)Walk around and the position changes. For a bar that shows a real value, see Example: player stats.
Options
ui.Overlay takes one table. Every entry is optional.
| Option | What it does | When left out |
|---|---|---|
anchor | Where on the screen the panel is pinned. | "top-right" |
x, y | How far in from that edge of the screen. | 16 |
width | The width of the panel. | 240 |
title | A heading at the top. | No heading. |
background | false leaves out the dark panel, so only the controls are drawn over the game. | true |
There are nine anchors. Each name says where on the screen it is:
"top-left" "top" "top-right"
"left" "center" "right"
"bottom-left" "bottom" "bottom-right"Show, hide and move
local hud = ui.Overlay({ title = "Compass", anchor = "top" })
hud:Label("Press F6 to hide or show me.")
ui.Hotkey("F6", function()
hud:SetVisible(not hud:IsVisible())
end)| Function | What it does |
|---|---|
overlay:SetVisible(shown) | Shows or hides the overlay. |
overlay:IsVisible() | true while it is shown. |
overlay:SetAnchor(anchor, x, y) | Pins it somewhere else. Leave x and y out to keep their values. |
overlay:Destroy() | Removes the overlay and everything on it. |
The player can move it
Open the menu with F8. Every overlay gets an outline, and you can drag it to another place. Wax remembers where you left it.
Let the player switch it off
Some players do not want a panel on screen all the time. Add a switch for the overlay to a window, and save the choice.
local settings = storage.Load("settings", { overlay = true })
local hud = ui.Overlay({ title = "Status" })
hud:Field("Map", game.MapName or "none")
hud:SetVisible(settings.overlay)
local window = ui.Window({ title = "Status settings", width = 300, height = 140 })
window:Toggle("Show the overlay", settings.overlay, function(on)
settings.overlay = on
storage.Save("settings", settings)
hud:SetVisible(on)
end)Panels
A panel is an overlay whose controls take the mouse. ui.Panel makes one. It has no title bar and the
player does not drag it. Use it for something that stands beside the game's own screens, such as a list of
items next to the inventory.
local panel = ui.Panel({ anchor = "right", width = 220, when = "menu" })
panel:Label("Shown with the Wax menu.")
panel:Button("Say hi", function()
ui.Notify("Hi!")
end)A panel takes the options of an overlay, and these:
| Option | What it does | When left out |
|---|---|---|
when | When it shows. "cursor": while the Wax menu is open or one of the game's own screens has the mouse. "menu": only with the Wax menu. "always": whenever it is switched on. | "cursor" |
padding | The space between its edge and its controls. | 12 at the sides. |
height | A fixed height. | As tall as its controls. |
zoom | Draws everything in it this much larger. 1.25 is a quarter larger. Text stays sharp. | 1 |
opacity | How solid its background is, from 0 to 1. | 0.96 |
visible | false makes it hidden until panel:SetVisible(true). | true |
on_press | A function that runs when the panel is pressed where it has no control. | Nothing. |
place | A function that says where the panel goes on a screen of a given size. See below. | The panel stays where its anchor puts it. |
While the mouse is over a panel, the mouse wheel belongs to the panel and the game does not see it.
panel.Scrolled fires with 1 when the wheel is turned down and -1 when it is turned up.
ui.Open({ windows = false }) frees the mouse without bringing a window up. A mod that only has panels uses
it to show them with its own key.
A panel that follows the screen
Give a panel a place function and it follows the game's window. The function gets the width and the height
of the screen and returns a table with any of x, y, width, height and zoom. Wax asks it when the
panel is made, and again in the same frame whenever the game's window changes size. The panel that exists is
moved and sized. Nothing is built again.
panel.Resized fires with the panel's new width and height when the answer gave it another size.
local SIZE, GAP = 36, 2
local width = 0
-- a strip along the top, always as wide as the screen
local strip = ui.Panel({
anchor = "top-left",
when = "menu",
place = function(screen_width)
width = screen_width - 16
return { x = 8, y = 8, width = width }
end,
})
local function columns_for(room)
return math.max(1, math.floor((room - 24 + GAP) / (SIZE + GAP)))
end
local slots = strip:Slots({ columns = columns_for(width), size = SIZE, gap = GAP })
slots:Set({ { icon = "home", value = "home" }, { icon = "star", value = "star" } })
strip.Resized:Connect(function(new_width)
slots:SetLayout(columns_for(new_width))
end)- The size a
placefunction gets is the screen in the units the game lays its own menus out in. The panel'szoomis used as it is. So such a panel keeps its size beside the game's menus whatever interface size the player chose. slots:SetLayout(columns, size)changes how many cells stand in a row and how large a cell is. The cells that exist are kept, and missing ones are made over the next frames.
Slots
container:Slots(options) adds a block of square cells that each show a picture, as an inventory does. It
works in a panel and in a window. Each cell shows a look: a table with a picture or an icon, and what
you want back when the cell is clicked.
local panel = ui.Panel({ anchor = "right", width = 220, when = "menu" })
local slots = panel:Slots({ columns = 5, rows = 2, size = 36 })
slots:Set({
{ icon = "axe", value = "axe", tip = "An axe" },
{ icon = "apple", value = "apple", count = 12 },
})
slots.Activated:Connect(function(value)
ui.Notify("You clicked " .. tostring(value))
end)ui.Hovered() gives the value of the slot under the mouse, or nothing. The
reference lists everything a look can hold and every signal of a block.
Room beside the game's screens
ui.FitGame draws the game's own menus smaller, which leaves room beside them for panels. ui.GameScreen()
says which of the game's screens is showing, and ui.GameScreenChanged fires when that changes. Listen to the
signal, and do not ask every frame.
local panel = ui.Panel({
anchor = "right", width = 220, when = "always", visible = false,
})
panel:Label("Beside the inventory.")
local fit = ui.FitGame({ scale = 0.85, enabled = false })
ui.GameScreenChanged:Connect(function(name)
local beside = name == "UMG_MainMenu"
panel:SetVisible(beside)
fit:SetEnabled(beside)
end)Every function is listed in the ui reference.