Lua · Variables · Drawing

draw

Draw on the overlay: shapes, text, 3D lines, images and fonts.

Draw from on_frame. Calls anywhere else, and while the game is not on screen, do nothing. render is another name for the same table.

Positions are screen pixels from the top-left corner. Sizes are pixels. Colours are packed integers from color(). 3D functions take vectors in game units: {x = …, y = …, z = …}.

Function	What it does
`draw.screen()`	Screen size in pixels.
`draw.line(x1, y1, x2, y2, col[, thickness])`	A straight line.
`draw.rect(x, y, w, h, col[, rounding][, thickness])`	A rectangle outline.
`draw.rect_filled(x, y, w, h, col[, rounding])`	A filled rectangle.
`draw.circle(x, y, radius, col[, thickness])`	A circle outline.
`draw.circle_filled(x, y, radius, col)`	A filled circle.
`draw.text(x, y, text, col[, size])`	Text in the menu font. (x, y) is the top-left corner of the text.
`draw.text_size(text[, size])`	How big the text will be. Use it to centre or right-align.
`draw.text_outline(x, y, text, col[, size])`	Text with a thin black outline, readable on any background.
`draw.gradient(x, y, w, h, col1, col2[, horizontal])`	A rectangle that fades from one colour to another.
`draw.polygon(points, col)`	A filled convex shape (triangle, arrow, diamond). Concave shapes draw wrong.
`draw.polyline(points, col[, thickness][, closed])`	Connected lines through the points.
`draw.world_to_screen(x, y, z)`	Turns a world position into screen pixels. Takes three numbers, not a vector.
`draw.line3d(a, b, col[, thickness])`	A line between two world points. Drawn only when both ends are in front of the camera.
`draw.circle3d(center, radius, col[, thickness])`	A flat circle on the ground around a world point (32 segments).
`draw.box3d(min, max, col[, thickness])`	A 3D box outline between two corners.
`draw.load_image(file)`	Loads a PNG or JPG from the script's data folder. Do it once, outside `on_frame`.
`draw.load_image_data(bytes)`	Loads an image from bytes in memory, for example the body of an `http.get` reply.
`draw.image(handle, x, y, w, h[, tint][, rounding])`	Draws an image.
`draw.image_size(handle)`	Original size of a loaded image. 0, 0 for a bad handle.
`draw.load_font(file[, size])`	Loads a .ttf, .otf or .ttc font. Looks in the script's data folder first, then in Windows\Fonts.
`draw.font_ready(handle)`	True once the font can be used.
`draw.text_font(handle, x, y, text, col[, size])`	Text in a loaded font. Uses the menu font until the font is ready.
`draw.text_size_font(handle, text[, size])`	Text size in a loaded font.

#draw.screen

draw.screen()

Screen size in pixels.

Returns

number1

width

number2

height

Example

local w, h = draw.screen()
draw.text(w / 2, h / 2, "centre", white)

#draw.line

draw.line(x1, y1, x2, y2, col[, thickness])

A straight line.

Arguments

x1, y1number

Start.

x2, y2number

End.

colcolor

Colour.

thicknessnumberoptional

Default 1.

#draw.rect

draw.rect(x, y, w, h, col[, rounding][, thickness])

A rectangle outline.

Arguments

x, ynumber

Top-left corner.

w, hnumber

Size.

colcolor

roundingnumberoptional

Corner radius. Default 0.

thicknessnumberoptional

Default 1.

#draw.rect_filled

draw.rect_filled(x, y, w, h, col[, rounding])

A filled rectangle.

Arguments

x, ynumber

Top-left corner.

w, hnumber

Size.

colcolor

roundingnumberoptional

Corner radius. Default 0.

Example

draw.rect_filled(20, 20, 180, 60, color(12, 14, 18, 210), 8)

#draw.circle

draw.circle(x, y, radius, col[, thickness])

A circle outline.

Arguments

x, ynumber

Centre.

radiusnumber

colcolor

thicknessnumberoptional

Default 1.

#draw.circle_filled

draw.circle_filled(x, y, radius, col)

A filled circle.

Arguments

x, ynumber

Centre.

radiusnumber

colcolor

#draw.text

draw.text(x, y, text, col[, size])

Text in the menu font. (x, y) is the top-left corner of the text.

Arguments

x, ynumber

Top-left.

textstring

colcolor

sizenumberoptional

Pixel size. Default 14.

#draw.text_size

draw.text_size(text[, size])

How big the text will be. Use it to centre or right-align.

Arguments

textstring

sizenumberoptional

Default 14.

Returns

number1

width

number2

height

Example

local tw, th = draw.text_size(label, 16)
draw.text(x - tw / 2, y, label, white, 16)

#draw.text_outline

