Callbacks and events
A script does not run in a loop of its own. When it loads, its main file runs once from top to bottom and registers callbacks: functions the overlay calls later. After that the script exists only as those callbacks and the variables they share.
The callbacks you can register#
| You write | Called | Use it for |
|---|---|---|
events.on("frame", fn) | Every frame, before the menu is built | Logic that does not draw; polling input |
events.on("draw", fn) | Every frame, on the overlay layer | Drawing in screen coordinates |
ui.widget{ draw = fn } | Every frame the widget is visible | Drawing a draggable box |
ui.tab(name, fn), ui.window{ body = fn }, ui.canvas(w, h, fn) | Every frame the page, window or canvas is visible | Building an interface |
timer.after(s, fn), timer.every(s, fn) | After / every s seconds | Periodic work |
task.spawn(fn) | Resumed by the host after each pause | Sequences with waits |
net.get(url, fn), mem.scan(...) | When the answer arrives | Results of background work |
events.on("unload", fn) | When the script is going away | Saving, last cleanup |
events.on("ingame" / "map" / "bomb" / "menu" / "settings" / "media_track", fn) | On the change | Reacting to what happened |
The events page lists every event with its arguments.
frame or draw?#
Both run every frame. The difference is what is allowed: draw.* functions only work inside a draw handler, a widget's draw, or a canvas callback, and anywhere else they raise "can only be called while drawing". Put drawing in draw, and everything else (updating state, reading input, timers' work) in frame, so the draw handler stays short.
local x = 0
events.on("frame", function(dt)
x = (x + 120 * dt) % 400 -- move 120 px per second, wrap at 400
end)
events.on("draw", function()
draw.circle(40 + x, 100, 8, 0xFFFFFFFF)
end)Order inside one frame#
- Finished asset uploads, network answers and memory scans are delivered.
- Timers and tasks run.
framehandlers run.- The menu is built, and with it your tabs and windows.
- The overlay layer is drawn:
drawhandlers, then widgets.
Because everything is on one thread, no two of your callbacks ever run at the same time, and you never need locks.
Every callback has a budget#
A callback gets 3 ms (drawing and building a tab get 4) and 3 million Lua instructions. Going over abandons that call with an error and counts a strike; five strikes in 20 seconds stop the script. All of one script's callbacks in a frame share 10 ms; callbacks that would run after that are skipped for the frame. If you need to do a lot, spread it over frames with task.yield(). See performance.
Errors inside callbacks#
An error raised in a callback is caught, logged to your console with a short traceback and counted; the callback is skipped this frame and called again next frame. Forty errors within 20 seconds stop the script. The same message repeated is logged once with a count. So a typo in a draw handler fills the console and eventually stops the script: read the first message.
Registering things in the right place#
- Register events, timers, tabs, windows and widgets once, in the main chunk (at load). A tab's function runs every frame, so registering a timer or an event inside it would add a new one every frame.
- Create assets (
assets.texture,assets.font) at load too, and checkready()before drawing them. - Keep state in
localvariables at the top of the file. They live as long as the script does, and are gone after a reload.
Removing a handler#
events.on returns an id: events.off(id) removes that handler. events.once(name, fn) removes itself after the first call. Everything is removed automatically when the script stops; see cleanup.