Build a mod
Drawing
Draw text, boxes, lines, images and items on the screen with the drawing context, ctx.
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
| Method | What 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
| Method | What 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).
wandhdefault to the image's own size.u0, v0, u1, v1pick part of the image, from 0 to 1. Leave them out to draw all of it.tintcolors 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)
| Method | What 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.



