Build a mod
The HUD
Add your own panels to the HUD, and hide, wrap or replace the parts the game draws.
The HUD is everything drawn on top of the world while you play: the hotbar, your hearts, the crosshair, chat and so on. The hud library lets you add to it and change the parts that are already there.
Add a panel
hud.add takes a function that draws with ctx. The game calls it every frame, right after it draws its own HUD.
hud.add(function(ctx, partialTick)
ctx:text("FPS: " .. game.fps(), 4, 4, "white")
end)
Give the panel a name as the first argument if you want to remove it later. Adding a panel with the same name again replaces the old one.
hud.add("fps", function(ctx)
ctx:text("FPS: " .. game.fps(), 4, 4, "white")
end)
hud.removeLayer("fps")
The hud event does the same job: on("hud", function(ctx, partialTick) end) runs after every panel.
The HUD only exists in a world, so these functions do not run on the title screen. They do keep running when the player hides the HUD with F1, and while a menu is open on top of the game.
Draw under or over one part
By default your panel goes on top of the game's HUD. To put it right before or after one part of the HUD, pass before or after in the options, or use hud.before and hud.after.
hud.add("chat_backdrop", drawBackdrop, { before = "chat" })
hud.before("chat", drawBackdrop)
hud.after("scoreboard", drawScoreboardNote)
Drawing before the chat means the chat ends up on top of your panel, which is what you want for a background. Panels added with hud.before and hud.after have no name, so they stay until your mod unloads.
Hide a part of the HUD
hud.hide("crosshair")
hud.show("crosshair") brings it back. A part stays hidden while any mod hides it, and everything your mod hid comes back by itself when it unloads. hud.isHidden("crosshair") tells you whether any mod is hiding it.
Replace a part of the HUD
hud.replace swaps one part of the HUD for your own drawing. Your function also gets drawOriginal, which draws the normal version, so you can wrap the original instead of throwing it away.
hud.replace("hotbar", function(ctx, partialTick, drawOriginal)
ctx:rect(0, ctx.height - 26, ctx.width, 26, "#60000000")
drawOriginal()
end)
That draws a dark strip behind the hotbar, then the normal hotbar on top. Each part can only have one replacement at a time, and the last mod to call hud.replace wins. hud.show removes your replacement.
The parts of the HUD
These are the names you can pass to hide, show, replace, before and after. hud.elements() gives you the same list in code.
| Name | What it is |
|---|---|
camera_overlays | full screen effects, like the pumpkin blur and powder snow |
crosshair | the crosshair |
hotbar | the hotbar |
player_health | your health, armor, hunger and air |
vehicle_health | the health of the mob you are riding |
experience_bar | the experience bar and level |
selected_item_name | the item name that shows when you switch slots |
effects | status effect icons |
boss_bar | boss health bars |
sleep_overlay | the fade when you sleep |
demo_overlay | the demo timer |
scoreboard | the sidebar scoreboard |
action_bar | the text above the hotbar |
title | titles and subtitles in the middle of the screen |
chat | the chat |
tab_list | the player list when you hold Tab |
subtitles | sound subtitles |
saving_indicator | the world saving icon |
toasts | the popups in the top right, like advancements |
debug | the F3 screen |
They are drawn in that order, top to bottom. Your panels from hud.add come right after subtitles, and the last three are drawn over everything, menus included.
Example: a coordinates panel
-- name: Coords
-- version: 1.0.0
hud.add("coords", function(ctx)
if not player.exists() then return end
local x, y, z = player.blockPos()
local lines = {
"XYZ: " .. x .. " " .. y .. " " .. z,
"Facing: " .. player.facing(),
"Biome: " .. (player.biome() or "unknown"),
}
local width = 0
for _, line in ipairs(lines) do
width = math.max(width, ctx:textWidth(line))
end
ctx:rect(2, 2, width + 6, #lines * 10 + 4, "#80000000")
for i, line in ipairs(lines) do
ctx:text(line, 5, 5 + (i - 1) * 10, "white")
end
end)
player.blockPos() gives back three numbers at once, so you catch all three with local x, y, z =. The panel measures its longest line first, so the background always fits the text.



