Build a mod

The HUD

Add your own panels to the HUD, and hide, wrap or replace the parts the game draws.

Pubblicità

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.

NameWhat it is
camera_overlaysfull screen effects, like the pumpkin blur and powder snow
crosshairthe crosshair
hotbarthe hotbar
player_healthyour health, armor, hunger and air
vehicle_healththe health of the mob you are riding
experience_barthe experience bar and level
selected_item_namethe item name that shows when you switch slots
effectsstatus effect icons
boss_barboss health bars
sleep_overlaythe fade when you sleep
demo_overlaythe demo timer
scoreboardthe sidebar scoreboard
action_barthe text above the hotbar
titletitles and subtitles in the middle of the screen
chatthe chat
tab_listthe player list when you hold Tab
subtitlessound subtitles
saving_indicatorthe world saving icon
toaststhe popups in the top right, like advancements
debugthe 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.