draw
Immediate-mode 2D drawing: lines, shapes, text, images, gradients, meshes and shaders.
draw.* works only inside a draw event handler (screen coordinates), a widget's draw function (widget coordinates, clipped to the widget) and a ui.canvas callback (canvas coordinates, clipped). Anywhere else it raises "can only be called while drawing". Coordinates are pixels with (0, 0) at the top left. Colours are 0xRRGGBBAA.
A script may issue 12 000 draw calls a frame; the rest are dropped. A draw handler that issues a few hundred calls is cheap. See drawing.
Reference#
draw.line#since 1.0
draw.line(x1: number, y1: number, x2: number, y2: number, col: integer, thickness?: number)A straight line.
| Parameter | Type | Description |
|---|---|---|
x1 | number | Start x. |
y1 | number | Start y. |
x2 | number | End x. |
y2 | number | End y. |
col | integer | Colour. |
thickness optional | number | Line width in pixels. default 1 |
draw.rect#since 1.0
draw.rect(x: number, y: number, w: number, h: number, col: integer, rounding?: number)A filled rectangle.
| Parameter | Type | Description |
|---|---|---|
x | number | Left. |
y | number | Top. |
w | number | Width. |
h | number | Height. |
col | integer | Colour. |
rounding optional | number | Corner radius. default 0 |
draw.rect(20, 20, 200, 40, 0x101418E0, 8)draw.rect_outline#since 1.0
draw.rect_outline(x: number, y: number, w: number, h: number, col: integer, thickness?: number, rounding?: number)A rectangle outline.
| Parameter | Type | Description |
|---|---|---|
x | number | Left. |
y | number | Top. |
w | number | Width. |
h | number | Height. |
col | integer | Colour. |
thickness optional | number | Line width. default 1 |
rounding optional | number | Corner radius. default 0 |
draw.rect_gradient#since 1.0
draw.rect_gradient(x: number, y: number, w: number, h: number, tl: integer, tr: integer, br: integer, bl: integer)A rectangle with a colour in each corner, blended across.
| Parameter | Type | Description |
|---|---|---|
x | number | Left. |
y | number | Top. |
w | number | Width. |
h | number | Height. |
tl | integer | Top-left colour. |
tr | integer | Top-right colour. |
br | integer | Bottom-right colour. |
bl | integer | Bottom-left colour. |
draw.rect_gradient(20, 20, 200, 10, 0xFF0000FF, 0x0000FFFF, 0x0000FFFF, 0xFF0000FF)draw.circle#since 1.0
draw.circle(x: number, y: number, r: number, col: integer, filled?: boolean, thickness?: number, segments?: integer)A circle.
| Parameter | Type | Description |
|---|---|---|
x | number | Centre x. |
y | number | Centre y. |
r | number | Radius. |
col | integer | Colour. |
filled optional | boolean | Fill the circle. default true |
thickness optional | number | Outline width when not filled. default 1 |
segments optional | integer | Smoothness. default automatic |
draw.arc#since 1.0
draw.arc(x: number, y: number, r: number, a0: number, a1: number, col: integer, thickness?: number)Part of a circle's outline.
| Parameter | Type | Description |
|---|---|---|
x | number | Centre x. |
y | number | Centre y. |
r | number | Radius. |
a0 | number | Start angle in radians. |
a1 | number | End angle in radians. |
col | integer | Colour. |
thickness optional | number | Line width. default 1 |
draw.arc(100, 100, 30, 0, math.pi * 1.5, 0xFFFFFFFF, 3)draw.triangle#since 1.0
draw.triangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, col: integer, filled?: boolean, thickness?: number)A triangle.
| Parameter | Type | Description |
|---|---|---|
x1 | number | First corner x. |
y1 | number | First corner y. |
x2 | number | Second x. |
y2 | number | Second y. |
x3 | number | Third x. |
y3 | number | Third y. |
col | integer | Colour. |
filled optional | boolean | Fill it. default true |
thickness optional | number | Outline width. default 1 |
draw.polyline#since 1.0
draw.polyline(points: number[][] | number[], col: integer, thickness?: number, closed?: boolean)Connected line segments.
| Parameter | Type | Description |
|---|---|---|
points | number[][] | number[] | {{x, y}, ...} or a flat {x1, y1, x2, y2, ...}; at most 512 points. |
col | integer | Colour. |
thickness optional | number | Line width. default 1 |
closed optional | boolean | Join the last point to the first. default false |
draw.polygon#since 1.0
draw.polygon(points: number[][] | number[], col: integer)A filled convex polygon.
| Parameter | Type | Description |
|---|---|---|
points | number[][] | number[] | The corners, at most 512. The shape must be convex. |
col | integer | Colour. |
draw.bezier#since 1.0
draw.bezier(x1: number, y1: number, c1x: number, c1y: number, c2x: number, c2y: number, x2: number, y2: number, col: integer, thickness?: number)A cubic Bézier curve.
| Parameter | Type | Description |
|---|---|---|
x1 | number | Start x. |
y1 | number | Start y. |
c1x | number | First control point x. |
c1y | number | First control point y. |
c2x | number | Second control point x. |
c2y | number | Second control point y. |
x2 | number | End x. |
y2 | number | End y. |
col | integer | Colour. |
thickness optional | number | Line width. default 1 |
draw.text#since 1.0
draw.text(x: number, y: number, col: integer, text: string, options?: table)Draws text. Note the argument order: the colour comes before the text.
| Parameter | Type | Description |
|---|---|---|
x | number | Anchor x. |
y | number | Top y. |
col | integer | Colour. |
text | string | The text. |
options optional | table | {font, size, shadow, outline, align}. font is a Font; size is in pixels; shadow and outline are booleans; align is "left", "center" or "right", relative to x. |
draw.text(100, 50, 0xFFFFFFFF, "hello", { size = 18, shadow = true })draw.text_size#since 1.0
draw.text_size(text: string, options?: table): number, numberMeasures text so you can size a background around it.
| Parameter | Type | Description |
|---|---|---|
text | string | The text. |
options optional | table | The same options as draw.text. |
| Returns | Description |
|---|---|
number | Width. |
number | Height. |
local w, h = draw.text_size("hello", { size = 16 })draw.clip#since 1.0
draw.clip(x: number, y: number, w: number, h: number)Limits drawing to a rectangle until draw.unclip.
| Parameter | Type | Description |
|---|---|---|
x | number | Left. |
y | number | Top. |
w | number | Width. |
h | number | Height. |
draw.unclip#since 1.0
draw.unclip()Removes the clip made by draw.clip.
draw.alpha#since 1.0
draw.alpha(a: number)Multiplies the opacity of everything drawn after it. Use it to fade a whole panel.
| Parameter | Type | Description |
|---|---|---|
a | number | Opacity multiplier, 0 to 1. |
draw.size#since 1.0
draw.size(): number, numberThe size of what you are drawing into: the screen in a draw handler, the widget in a widget, the canvas in a canvas.
| Returns | Description |
|---|---|
number | Width of the drawing area. |
number | Height. |
draw.image#since 1.0
draw.image(tex: Texture, x: number, y: number, w: number, h: number, options?: table)Draws a texture. A texture that has not finished loading draws nothing; check tex:ready() or task.await it.
| Parameter | Type | Description |
|---|---|---|
tex | Texture | A texture. |
x | number | Left. |
y | number | Top. |
w | number | Width. |
h | number | Height. |
options optional | table | {tint, rounding, rotation, uv}: a colour tint, a corner radius, a rotation in radians, and uv = {u0, v0, u1, v1} to draw part of the picture. |
draw.model#since 1.0
draw.model(x: number, y: number, w: number, h: number, options?: table)Draws the built-in player model. It renders on a worker thread and the pictures are cached.
| Parameter | Type | Description |
|---|---|---|
x | number | Left. |
y | number | Top. |
w | number | Width. |
h | number | Height. |
options optional | table | {yaw = degrees, team = "ct" | "t", tint}. |
draw.mesh#since 1.0
draw.mesh(vertices: number[], indices: integer[], options?: table)Draws a small 3D mesh, turned, perspective projected and flat shaded in software.
| Parameter | Type | Description |
|---|---|---|
vertices | number[] | Flat {x, y, z, x, y, z, ...}. |
indices | integer[] | 1-based vertex index triples; at most 4096 triangles. |
options optional | table | {x, y, scale, yaw, pitch, roll, distance, color, light, wire}. |
draw.shader_rect#since 1.0
draw.shader_rect(shader: Shader, x: number, y: number, w: number, h: number, params?: number[])Fills a rectangle with a pixel shader. A shader that is not ready yet draws nothing.
| Parameter | Type | Description |
|---|---|---|
shader | Shader | A shader made with assets.shader. |
x | number | Left. |
y | number | Top. |
w | number | Width. |
h | number | Height. |
params optional | number[] | Up to 16 numbers, available in the shader as u_p[0..3]. |