Wax

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.

A small dark panel titled Status with three rows: Map Olympus, Position 571, 588, 2536 in a fixed-width font, and a blue Oxygen bar filled to 80 percent.
init.lua
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.

init.lua
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.

OptionWhat it doesWhen left out
anchorWhere on the screen the panel is pinned."top-right"
x, yHow far in from that edge of the screen.16
widthThe width of the panel.240
titleA heading at the top.No heading.
backgroundfalse 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

init.lua
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)
FunctionWhat 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.

init.lua
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.

init.lua
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:

OptionWhat it doesWhen left out
whenWhen 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"
paddingThe space between its edge and its controls.12 at the sides.
heightA fixed height.As tall as its controls.
zoomDraws everything in it this much larger. 1.25 is a quarter larger. Text stays sharp.1
opacityHow solid its background is, from 0 to 1.0.96
visiblefalse makes it hidden until panel:SetVisible(true).true
on_pressA function that runs when the panel is pressed where it has no control.Nothing.
placeA 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.

init.lua
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 place function gets is the screen in the units the game lays its own menus out in. The panel's zoom is 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.

init.lua
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.

init.lua
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.

On this page