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#
| Limit | Value | What happens when you exceed it |
|---|---|---|
| Time for one callback | 3 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 callback | 3 million (load: 120 million) | Same. |
| Strikes | 5 within 20 seconds | The script is stopped (status Stopped). |
| Errors | 40 within 20 seconds | The script is stopped. A repeated message is logged once with a count. |
| All callbacks of one script in a frame | 10 ms | The rest of that script's callbacks are skipped that frame. |
| Draw calls | 12 000 per frame | The rest are dropped and logged. |
| Lua memory | 32 MB (memory_mb in the manifest, 8 to 96) | The allocation fails with an error in the script. |
| String patterns | 8 million steps per call | pattern 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:
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
endAllocate 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():
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).