Build a mod

Drawing

Draw text, boxes, lines, images and items on the screen with the drawing context, ctx.

Advertisement

Anything your mod shows on the screen is drawn with a drawing context. You never make one yourself. The game hands it to you in places like hud.add, the hud, overlay and screen_render events and your own screens, and it is always called ctx in these docs.

hud.add(function(ctx)
  ctx:rect(4, 4, 120, 20, "#80000000")
  ctx:text("Hello there", 8, 10, "white")
end)

That draws a see-through black box with white text on top. Notice the colon in ctx:text. Every drawing function is a method on ctx, so you call it with : and not ..

Use ctx right away and do not keep it around. The game gives you a fresh one every frame.

Where things go

Positions are in GUI pixels. That is the same unit the game uses for its own menus, so your drawings scale with the player's GUI scale setting. The top left corner is 0, 0, x grows to the right and y grows down. Positions are rounded down to whole pixels.

ctx.width and ctx.height are the size of the screen in GUI pixels. game.width() and game.height() give you the same numbers anywhere in your mod. To put text in the bottom right corner:

hud.add(function(ctx)
  local text = "Bottom right"
  local w = ctx:textWidth(text)
  ctx:text(text, ctx.width - w - 4, ctx.height - ctx:fontHeight() - 4, "yellow")
end)

Colors

There are three ways to write a color.

A name. These names work: white, black, red, green, blue, yellow, gold, aqua, purple, gray (or grey), darkgray, orange and transparent. Red, green and blue are the soft Minecraft chat colors, not pure RGB.

A hex string. "#RRGGBB" is a solid color, and "#AARRGGBB" adds alpha (how see-through it is) at the front. "#80000000" is half see-through black, which makes a nice HUD background. The # is optional. Short forms like "#F00" do not work, so always write all six digits.

A number. 0xRRGGBB is a solid color and 0xAARRGGBB adds alpha. One catch: a number with alpha 00 is drawn solid, not invisible. To draw something see-through, use a hex string.

util.color(r, g, b, a) builds a color from whole numbers from 0 to 255 (a is 255 if you leave it out). util.hsv(h, s, v) builds one from a hue in degrees (0 to 360) and a saturation and value from 0 to 1, which is handy for rainbows.

local hue = 0

hud.add(function(ctx)
  hue = (hue + 1) % 360
  ctx:text("Rainbow", 4, 4, util.hsv(hue, 1, 1))
end)

Text understands the game's § color codes too, so "§aGreen §cRed" draws two colors. The game's code editor removes the § character when you type or paste it, so write it as "\u{00A7}" instead: "\u{00A7}aGreen".

Shapes

MethodWhat it draws
ctx:rect(x, y, w, h, color)a filled box from its corner and size
ctx:fill(x1, y1, x2, y2, color)a filled box between two corners
ctx:gradient(x1, y1, x2, y2, top, bottom)a box that fades from one color at the top to another at the bottom
ctx:outline(x, y, w, h, color)a 1 pixel border, drawn just inside the box
ctx:line(x1, y1, x2, y2, color, thickness)a line. thickness is 1 if you leave it out
ctx:circle(x, y, r, color, filled)a circle. It is filled unless you pass false for filled

If you leave out a color, you get white.

Text

MethodWhat it does
ctx:text(str, x, y, color, shadow)draws text and returns its width. It has a shadow unless you pass false
ctx:centeredText(str, cx, y, color)draws text centered on cx
ctx:wrappedText(str, x, y, width, color)wraps text to a width and returns the height it took
ctx:textWidth(str)the width of some text, without drawing it
ctx:fontHeight()the height of one line
ctx:tooltip(text, x, y)a tooltip box like the ones on items. Only shows up on screens, not on the HUD

You can pass numbers and other values as the text too. They are turned into text for you.

Images

Put a PNG in your mod's zip and load it once with textures.load, outside your draw function. Every call to textures.load makes a new copy, so loading inside a draw function would make a new one every frame.

local logo = textures.load("assets/logo.png")

hud.add(function(ctx)
  ctx:image(logo, 4, 4, 32, 32)
end)

The full form is ctx:image(texture, x, y, w, h, u0, v0, u1, v1, tint).

  • w and h default to the image's own size.
  • u0, v0, u1, v1 pick part of the image, from 0 to 1. Leave them out to draw all of it.
  • tint colors the image. Leave it out for the normal colors.

A texture has width and height fields. textures.release(texture) frees one early, but you rarely need it: everything your mod loaded is freed when it unloads.

Items

ctx:item(id, x, y, scale) draws an item's icon, the same way the hotbar does.

ctx:item("minecraft:diamond", 4, 40)
ctx:item("golden_apple", 24, 40, 2)

The minecraft: part is optional. scale is 1 if you leave it out, which is 16 by 16 pixels. Only the icon is drawn, without a count or a durability bar. An id that does not exist draws nothing.

Clipping

ctx:clip(x1, y1, x2, y2, fn) runs fn, and anything it draws outside that box is cut off. Use it for scrolling lists and anything else that has to stay inside a panel.

ctx:clip(10, 10, 110, 40, function()
  ctx:text("This long line gets cut off at the edge of the box", 10, 20, "white")
end)

ctx:pushClip(x1, y1, x2, y2) and ctx:popClip() do the same thing without a function.

Moving, scaling and rotating

To move, scale or rotate a group of drawings, save the current state with ctx:push(), change it, draw, and put it back with ctx:pop().

hud.add(function(ctx)
  ctx:push()
  ctx:translate(ctx.width / 2, 30)
  ctx:scale(2)
  ctx:centeredText("BIG TITLE", 0, 0, "gold")
  ctx:pop()
end)
MethodWhat it does
ctx:translate(x, y)moves everything drawn after it
ctx:scale(sx, sy)scales everything drawn after it. sy is the same as sx if you leave it out
ctx:rotate(degrees)rotates everything drawn after it, around the current position

Always wrap these in push and pop. Every mod draws with the same ctx each frame, so a translate without a pop moves everything drawn after yours too, even the game's menus.