Canvas
The canvas module provides an HTML5 \<canvas> overlay for custom 2D drawing composited on top of the final rendered viewport. You can this API to render shapes, text, gradients, and other graphics on top of your scene. For more detailed behavior, refer to the HTML Canvas API which this LUA api is built on top of.
Rendering behavior
The Canvas module renders into a dedicated 2D buffer that is composited after all regular scene rendering has finished. Canvas content is alpha-blended over the final viewport image and does not interact with the 3D render pipeline, including depth testing or post-processing passes. Drawn content persists across frames until it is explicitly cleared using Canvas.clear() or Canvas.clearRect().
Canvas commands may be issued at any time, but for predictable behavior and to avoid redundant work, it is recommended to update dynamic Canvas content from a render-related lifecycle callback such as rendergui().
Usage
To use this module, add the following require at the top of your script:
Reference
commit
Commit all pending buffered canvas commands.
Returns
table|nil: Optional engine-side debug info.
getPendingCommandCount
Debug helper: returns count of pending buffered commands in Lua.
Returns
number
getPendingCommands
Debug helper: returns current pending buffered commands in Lua.
Returns
table
getLastCommittedCommands
Debug helper: returns most recently committed command list on engine side.
Returns
table
clear
Clear the canvas.
getWidth
Returns the width of the canvas in pixels.
getHeight
Returns the height of the canvas in pixels.
setLineWidth
Sets the width of lines in the canvas.
Parameters
w(number): the width to set the lines to.
setLineCap
Sets the type of endings applied to the ends of a line.
Parameters
cap(string): the type of corner to create on a line. One of "butt", "round", "square".
setLineJoin
Sets the type of corner created when two lines meet.
Parameters
join(string): the type of connection to create between two lines. One of "bevel", "round", or "miter".
setMiterLimit
Sets the maximum miter length. Miter length is the distance between the inner corner and the outer corner of the join.
Parameters
limit(number): the maximum miter length. When the miter length exceeds this value, the corner is trimmed.
setStrokeColor
Sets the color of the stroke (outline) for shapes drawn on the canvas.
Parameters
r(number): Red channel value (0–255)g(number): Green channel value (0–255)b(number): Blue channel value (0–255)a(number): Alpha channel value (0–1)
setFillColor
Sets the color that is used to fill in shapes and text when they are drawn on the canvas.
Parameters
r(number): Red channel value (0–255)g(number): Green channel value (0–255)b(number): Blue channel value (0–255)a(number): Alpha channel value (0–1)
setShadowColor
Sets the color to use for shadows.
Parameters
r(number): Red channel value (0–255)g(number): Green channel value (0–255)b(number): Blue channel value (0–255)a(number): Alpha channel value (0–1)
setShadowBlurLevel
Sets the blur level for shadows.
Parameters
level(number): the level of blur to be applied to shadows (in pixels).
setShadowOffset
Sets the blur level for shadows.
Parameters
x(number): the vertical offset of the shadow in pixels.y(number): the horizontal offset of the shadow in pixels.
beginPath
Begins a new path.
closePath
Close the current path by connecting the last and first point in the path, creating a loop.
isPointInPath
Determines if the specified point is in the current path.
Parameters
x(number): x-coordinate of the point to check.y(number): y-coordinate of the point to check.
Returns
boolean: if the point is in the path or not.
clip
Sets the clipping path to the current drawing path.
stroke
Draws the outline of a shape or path using the current stroke style, line width and styles.
fill
Fills a shape or path with the current fill style.
moveTo
Moves the current drawing position to the specified coordinates.
Parameters
x(number): x-coordinate of the new current drawing position.y(number): y-coordinate of the new current drawing position.
lineTo
Draws a straight line from the current position to the specified coordinates.
Parameters
x(number): the x-coordinate to draw the line to.y(number): the y-coordinate to draw the line to.
setCompositeOperation
Sets the type of compositing operation to apply when drawing new shapes.
Parameters
operation(string): the compositing operation to use, possible values are: "source-over", "source-in", "source-out", "source-atop", "destination-over", "destination-in", "destination-out", "destination-atop", "lighter", "copy", "xor".
setGlobalAlpha
Sets the transparency value that is applied to all rendering operations.
Parameters
value(number): a value between 0.0 (fully transparent) and 1.0 (fully opaque).
pathRect
Creates a rectangle path which is only drawn after calling stroke() or fill().
Parameters
x(number): x-coordinate of the rectangle upper-left corner.y(number): y-coordinate of the rectangle upper-left corner.w(number): width of the rectangle.h(number): height of the rectangle.
roundRect
Adds a rounded rectangle to the current path. Must be followed by stroke() or fill().
Parameters
x(number): x-coordinate of the rectangle upper-left corner.y(number): y-coordinate of the rectangle upper-left corner.w(number): width of the rectangle.h(number): height of the rectangle.radius(number|table): corner radius applied to all four corners (uniform), or a table of 1–4 values to set individual corner radius in the order [top-left, top-right, bottom-right, bottom-left], following the HTML Canvas API specification.
strokeRect
Draw a rectangle outline using the current stroke style.
Parameters
x(number): x-coordinate of the rectangle upper-left corner.y(number): y-coordinate of the rectangle upper-left corner.w(number): width of the rectangle.h(number): height of the rectangle.
fillRect
Draw a rectangle with a filled interior using the current fill style,
Parameters
x(number): x-coordinate of the rectangle upper-left corner.y(number): y-coordinate of the rectangle upper-left corner.w(number): width of the rectangle.h(number): height of the rectangle.
clearRect
Clears the specified rectangle by setting its pixels to transparent.
Parameters
x(number): x-coordinate of the rectangle upper-left corner.y(number): y-coordinate of the rectangle upper-left corner.w(number): width of the rectangle.h(number): height of the rectangle.
circle
Draws a circle with given parameters. Must be followed by stroke() or fill().
Parameters
x(number): x-coordinates of the center of the circle.y(number): y-coordinates of the center of the circle.r(number): the radius of the circle
arc
Draws an arc with given parameters. Must be followed by stroke() or fill().
Parameters
x(number): x-coordinates of the center of the circle.y(number): y-coordinates of the center of the circle.r(number): the radius of the circle.startAngle(number): the starting angle in radians.endAngle(number): the ending angle, in radians.anticlockwise(boolean): a flag which specifies whether the drawing should be counterclockwise or clockwise.
quadraticCurve
Adds a quadratic Bézier curve to the path with given control point and end point.
Parameters
cpx(number): x-coordinate of the control point.cpy(number): y-coordinate of the control point.x(number): x-coordinate of the end point.y(number): y-coordinate of the end point.
bezierCurve
Draws a bezier curve from the current position to the specified point, using the specified control points.
Parameters
cp1x(number): x-coordinate of the first control point.cp1y(number): y-coordinate of the first control point.cp2x(number): x-coordinate of the second control point.cp2y(number): y-coordinate of the second control point.x(number): x-coordinate of the end point.y(number): y-coordinate of the end point.
setGradientActive
Sets a gradient object to active.
Parameters
gradient(Gradient): a gradient object
colorStop
Adds a new stop, defined by an offset and a color, to a gradient object.
Parameters
gradient(Gradient): a gradient objectoffset(number): a value between 0.0 and 1.0 where the new color stop is positioned.r(number): Red channel value (0–255)g(number): Green channel value (0–255)b(number): Blue channel value (0–255)a(number): Alpha channel value (0–1)
createLinearGradient
Creates a linear gradient object.
Parameters
x1(number): the x-coordinate of the start point of the gradienty1(number): the y-coordinate of the start point of the gradientx2(number): the x-coordinate of the end point of the gradienty2(number): the y-coordinate of the end point of the gradient
Returns
Gradient: new gradient object
Example
createRadialGradient
Creates a radial gradient object.
Parameters
x1(number): x-coordinate of the start circley1(number): y-coordinate of the start circler1(number): radius of the start circlex2(number): x-coordinate of the end circley2(number): y-coordinate of the end circler2(number): radius of the end circle
Returns
Gradient: new gradient object
getAvailableFonts
Returns an array with strings of all available fonts. This will list all custom loaded fonts through Loader.loadFont and fonts registered in Canvas Fonts in your project. It will also probe for common system fonts although the list might not be complete. It is strongly recommended to use only custom uploaded fonts to have reliable results on all platforms.
Returns
table: array with all the available fonts as strings
setFont
Sets a font style.
Parameters
font(string): The font style to be set, in the format of 'font-style font-size font-family'. Example: 'italic 20px Arial'.
setTextAlign
Sets the current text alignment
Parameters
align(string): The new text alignment to be set. One of 'start', 'end', 'left', 'right', or 'center'.
setTextBaseline
Sets the text baseline used when drawing text.
Parameters
baseline(string): The text baseline to set. One of 'alphabetic', 'top', 'hanging', 'middle', 'ideographic', or 'bottom'.
measureTextWidth
Measures the width of the specified text in pixels.
Parameters
text(string): The text to measure.
fillText
Draws and fills a given text string at the specified coordinates.
Parameters
text(string): The text string to be drawn and filled.x(number): The x-coordinate where the text will be drawn.y(number): The y-coordinate where the text will be drawn.
strokeText
Draws the outline of the given text at the specified coordinates.
Parameters
text(string): The text string to be drawn.x(number): The x-coordinate where the text will be drawn.y(number): The y-coordinate where the text will be drawn.
drawImage
Draws the image data at the given coordinates.
Parameters
image(Texture): the image data to paintx(number): x-coordinate of the top left corner where the image data will be paintedy(number): y-coordinate of the top left corner where the image data will be paintedwidth(number): width of the image on screen (optional)height(number): height of the image on screen (optional)mode(number): mode to use for stretching. possible values are 0 = stretch, 1 = fit, 2 = cover
drawSubImage
Draws the image data at the given coordinates.
Parameters
image(Texture): the image data to paintx(number): x-coordinate of the top left corner where the image data will be paintedy(number): y-coordinate of the top left corner where the image data will be paintedwidth(number): width of the image on screen (optional)height(number): height of the image on screen (optional)sourceXsourceYsourceWidthsourceHeight
scale
Scales the canvas by the specified factors along the x and y axes. Transformations are applied relative to the canvas origin (0,0). To scale around a different point, use translate() to move the origin before scaling.
Parameters
x(number): Scale factor along the x-axis.y(number): Scale factor along the y-axis.
rotate
Rotates the canvas by the specified angle in radians. Rotation is performed around the canvas origin (0,0). To rotate around a different point, translate the canvas to that point before calling rotate().
Parameters
a(number): Angle in radians.
translate
Moves (translates) the canvas origin by the specified amounts. All subsequent drawing and transformations (scale, rotate, etc.) are relative to the new origin.
Parameters
x(number): Amount to translate along the x-axis.y(number): Amount to translate along the y-axis.
transform
static transform(horizontal_scale, horizontal_skew, vertical_skew, vertical_scale, horizontal_translation, vertical_translation)
Applies a 2D transformation matrix to the canvas.
Parameters
horizontal_scale(number): The amount to scale horizontally.horizontal_skew(number): The amount of horizontal skew.vertical_skew(number): The amount of vertical skew.vertical_scale(number): The amount to scale vertically.horizontal_translation(number): The amount of horizontal translation.vertical_translation(number): The amount of vertical translation.
resetAndSetTransform
static resetAndSetTransform(horizontal_scale, horizontal_skew, vertical_skew, vertical_scale, horizontal_translation, vertical_translation)
Resets the current canvas transform to the identity matrix and then invokes the transform() function with the given parameters.
Parameters
horizontal_scale(number): The amount to scale horizontally.horizontal_skew(number): The amount of horizontal skew.vertical_skew(number): The amount of vertical skew.vertical_scale(number): The amount to scale vertically.horizontal_translation(number): The amount of horizontal translation.vertical_translation(number): The amount of vertical translation.
resetTransform
Reset the transformation matrix to the identity matrix.
saveState
Pushes the current canvas state to a stack so that you can restore it. This can be useful for performing multiple transformations or styles on the canvas, and then restoring it to its original state. The canvas state in fact includes current transformation matrix stroke and fill styles, shadow styles, and other attributes. To restore the canvas state you call the restoreState() function.
restoreState
Pops the the most recently saved canvas from the saved state stack and restores it.
reset
Resets the canvas to its default state, clearing the canvas and restoring all context -properties (transforms, styles, clipping region, etc.) to their defaults. Reset() is more thorough than -calling clear() alone, which only erases pixels but leaves context state intact.
Class: Gradient
Examples
local Canvas = require 'engine/canvas'
Canvas.setLineWidth(10)
Canvas.strokeRect(75, 140, 150, 110)
Canvas.fillRect(130, 190, 40, 60)
Canvas.beginPath()
Canvas.moveTo(50, 140)
Canvas.lineTo(150, 60)
Canvas.lineTo(250, 140)
Canvas.closePath()
Canvas.stroke()
local Canvas = require 'engine/canvas'
Canvas.beginPath()
Canvas.moveTo(300, 100)
Canvas.quadraticCurve(250, 350, 500, 120)
-- or you can create a bezierCurve
Canvas.bezierCurve(100, 200, 300, 200, 300, 120)
Canvas.stroke()
Canvas.closePath()
local Canvas = require 'engine/canvas'
local gradient1 = Canvas.createLinearGradient(0, 0, 50, 0)
Canvas.colorStop(gradient1, 0, 255, 0, 0, 0)
Canvas.colorStop(gradient1, 1, 0, 0, 255, 0.5)
Canvas.setGradientActive(gradient1)
Canvas.fillRect(0, 0, 75, 75)
local gradient2 = Canvas.createLinearGradient(0, 0, 0, 50)
Canvas.colorStop(gradient2, 0, 255, 0, 0, 0)
Canvas.colorStop(gradient2, 0.3, 128, 128, 0, 0.5)
Canvas.colorStop(gradient2, 0.65, 0, 0, 0, 0.5)
Canvas.colorStop(gradient2, 1, 0, 0, 255, 0.5)
Canvas.setGradientActive(gradient2)
Canvas.fillRect(75, 0, 75, 75)
local gradient3 = Canvas.createRadialGradient(85, 88, 5, 88, 90, 69)
Canvas.colorStop(gradient3, 0, 128, 128, 0, 0.5)
Canvas.colorStop(gradient3, 1, 128, 128, 0, 0.5)
Canvas.setGradientActive(gradient3)
Canvas.circle(250, 100, 60)
Canvas.fill()
local Canvas = require 'engine/canvas'
local screenWidth = Canvas.getWidth()
local screenHeight = Canvas.getHeight()
Canvas.setFillColor(255, 0, 0, 1)
Canvas.setFont("italic 12px Arial")
Canvas.saveState()
Canvas.setFillColor(0, 255, 0, 1)
Canvas.setFont("20px Arial")
-- Canvas.moveTo(5, 350)
Canvas.rotate(0.25)
Canvas.fillText("Rotated state", screenWidth/2, screenHeight/2)
-- Restoring a state will also restore fill/stroke color
-- and all transformation to the canvas
Canvas.restoreState()
Canvas.fillText("Original state restored!", screenWidth/2, screenHeight/2)
local Canvas = require 'engine/canvas'
Canvas.setFillColor(255, 0, 0, 0.4)
Canvas.fillRect(20, 20, 75, 50)
Canvas.setCompositeOperation("source-over")
Canvas.setFillColor(255, 0, 0, 1)
Canvas.fillRect(50, 50, 75, 50)
Canvas.setFillColor(255, 0, 0, 1)
Canvas.fillRect(150, 20, 75, 50)
Canvas.setCompositeOperation("destination-over")
Canvas.setFillColor(0, 0, 255, 1)
Canvas.fillRect(180, 50, 75, 50)
local Canvas = require 'engine/canvas'
Canvas.setFillColor(255, 0, 0, 0.4)
Canvas.setShadowColor(0, 255, 0, 1)
Canvas.setShadowBlurLevel(10)
Canvas.setShadowOffset(25, 10)
Canvas.fillRect(50, 50, 100, 100)
local Canvas = require 'engine/canvas'
Canvas.beginPath()
Canvas.pathRect(50, 20, 200, 120)
Canvas.stroke()
Canvas.clip()
Canvas.setFillColor(255, 0, 0, 1)
Canvas.fillRect(0, 0, 150, 100)
local Canvas = require 'engine/canvas'
local screenWidth = Canvas.getWidth()
local screenHeight = Canvas.getHeight()
Canvas.setLineJoin("miter")
Canvas.setMiterLimit(5)
Canvas.setLineCap("square")
Canvas.beginPath()
Canvas.setLineWidth(50)
Canvas.moveTo(50, 80)
Canvas.lineTo(screenWidth/2, screenHeight/2)
Canvas.lineTo(50, screenHeight-80)
Canvas.stroke()