render
2D and world-space drawing: text, lines, rectangles, circles, polygons, clipping, textures and screen queries, and when drawing is available.
Drawing is available while the frame's draw list is being recorded: in render callbacks and the frame's resize_window, key and timer processing. Draw calls from createmove, frame_stage, game events and override_view are silently discarded.
Queries (screen_size, frame_count, frame_time, calc_text_size, world_to_screen) and texture setup functions may be called outside this drawing phase.
Coordinates are window pixels measured from the top-left. Screen positions are 2D vectors; world positions are 3D vectors. Non-finite drawing coordinates produce no output. Integer thickness values below 1 produce no output. Rounding is clamped to half the smaller rectangle side.
Queries
| Function | Returns | Description |
|---|---|---|
render.screen_size() | vector2d | Window dimensions in pixels. |
render.frame_count() | number | Rendered-frame count. |
render.frame_time() | number | Seconds since the previous frame. |
render.world_to_screen(world) | vector2d or nil | Projects a 3D point. Returns nil behind the camera; off-screen points still return coordinates. |
render.calc_text_size(text, size?) | vector2d | Dimensions of text rendered by render.text. |
Each call returns a new copy; modifying it does not affect anything else.
render.text
render.text(text, pos, color?, size?)
render.text(text, font, pos, color?, size?)Draws text. The default colour is white; the default size is the menu font's size. The second form accepts font_t, but the API currently provides no function that returns one.
Returns: no values.
Lines and rectangles
render.line(from, to, color, thickness?)
render.rect(pos, size, color, rounding?)
render.rect_outline(pos, size, color, thickness?, rounding?)
render.rect_filled(from, to, color, rounding?)
render.rect_filled_fade(from, to, top_left, top_right, bottom_right, bottom_left)line: draws a line; thickness defaults to1.rect: fills the rectangle frompostopos + size.rect_outline: draws an outline using position and size.rect_filled: fills a corner-to-corner rectangle.rect_filled_fade: fills a rectangle with four corner colours in the order shown.
Returns: no values.
Circles and arcs
render.circle(center, color, radius, start_degrees?, fraction?)
render.circle(center, radius, segments, color, thickness?)
render.circle_filled(center, radius, segments, color)
render.circle_fade(center, radius, color_inner, color_outer)
render.arc(center, radius, from_radians, to_radians, segments, color, thickness?)The first circle form draws a filled disc, or a filled sector when fraction is below 1. Fraction is in 0..1; angle 0 points right and increases clockwise. The second form, selected by a numeric second argument, draws an outline.
circle_filled draws a filled disc. circle_fade draws a radial gradient. arc takes angles in radians, unlike the filled-sector form of circle.
The segments argument is required where shown but ignored.
Returns: no values.
Polygons and curves
render.polygon(points, color)
render.filled_polygon(points, color)
render.concave_polygon(points, color)
render.poly_line(points, color, thickness?, closed?)
render.bezier_cubic(p1, p2, p3, p4, color, thickness?)The three polygon functions fill a table of at least three 2D points. Concave polygons must not self-intersect.
poly_line joins the supplied points; closed defaults to true, joining the last point to the first. Pass false for an open line. bezier_cubic draws a screen-space cubic Bézier curve.
Returns: no values.
World-space circles
render.circle_3d(center, radius, color, thickness?, normal?)
render.circle_filled_3d(center, radius, color, normal?)
render.circle_fade_3d(center, radius, color_inner, color_outer, normal?)Draw an outline, filled circle or radial gradient in world space. Without normal, the circle lies flat on the ground. A circle is not drawn if any part is behind the camera.
Returns: no values.
Clipping
render.push_clip_rect(from, to, intersect?)
render.pop_clip_rect()Restricts subsequent drawing to the corner-to-corner rectangle. intersect = true intersects it with the current clip; otherwise it replaces the clip. Unmatched pushes are popped at the end of the frame.
Returns: no values.
Textures
render.setup_texture(filename)
render.setup_texture_rgba(pixels, size)
render.setup_texture_from_memory(bytes)
render.texture(texture, from, to, tint?, rounding?)setup_texture: loads PNG, JPEG or the first frame of a GIF. Relative paths use the game's working directory.setup_texture_rgba: accepts a table of exactlyw * hpacked pixels, row by row. Each integer isr + g*256 + b*65536 + a*16777216.setup_texture_from_memory: accepts a table of encoded PNG/JPEG/GIF bytes, not a Lua string.texture: draws corner to corner. A newly created texture becomes drawable on the next frame.
Returns: setup functions return texture_t or nil; texture returns no values.
Textures belong to the script and are freed on unload.