Resource cleanup
A script can stop for several reasons: the user switches it off, presses Reload, removes it, the host stops it (too many budget strikes or errors), or the overlay closes. The host releases what the script registered in each case, so you rarely have to clean up by hand. One difference: your unload handler runs when the script is switched off, reloaded, removed or the overlay closes, but not for a script the host has already stopped for misbehaving.
What is released automatically#
In this order:
- Your
unloadhandler runs (25 ms budget). - The store is saved.
- Network requests in flight and memory scans are cancelled.
- Memory writes made with
mem.write_*are undone, unless the game changed those bytes since. (For a script the host stopped, this happens at the moment it is stopped.) - Tasks, timers, event handlers, tabs, windows, widgets and themes are removed. The menu's colours are restored at once.
- Textures and shaders are released, after the frame that may still be drawing them.
- The Lua state itself is freed.
The test suite verifies this: after a script is unloaded the Lua allocator's byte count is back to zero and no handler or registration is left behind.
What is not released#
- Fonts. The overlay's font atlas cannot drop one font, so a font your script loaded with
assets.fontstays in memory until the overlay restarts. Loading the same font again costs nothing, so reloading a script does not grow it. At most 8 fonts per script and 24 in all. - Files and saved settings. Your data folder and the store stay on disk. That is what lets settings survive a reload.
Your unload handler#
Use it for the things only you know about:
events.on("unload", function()
store.set("lifetime", lifetime) -- final save
log.info("goodbye")
end)It must be quick: 25 ms. Do not start new timers, requests or tasks in it; they are cancelled immediately.
Reload gives you a fresh start#
Reload unloads the script and runs its files again. Everything in local variables is gone; only the store, files and fonts remain. Write your main chunk so that running it from the top is always safe: register callbacks once, read saved state from the store, and do not assume anything survives.
Free big things early#
tex:free() releases a texture before the script ends, which matters for scripts that load many pictures one after another (the limit is 64 textures and 64 MB). Cancel a request you no longer need with req:cancel(), a scan with scan:cancel(), a timer with timer.cancel(id) and a task with task.cancel(id).
Memory writes are different#
If your script uses mem.write_*, remember that stopping the script reverts the game. That is the point of the safety net, but it also means a script that sets a value once and then does nothing is undone when it stops. To keep a value changed, the script has to stay running, and to restore it earlier use mem.undo(addr) or mem.undo_all(). If the game was restarted in between, old writes are forgotten instead of undone. See mem.
Checklist#
- Register events, timers, tabs, windows and widgets once at load.
- Save state in
unload, and also periodically withtimer.everyif losing it would hurt. - Do not keep references to things you have freed.
- Use
mem.can_write()rather than letting a denied write raise an error every frame.