wolfhacklua API 1.1 Forum

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 writeCalledUse it for
events.on("frame", fn)Every frame, before the menu is builtLogic that does not draw; polling input
events.on("draw", fn)Every frame, on the overlay layerDrawing in screen coordinates
ui.widget{ draw = fn }Every frame the widget is visibleDrawing a draggable box
ui.tab(name, fn), ui.window{ body = fn }, ui.canvas(w, h, fn)Every frame the page, window or canvas is visibleBuilding an interface
timer.after(s, fn), timer.every(s, fn)After / every s secondsPeriodic work
task.spawn(fn)Resumed by the host after each pauseSequences with waits
net.get(url, fn), mem.scan(...)When the answer arrivesResults of background work
events.on("unload", fn)When the script is going awaySaving, last cleanup
events.on("ingame" / "map" / "bomb" / "menu" / "settings" / "media_track", fn)On the changeReacting 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.

lua
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#

  1. Finished asset uploads, network answers and memory scans are delivered.
  2. Timers and tasks run.
  3. frame handlers run.
  4. The menu is built, and with it your tabs and windows.
  5. The overlay layer is drawn: draw handlers, 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 check ready() before drawing them.
  • Keep state in local variables 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.

API 1.1 · source docs-src/pages/guide/callbacks.md