wolfhacklua API 1.1 Forum

Performance conventions

The overlay draws on the same thread your Lua runs on, so a slow script makes the overlay (and its frame rate) slow. The host protects itself with budgets; this page tells you what they are and how to stay far below them.

The budgets#

LimitValueWhat happens when you exceed it
Time for one callback3 ms (drawing and building a tab: 4 ms; first load: 400 ms; unload: 25 ms)The call is abandoned with an error and counted as a strike.
Instructions for one callback3 million (load: 120 million)Same.
Strikes5 within 20 secondsThe script is stopped (status Stopped).
Errors40 within 20 secondsThe script is stopped. A repeated message is logged once with a count.
All callbacks of one script in a frame10 msThe rest of that script's callbacks are skipped that frame.
Draw calls12 000 per frameThe rest are dropped and logged.
Lua memory32 MB (memory_mb in the manifest, 8 to 96)The allocation fails with an error in the script.
String patterns8 million steps per callpattern too expensive.

A well-behaved overlay script uses well under 1 ms per frame.

Measure it#

Select the script on the Scripts page and open the Manage tab: it shows per frame the average and worst time of all your callbacks, the number of calls, frames skipped by the 10 ms rule, the Lua memory (with its peak), strikes, and a breakdown per callback kind (draw, frame, a tab, ...). Look at the worst number as well as the average; a rare spike is what causes strikes.

Habits that keep a script cheap#

Do little per frame. Guard clauses first (if not snap.in_game then return end) so an idle script costs almost nothing.

Cache what does not change. Compute text, layouts and lookup tables when their inputs change, not every frame:

lua
local cached_text, cached_key
local function label(health)
  if health ~= cached_key then
    cached_key = health
    cached_text = string.format("%d hp", health)
  end
  return cached_text
end

Allocate outside the draw loop. Tables and strings created every frame become garbage the collector must clean. Build constant tables once at the top of the file; avoid table.insert into fresh tables inside draw.

Spread heavy work over frames. If you must process a lot, do a slice and task.yield():

lua
task.spawn(function()
  for i = 1, #big_list do
    process(big_list[i])
    if i % 200 == 0 then task.yield() end     -- 200 items a frame
  end
end)

Let the workers work. Network, picture decoding, shader compilation and memory scans run on worker threads; use them instead of doing the same in Lua.

Keep draw calls reasonable. A few hundred is cheap; draw.polyline with many points or per-pixel loops are not. For pixel-level effects use assets.canvas (tex:set_pixels with a prepared string) or a shader.

The overlay is idle when nothing draws#

A script with a draw handler, a visible widget, a timer, a task or a frame handler keeps the overlay drawing every frame. A script that only reacts to rare events costs nothing while idle. The Manage tab shows the effect.

Memory#

32 MB is plenty for a normal script. If you hit the limit, free what you hold (tables you no longer need), release textures with tex:free(), and only then raise memory_mb. collectgarbage("count") returns what the script uses, in KB.

Reading memory efficiently#

Each mem.read_* call is a system call. At most 8192 reads are allowed per frame. Read a block with mem.read_bytes and unpack with string.unpack instead of many small reads, and cache addresses that do not change (module bases, offsets).

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