Lua scenes
From Zacess Scenes v1.1.0. Edit this page on GitHub
Zacess Scenes can run scenes of your own, written in Lua 5.4.
Lua is compiled into the program, so there is nothing to install. A user scene is listed by
zacess-scenes list and runs on its own like a built-in scene. It can also be picked for the watch
mode in scenes.toml, with --scene or with --fail-scene.
A user scene never chooses a colour. It names a role from the palette, such as accent or
syntax.keyword. The program draws that role in the active Zacess theme, which keeps a user
scene's text inside the same contrast floor as the built-in scenes: the text contrast the palette
sets for each theme, 7 to 1 on the first eight themes and 4.5 to 1 on Warm Dark and Warm Light. The same
flash limit applies too, measured while the scene runs.
Where scenes live
Each scene is one .lua file in the scenes folder next to scenes.toml:
| System | Folder |
|---|---|
| macOS and Linux | $XDG_CONFIG_HOME/zacess/scenes when XDG_CONFIG_HOME is set, otherwise ~/.config/zacess/scenes |
| Windows | %APPDATA%\zacess\scenes |
Every .lua file there is loaded when the program starts, in name order. A file that fails to load
is reported and left out; the rest still load.
Start a scene
zacess-scenes scene new pondThis writes pond.lua into the scenes folder with every part of the API commented. It refuses to
overwrite a file that is already there. Run the new scene with:
zacess-scenes pond
zacess-scenes watch --scene pondA finished example, a paper lantern swaying over still water, is in examples/scenes/lantern.lua. Copy it into the scenes folder to run it.
The script
A script returns a table. Only frame is required.
return {
name = "pond",
kind = "pass",
summary = "Slow ripples on a pond at dusk",
captions = { "All good.", "Still water and a clean build." },
init = function(ctx) end,
resize = function(ctx) end,
frame = function(ctx) end,
on_pass = function(ctx) return "Passed." end,
on_fail = function(ctx) return "Something to fix." end,
on_recovered = function(ctx) return "Fixed." end,
}| Field | Type | Meaning |
|---|---|---|
name |
string | The name used on the command line and in scenes.toml. Letters, digits and hyphens; _ and spaces become hyphens and capitals become lower case. It may not be the name of a built-in scene. Defaults to the file name without .lua |
kind |
string | pass for a passing build, fail for a failing one or general for either. Defaults to general |
summary |
string | One line shown by zacess-scenes list |
captions |
list of strings | Lines shown under the watch mode's banner, one per run in turn. Each is cut to 60 characters. Without any, the watch mode's own captions are used |
init |
function | Called once, before the first frame |
resize |
function | Called when the terminal changes size. ctx.width and ctx.height are already the new size |
frame |
function | Called once a frame, about 20 times a second. Move things on by ctx.dt seconds and draw them |
on_pass |
function | Called when the watch mode shows a passing build. May return a caption |
on_fail |
function | Called when the watch mode shows a failing build. May return a caption |
on_recovered |
function | Called when a failing build passes again. May return a caption |
A hook that returns a string replaces the caption for that moment. Returning nothing keeps the
caption from captions.
State lives in ordinary Lua variables, such as locals declared above the return. They keep their
values from one frame to the next.
The context
Every function is called with one argument, ctx:
| Field | Type | Meaning |
|---|---|---|
ctx.width |
integer | Columns on screen |
ctx.height |
integer | Rows on screen |
ctx.time |
number | Seconds since the scene started |
ctx.dt |
number | Seconds since the last frame, 0 in init and resize |
ctx.motion |
string | The motion level: calm, standard or lively |
ctx.reduced |
boolean | Whether reduced motion is on |
ctx.speed |
number | The factor to multiply movement by: 1 on standard, less on calm or under reduced motion and more on lively |
ctx.pace |
number | The factor for anything that changes in place, such as a pulse or a glow. It is never above 1, so lively cannot make a cell change faster |
ctx.busy |
number | The factor to multiply counts by: fewer things on calm and more on lively |
ctx.random() |
function | A number from 0 up to but not including 1 |
ctx.random(n) |
function | A whole number from 1 to n |
ctx.random(a, b) |
function | A whole number from a to b |
ctx.put(x, y, text, role) |
function | Draws text, see below. put on its own does the same |
ctx.pixel_width |
integer | Pixels across the canvas, the same as ctx.width |
ctx.pixel_height |
integer | Pixels down the canvas, twice ctx.height |
ctx.pixel, ctx.rect, ctx.disc, ctx.line, ctx.blend |
function | Paint solid pixels, see Pixels |
ctx.clock |
table or nil | The local date and time, see The clock |
ctx.random and math.random share one generator seeded from the program's, so a run with
--seed repeats exactly. math.randomseed does nothing.
Drawing
put(x, y, text, role)xandyare the column and row of the first character, counted from 0 at the top left. Fractions are rounded down. Anything outside the screen is left out, so a shape can sit half off an edge.textis drawn from left to right, spaces included. A number is drawn as its digits.roleis a palette role name. It defaults totext.- A character that some terminal fonts lack is drawn as
?. The safe set is printable ASCII, the middle dot·, the block and shade characters from▀to▟and the light box drawing lines─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼. - The screen starts empty each frame. Later calls draw over earlier ones.
- One frame may make at most 20,000
putcalls of up to 1,000 characters each.
Roles
| Role | Colour in the theme |
|---|---|
text |
The text colour (foreground also works) |
muted |
The muted text colour |
accent, link, info |
The interface colours of the same names |
error, warning |
The error and warning colours, with the theme's red or yellow where those are below the floor |
bright |
The strongest text colour: white on a dark theme and near black on a light one |
grey |
A grey that still reads on the background (gray also works) |
red, green, yellow, blue, magenta, cyan |
The terminal colours |
bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan |
The bright terminal colours |
syntax.keyword, syntax.control, syntax.function, syntax.type, syntax.string, syntax.number, syntax.comment, syntax.property, syntax.regex |
The syntax colours |
Names ignore case and accept - for _. A name that is not a role, such as a hex colour, is an
error. A terminal colour below the theme's floor is already fitted to it, as it is for the built-in
scenes: by its bright or plain twin, otherwise by the same hue at a lightness that keeps the floor
(see themes).
Colour is never the only signal in a Zacess scene. Give things different characters as well as
different roles, so the scene still reads with NO_COLOR set.
Pixels
Text is not the only way to draw. The same canvas the built-in scenes paint on is open to a
script: each character cell holds two square pixels, one above the other, so the canvas is
ctx.pixel_width pixels across and ctx.pixel_height pixels down, counted from 0 at the top left.
Pixels suit solid imagery such as hills, clouds, water or a drone; text suits words and fine detail.
| Function | Paints |
|---|---|
ctx.pixel(x, y, role, strength) |
One pixel |
ctx.rect(x, y, width, height, role, strength) |
A filled rectangle |
ctx.disc(x, y, radius, role, strength) |
A filled disc centred on a point |
ctx.line(x1, y1, x2, y2, role, strength) |
A line one pixel wide |
ctx.blend(x, y, role, amount) |
Moves the pixel already there amount of the way towards the role's colour |
- The role is a palette role as for
putand defaults totext. A pixel never takes a colour of its own, so imagery follows the theme like everything else. strengthruns from 0 (the theme's background) to 1 (the role's full colour) and defaults to 1. Anything between is mixed in the OKLab space, so0.25gives a faint wash and0.6a soft shade. Keep background imagery faint and give anything that carries meaning full strength, so it stands out from the background as the built-in scenes do.- Positions are rounded down and anything off the canvas is left out, so a shape can sit half off an edge. A rectangle or disc far bigger than the screen is cut to the screen.
- Pixels are painted first in the order they were called. Text is drawn over them. Text keeps the picture behind it only while it keeps its full contrast against it; where it would not, that cell falls back to the plain background. A space drawn over a picture leaves the picture as it is, so words can be laid out over imagery.
- The canvas starts empty each frame. One frame may make at most 50,000 pixel calls. Between them they may touch at most 64 screens' worth of pixels, counted after each shape is cut to the screen. Past that the rest of that frame's imagery is left out.
- Pixels count towards the flash limit like everything else, so a large area that lights up or goes dark at once is held back.
-- a soft cloud of overlapping discs and a sun, then words over the sky
ctx.disc(20, 8, 5, "muted", 0.35)
ctx.disc(27, 7, 6, "muted", 0.35)
ctx.disc(33, 9, 4, "muted", 0.35)
ctx.disc(ctx.pixel_width - 12, 10, 4, "yellow")
put(2, 1, "Good morning", "bright")A scene that should still run on an older version, from before pixels, can check for them first
with if ctx.rect then ... end.
The clock
ctx.clock is the local date and time in the system's time zone, refreshed once a second. It is a
fresh table each second, so changing a field changes nothing outside the script.
| Field | Example | Meaning |
|---|---|---|
hour, minute, second |
14, 5, 9 |
The time on a 24 hour clock |
time |
"14:05" |
The time as text |
year, month, day |
2026, 11, 7 |
The date |
weekday |
6 |
1 for Monday to 7 for Sunday |
weekday_name, month_name |
"Saturday", "November" |
The names in English |
date |
"Saturday 7 November 2026" |
The date as text |
It is nil when the system cannot say which time zone it is in, so a scene never shows a time
that might be hours out. It is missing too on versions from before the clock. A scene that uses it
checks first:
local c = ctx.clock
if c then
local part = c.hour < 5 and "night" or c.hour < 12 and "morning" or c.hour < 18 and "afternoon" or "evening"
put(2, 1, "Good " .. part .. ", it is " .. c.time, "text")
endIn a snapshot the clock does not read the system. It starts at Monday 1 June 2026 at 09:00 (or the
time --clock names) and moves on with --time, so a still is the same on every machine.
--state pass or --state fail runs the scene's on_pass or on_fail hook as it starts, so a
still can show what a scene does when a result arrives.
The sandbox
A script can only compute and draw:
- The libraries are
string,table,mathandutf8, plus the safe parts of the base library. - There is no
io,os,package,require,debug,coroutine,load,loadfile,dofile,collectgarbage,printorstring.dump. A script cannot read or write files, run programs, reach the network or load other code. - Only text chunks are loaded, never precompiled bytecode.
- A Lua state may use at most 32 MB of memory.
- Every call has an instruction budget: 20 million instructions for loading the file and
initand 2 million for eachframe,resizeand hook. A loop that never ends stops within a few milliseconds with an error instead of freezing the terminal.
Flashing
Every frame a user scene draws passes through the same flash meter the built-in scenes are tested
against. The meter splits the screen into twelve regions and works out how bright each one looks
from the characters and the luminance of their colours. A large change in any region counts as one
step. At most three large steps are let through in any second, which is at most one and a half
flashes a second: half the limit in the guidelines. A frame that would go over the limit is held
back and the last frame shown stays on screen instead. A scene that has more than ten frames held
back within ten seconds is stopped with the message <name> was stopped because it flashed too often.
Things that move, such as a drop falling or a boat drifting, keep each region about as bright as it
was and never count. To change something in place, such as a glow or a light in a window, change a
few cells at a time and keep the period in a named variable, as the example does with
GLOW_PERIOD. Multiply in-place rates by ctx.pace and movement by ctx.speed. Leave out
anything like lightning when ctx.reduced is true.
Errors
A script that fails to load is reported with its file name and line, such as
pond.lua:12: attempt to index a nil value. It is left out of the scene list and
zacess-scenes list prints the reason.
A script that fails while it runs is stopped and never called again. That covers a runtime error, an unknown role, the instruction budget, the memory limit and flashing. The last frame it drew stays until the program swaps in a built-in scene. In the watch mode the status bar names the scene and the problem, then a built-in scene of the same kind takes its place. The program never crashes because of a script.
A worked example
This scene draws a jar of fireflies on a shelf. The lights wander inside the jar and pulse slowly,
with the period kept in a variable and slowed by ctx.pace.
-- jar: fireflies in a glass jar on a shelf
local PULSE_PERIOD = 4 -- seconds per pulse, slow enough that no light blinks
local flies = {}
local function jar_box(ctx)
local w = math.min(16, ctx.width - 2)
local h = math.min(8, ctx.height - 2)
local left = math.floor((ctx.width - w) / 2)
local top = ctx.height - 1 - h
return left, top, w, h
end
return {
name = "jar",
kind = "pass",
summary = "Fireflies pulsing slowly in a glass jar on a shelf",
captions = { "Small lights and a clean build.", "All good in the jar." },
init = function(ctx)
for i = 1, math.max(2, math.floor(5 * ctx.busy)) do
flies[i] = { x = ctx.random(), y = ctx.random(), phase = ctx.random() * 6.28 }
end
end,
frame = function(ctx)
local left, top, w, h = jar_box(ctx)
-- the shelf, then the lid and the sides of the jar
put(0, ctx.height - 1, string.rep("=", ctx.width), "syntax.type")
put(left + 1, top - 1, string.rep("_", w - 2), "grey")
for y = top, ctx.height - 2 do
put(left, y, "|", "cyan")
put(left + w - 1, y, "|", "cyan")
end
-- each fly wanders a little and shows as a dot, an o or a star as it pulses
for _, fly in ipairs(flies) do
local wander = 0.2 * ctx.speed * ctx.dt
fly.x = math.min(1, math.max(0, fly.x + (ctx.random() - 0.5) * wander))
fly.y = math.min(1, math.max(0, fly.y + (ctx.random() - 0.5) * wander))
local level = math.sin(ctx.time * 2 * math.pi / PULSE_PERIOD * ctx.pace + fly.phase)
if level > -0.3 then
local ch = "."
local role = "yellow"
if level > 0.7 then
ch = "*"
role = "bright_yellow"
elseif level > 0.2 then
ch = "o"
end
local x = left + 1 + math.floor(fly.x * (w - 3))
local y = top + math.floor(fly.y * (h - 2))
put(x, y, ch, role)
end
end
end,
on_recovered = function(ctx)
return "Fixed. The jar glows again."
end,
}Save it as jar.lua in the scenes folder and run zacess-scenes jar.