Build a mod
Screens and menus
Add buttons to the game's own screens, or build full menus of your own with buttons, toggles, sliders, text boxes and lists.
A screen is anything that takes over the game and gives you a mouse: the title screen, the pause menu, your inventory, the options. Mods can add buttons to the game's screens and open screens of their own.
Add a button to a game screen
When one of the game's screens opens, it fires screen_init with that screen. Check which screen it is with screen.id, then add your buttons.
on("screen_init", function(screen)
if screen.id ~= "title" then return end
screen:button({
text = "Discord",
x = 4,
y = 4,
width = 80,
onClick = function()
clipboard.set("https://discord.gg/your-server")
ui.notify("Copied", "The Discord link is on your clipboard")
end,
})
end)
That puts a Discord button in the top left corner of the title screen. Clicking it copies a link and shows a popup.
screen_init fires again every time the screen is rebuilt, which includes every time the window changes size, and the buttons mods added are cleared each time. That is why you add buttons inside screen_init: they come back on their own. Never add buttons every frame, or you get a new button every frame.
screen:button takes text, onClick, x, y, width, height and tooltip. Without an x the button is centered, and without a y it sits at the top.
Screen ids
screen.id is one of these:
| Id | Screen |
|---|---|
title | the title screen |
pause | the pause menu |
options | the main options screen (its sub-pages are other) |
chat | the chat box |
inventory | your inventory |
creative | the creative inventory |
container | chests, furnaces and every other block you open |
multiplayer | the server list |
singleplayer | the world list |
death | the death screen |
other | anything else |
Screens made by mods have the id mod: plus their title, like mod:My Menu.
Change the buttons that are already there
screen:widgets() lists every button and widget on the screen. Each one has text, x, y, width, height, visible and active that you can read and change, and remove() to take it off the screen.
on("screen_init", function(screen)
if screen.id ~= "pause" then return end
for _, widget in ipairs(screen:widgets()) do
widget.y = widget.y + 10
end
end)
screen:find(text) finds a widget by its exact label. Labels follow the player's language, so find("Options...") only works for players who play in English.
Stop a screen from opening
screen_open fires before any screen opens. Cancel it and the screen never shows.
on("screen_open", function(e)
if e.screen == "inventory" and player.exists() and player.isSneaking() then
e:cancel()
end
end)
That stops the inventory from opening while you sneak. e.screen is the id of the screen that wants to open, and e.title is its title.
Build your own screen
ui.screen makes a new screen. Its init function adds the widgets, and ui.open shows it.
local count = 0
local menu = ui.screen({
title = "My Menu",
init = function(s)
s:label({ text = "Clicked " .. count .. " times", centered = true })
s:button({
text = "Click me",
onClick = function()
count = count + 1
s:rebuild()
end,
})
s:button({ text = "Close", onClick = function() s:close() end })
end,
})
ui.open(menu)
init runs every time the screen is shown: when it opens, when you come back to it from another screen, when the window changes size and when you call s:rebuild(). It starts from an empty screen each time. That is how the label above shows the new count: clicking the button calls rebuild, and init builds the label again with the new number.
Widgets without an x and y are centered and stacked down the screen, one under the other. That is usually all you need.
Screen options
| Option | Default | What it does |
|---|---|---|
title | your mod's name | the title of the screen |
init | function(screen), adds the widgets | |
render | function(screen, ctx, mouseX, mouseY, delta), draws on top of the widgets | |
tick | function(screen), runs every game tick while the screen is open | |
onClose | function(screen), runs when the screen closes | |
onKey | function(screen, key, code, modifiers). Return true to keep the key for yourself | |
onClick | function(screen, x, y, button). Return true to keep the click for yourself | |
pause | true | pauses a singleplayer world while the screen is open |
background | true | darkens and blurs the game behind the screen |
closeOnEsc | true | closes the screen when the player presses Escape |
The screen you get back has width, height and title, plus these methods:
| Method | What it does |
|---|---|
s:rebuild() | clears the screen and runs init again |
s:close() | closes the screen and goes back to where the player was |
s:clear() | removes every widget |
s:widgets() | a list of every widget |
s:find(id) | the widget you gave that id, or nil |
ui.close() closes whichever mod screen is open.
Widgets
Every widget takes these options: x, y, width, height, tooltip, id, visible and active (set active = false to grey it out).
| Widget | Options | Callbacks |
|---|---|---|
s:button | text | onClick(widget) |
s:label | text, color, centered, shadow, wrap | |
s:toggle | label, value | onChange(value, widget) |
s:slider | label, min, max, step, value, format | onChange(value, widget) |
s:textField | value, hint, maxLength, focus | onChange(text), onSubmit(text) |
s:textArea | value, hint, maxLength | onChange(text) |
s:list | items, itemHeight | onSelect(index, data), onActivate(index, data) |
s:image | texture, tint | |
s:canvas | render(ctx, mouseX, mouseY, delta), onClick(x, y, button) |
s:toggle({ label = "Enabled", value = true, onChange = function(on) end })
s:slider({
label = "Size",
min = 1,
max = 10,
step = 1,
value = 5,
onChange = function(value) end,
})
s:textField({ hint = "Type here...", onSubmit = function(text) end })
s:list({
items = { { title = "Home", subtitle = "x 100, z 200" }, "Spawn" },
height = 80,
onSelect = function(index, item) end,
})
A few things to know:
- A slider's value is always a decimal number, so
5comes back as5.0. Usemath.floorif you need a whole number.formatis a function that turns the value into the text shown on the slider. onSubmitruns when the player presses Enter in a text field.- List items are text, or tables with
title,subtitle,icon(a texture),coloranddata.onSelectgets the 1-based index and the item'sdata(the item itself if it has none).onActivateruns on a double click. - A canvas is an empty box you draw yourself. Its
renderuses screen positions, but thexandyin itsonClickare relative to the canvas.
Every widget function gives you back the widget, and you can change it later: text, value, visible, active, x, y, width, height and tooltip all work. Changing value or text from code does not call onChange. remove() takes a widget off the screen, and focus() puts the cursor in a text field.
Pop up a message
ui.notify shows a popup in the corner of the screen, like an advancement. It works anywhere, not just in menus.
ui.notify("Saved", "Your waypoint was saved")
A new popup replaces the one on screen, so do not send several in a row.
Open your menu with a key
A menu is only useful if players can get to it. Bind it to a key, or add a command for it. See Commands and keys.
keys.bind({
id = "open_menu",
label = "Open my menu",
default = "m",
onPress = function() ui.open(menu) end,
})
When your menu closes, the player goes back to wherever they were. If you open it from another mod screen, closing it goes back to that screen.



