API reference
Colours are r, g, b from 0 to 255 unless noted. Coordinates start at the top-left pixel.
Functions you define
Section titled “Functions you define”| Function | Called |
|---|---|
_init() |
Once, after the script loads |
_update(dt) |
Every frame; dt in seconds, at most 0.25 |
_draw() |
Every frame, after _update |
fragment(x, y, u) |
By gfx.fill, for every pixel; returns r, g, b from 0 to 1 or one vec3 |
gfx: 2D
Section titled “gfx: 2D”| Call | Notes |
|---|---|
gfx.width(), gfx.height() |
Panel size in pixels |
gfx.cls(r, g, b) |
Fill the canvas; gfx.cls() is black |
gfx.pset(x, y, r, g, b) |
One pixel; off-canvas pixels are ignored |
gfx.rectfill(x, y, w, h, r, g, b) |
Filled rectangle, clipped to the canvas |
gfx.line(x0, y0, x1, y1, r, g, b) |
One-pixel line |
gfx.rgb(r, g, b) |
The colour as one 16-bit number |
gfx.pset565(x, y, packed) |
One pixel from a packed colour |
gfx: shaders
Section titled “gfx: shaders”| Call | Notes |
|---|---|
gfx.fill(fragment) |
Calls the Lua function for every pixel |
gfx.fill(shader) |
Runs a compiled shader for every pixel |
gfx.shader(bytecode) |
A compiled shader from its bytecode, as raw bytes or hex digits. The editor writes this line for you |
shader:set(name, value) |
Sets a uniform of a compiled shader: a number or a list of 2 to 4. Only needed for values that are not in the uniforms table |
See Fragment shaders and Interpreted and compiled.
gfx: 3D
Section titled “gfx: 3D”| Call | Notes |
|---|---|
gfx.mesh{ pos, normal, uv, color, index, mode } |
A mesh from lists of numbers |
gfx.cube(), gfx.sphere(segments), gfx.plane(divisions) |
Built-in meshes |
gfx.texture(w, h, pixels [, key]) |
A texture from hex digits; key is a transparent colour |
gfx.material{ color, shading, texture, cull, depth, blend, alpha } |
A material |
material:set{ ... } |
Change a material’s fields |
gfx.projection(m), gfx.view(m) |
The camera’s matrices; kept until changed |
gfx.ambient(r, g, b) |
Light from everywhere |
gfx.light(i, { dir or pos, color, range }), gfx.light(i, nil) |
Lights 1 to 4 |
gfx.fog(near, far, r, g, b), gfx.fog() |
Distance fog, and off |
gfx.draw(mesh, material [, model]) |
Draw a mesh |
gfx.project(x, y, z) |
Canvas x, y and depth of a world point; nothing if it is behind the camera |
gfx.clear_depth() |
Start a new 3D layer |
See 3D.
| Call | Notes |
|---|---|
mat4.identity() |
|
mat4.translate(x, y, z), mat4.scale(x, y, z) |
|
mat4.rotate_x(a), mat4.rotate_y(a), mat4.rotate_z(a) |
Radians |
mat4.perspective(fov, aspect, near, far) |
fov in degrees |
mat4.ortho(left, right, bottom, top, near, far) |
|
mat4.look_at(ex, ey, ez, tx, ty, tz, ux, uy, uz) |
Eye, target, up |
a * b |
Applies b, then a |
m:transform(x, y, z [, w]) |
Returns x, y, z, w |
Vectors and shader math
Section titled “Vectors and shader math”vec2, vec3, vec4 and the functions sin cos tan asin acos atan exp log sqrt abs floor ceil fract sign min max pow mod step clamp mix smoothstep dot length distance normalize cross hash noise fbm are globals. They are listed on the Shader built-ins page.
uniforms
Section titled “uniforms”A global table. Values sent to the panel from outside appear in it by name on the next frame; the script may read and write it; gfx.fill passes it to fragment as the third argument. See Animation and uniforms.
Lua itself
Section titled “Lua itself”Lua 5.4 with string, table, math, utf8 and coroutine. print(...) writes to the panel’s serial port, and to the console of the preview. Not available: io, os, debug, package, require, load, loadfile, dofile.