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.

Pubblicità

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:

IdScreen
titlethe title screen
pausethe pause menu
optionsthe main options screen (its sub-pages are other)
chatthe chat box
inventoryyour inventory
creativethe creative inventory
containerchests, furnaces and every other block you open
multiplayerthe server list
singleplayerthe world list
deaththe death screen
otheranything 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

OptionDefaultWhat it does
titleyour mod's namethe title of the screen
initfunction(screen), adds the widgets
renderfunction(screen, ctx, mouseX, mouseY, delta), draws on top of the widgets
tickfunction(screen), runs every game tick while the screen is open
onClosefunction(screen), runs when the screen closes
onKeyfunction(screen, key, code, modifiers). Return true to keep the key for yourself
onClickfunction(screen, x, y, button). Return true to keep the click for yourself
pausetruepauses a singleplayer world while the screen is open
backgroundtruedarkens and blurs the game behind the screen
closeOnEsctruecloses the screen when the player presses Escape

The screen you get back has width, height and title, plus these methods:

MethodWhat 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).

WidgetOptionsCallbacks
s:buttontextonClick(widget)
s:labeltext, color, centered, shadow, wrap
s:togglelabel, valueonChange(value, widget)
s:sliderlabel, min, max, step, value, formatonChange(value, widget)
s:textFieldvalue, hint, maxLength, focusonChange(text), onSubmit(text)
s:textAreavalue, hint, maxLengthonChange(text)
s:listitems, itemHeightonSelect(index, data), onActivate(index, data)
s:imagetexture, tint
s:canvasrender(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 5 comes back as 5.0. Use math.floor if you need a whole number. format is a function that turns the value into the text shown on the slider.
  • onSubmit runs when the player presses Enter in a text field.
  • List items are text, or tables with title, subtitle, icon (a texture), color and data. onSelect gets the 1-based index and the item's data (the item itself if it has none). onActivate runs on a double click.
  • A canvas is an empty box you draw yourself. Its render uses screen positions, but the x and y in its onClick are 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.