draw.text_outline(x, y, text, col[, size])

Text with a thin black outline, readable on any background.

Arguments

x, ynumber

textstring

colcolor

The outline uses 75% of this alpha.

sizenumberoptional

Default 14.

#draw.gradient

draw.gradient(x, y, w, h, col1, col2[, horizontal])

A rectangle that fades from one colour to another.

Arguments

x, y, w, hnumber

col1color

Left (or top) colour.

col2color

Right (or bottom) colour.

horizontalbooleanoptional

true (default) left to right, false top to bottom.

#draw.polygon

draw.polygon(points, col)

A filled convex shape (triangle, arrow, diamond). Concave shapes draw wrong.

Arguments

pointsnumber[]

Flat list {x1, y1, x2, y2, ...}, at least 3 points, up to 128.

colcolor

Example

draw.polygon({ 100, 100, 120, 140, 80, 140 }, color(255, 200, 0))

#draw.polyline

draw.polyline(points, col[, thickness][, closed])

Connected lines through the points.

Arguments

pointsnumber[]

Flat list, at least 2 points.

colcolor

thicknessnumberoptional

Default 1.

closedbooleanoptional

Join the last point to the first. Default false.

#draw.world_to_screen

draw.world_to_screen(x, y, z)

Turns a world position into screen pixels. Takes three numbers, not a vector.

Arguments

x, y, znumber

World position.

Returns

number1

screen x

number2

screen y

boolean3

visible: true when the point is in front of the camera. It can still be off the edge of the screen.

Example

local sx, sy, ok = draw.world_to_screen(p.head.x, p.head.y, p.head.z + 10)
if ok then draw.text(sx, sy, p.name, white) end

#draw.line3d

draw.line3d(a, b, col[, thickness])

A line between two world points. Drawn only when both ends are in front of the camera.

Arguments

a, bvector

colcolor

thicknessnumberoptional

Default 1.

#draw.circle3d

draw.circle3d(center, radius, col[, thickness])

A flat circle on the ground around a world point (32 segments).

Arguments

centervector

radiusnumber

Game units.

colcolor

thicknessnumberoptional

Default 1.

Example

draw.circle3d(me.pos, 60, color(120, 200, 255), 2)

#draw.box3d

draw.box3d(min, max, col[, thickness])

A 3D box outline between two corners.

Arguments

min, maxvector

Opposite corners.

colcolor

thicknessnumberoptional

Default 1.

#draw.load_image

draw.load_image(file)

Loads a PNG or JPG from the script's data folder. Do it once, outside on_frame.

Arguments

filestring

File name in scripts/data/<script>/.

Returns

integer | nil

Image handle, or nil when missing or invalid.

Up to 16 images per script, 2048 x 2048, 8 MB. Images are freed when the script unloads or reloads.

Example

local logo = draw.load_image("logo.png")

#draw.load_image_data

draw.load_image_data(bytes)

Loads an image from bytes in memory, for example the body of an http.get reply.

Arguments

bytesstring

PNG or JPG file contents.

Returns

integer | nil

Image handle.

#draw.image

draw.image(handle, x, y, w, h[, tint][, rounding])

Draws an image.

Arguments

handleinteger

From load_image.

x, y, w, hnumber

Where and how big.

tintcoloroptional

Multiplies the image. Default white (no change). Use color(255, 255, 255, a) to fade.

roundingnumberoptional

Corner radius.

#draw.image_size

draw.image_size(handle)

Original size of a loaded image. 0, 0 for a bad handle.

Arguments

handleinteger

Returns

integer1

width

integer2

height

#draw.load_font

draw.load_font(file[, size])

Loads a .ttf, .otf or .ttc font. Looks in the script's data folder first, then in Windows\Fonts.

Arguments

filestring

For example arial.ttf or segoeuib.ttf.

sizenumberoptional

Pixel size, 6 to 96. Default 16.

Returns

integer | nil

Font handle. The font is ready after the next font rebuild, usually one frame.

8 fonts in total across all scripts. Loading the same file and size again returns the same handle. Covers Latin, Latin Extended and Cyrillic.

Example

local big = draw.load_font("segoeuib.ttf", 28)

#draw.font_ready

draw.font_ready(handle)

True once the font can be used.

Arguments

handleinteger

Returns

boolean

#draw.text_font

draw.text_font(handle, x, y, text, col[, size])

Text in a loaded font. Uses the menu font until the font is ready.

Arguments

handleinteger

x, ynumber

textstring

colcolor

sizenumberoptional

Default: the size the font was loaded at.

#draw.text_size_font

draw.text_size_font(handle, text[, size])

Text size in a loaded font.

Arguments

handleinteger

textstring

sizenumberoptional

Returns

number1

width

number2

height