Drawing and coordinates
Where you can draw#
draw.* functions are valid in exactly three places, and each has its own coordinate system:
| Place | Coordinates | Clipping |
|---|---|---|
events.on("draw", fn) | Screen pixels, (0, 0) at the top left of the overlay | None |
ui.widget{ draw = fn(w) } | The widget's own pixels, (0, 0) at its top left | Clipped to the widget's size |
ui.canvas(w, h, fn(c)) | The canvas's own pixels | Clipped to the canvas |
draw.size() returns the size of whatever you are drawing into, so the same helper function works in all three.
Coordinates#
- x grows to the right, y grows downwards.
- Positions and sizes are in pixels. They may be fractions (
10.5); the renderer handles them, though text and thin lines look sharpest on whole pixels. - The overlay covers the game picture, so
app.screen_size()is the game's size. It changes if the player changes resolution or window size, so read it every frame instead of caching it.
Staying correct at any resolution#
Do not hard-code positions for your own screen. Anchor to an edge or compute from the size:
events.on("draw", function()
local sw, sh = app.screen_size()
local m = 16
draw.rect(sw - 120 - m, m, 120, 24, 0x101418E0, 4) -- 16 px from the top-right corner
draw.rect(sw / 2 - 50, sh - 40, 100, 10, 0xFFFFFF40) -- centred at the bottom
end)For a movable element use a widget: its pos = {fx, fy} is a fraction of the free space of the screen (0, 0 top left, 1, 1 bottom right), so it lands in the same relative place at any size, and the user can drag it.
World positions#
data.world_to_screen(x, y, z) projects a world position to screen pixels, or returns nil for a point behind the camera. Always test for nil:
local sx, sy = data.world_to_screen(p.x, p.y, p.z + 72)
if sx then draw.circle(sx, sy, 4, 0xFF4040FF) endText#
draw.text(x, y, colour, text, options) puts the colour before the text. y is the top of the text. Options: size in pixels, shadow, outline, align ("left", "center", "right" relative to x) and font.
To put a background behind text, measure it first:
local text = "hello"
local w, h = draw.text_size(text, { size = 16 })
draw.rect(20 - 6, 20 - 4, w + 12, h + 8, 0x000000A0, 4)
draw.text(20, 20, 0xFFFFFFFF, text, { size = 16 })Use assets.font(path, size) for another typeface and pass it as { font = f }; a font that is not ready() yet cannot be used. Text is drawn with the built-in font otherwise.
Order, layering and fading#
Things are drawn in the order you call them, so later calls cover earlier ones. draw.alpha(a) multiplies the opacity of everything drawn after it, which is the easy way to fade a whole panel; call draw.alpha(1) when you are done. draw.clip(x, y, w, h) limits drawing to a rectangle until draw.unclip().
draw.alpha(fade) -- 0..1
draw.rect(x, y, w, h, 0x101418FF, 6)
draw.text(x + 10, y + 8, 0xFFFFFFFF, "fading panel")
draw.alpha(1)Images, gradients and shapes#
draw.image(tex, x, y, w, h, { tint, rounding, rotation, uv }). A texture that is not ready draws nothing. See assets.draw.rect_gradient(x, y, w, h, tl, tr, br, bl)blends four corner colours.draw.line,draw.circle,draw.arc,draw.triangle,draw.polyline,draw.polygon(convex only),draw.bezier: see draw.draw.meshanddraw.modeldraw a small 3D mesh and the built-in player model.draw.shader_rectfills a rectangle with a pixel shader fromassets.shader.
Limits#
12 000 draw calls per script per frame; beyond that the rest are dropped and the overlay logs it. A few hundred calls is cheap. See performance.