Script lifecycle
Script directories, the require search path, metadata tags, Library actions, load and unload order, error handling and what the configuration persists.
Directories and modules
| Purpose | Location |
|---|---|
| Scripts | %SystemDrive%\nix\scripts\ |
| Shared Lua modules | %SystemDrive%\nix\scripts\lib\ |
| Script data | %SystemDrive%\nix\script_data\<script file name without .lua>\ |
If SystemDrive is unset, the scripts directory is C:\nix\scripts.
The Library lists .lua files directly in the scripts directory; extension matching is case-insensitive. Subdirectories are not listed. The list is refreshed when the menu opens, when Refresh is selected, and after a file is deleted. Files are not watched for changes. Open folder creates and opens the scripts directory.
require 'name' uses the standard Lua loader with this search path:
scripts\?.lua;scripts\?\init.lua;scripts\lib\?.luaEach script loads its own copy of a module. C module loading through require is disabled because package.cpath is empty; this does not disable ffi.load.
Metadata
Metadata is read from comments at the beginning of the file without executing the script.
-- @name Watermark
-- @author you
-- @version 1.2
-- @description A boxed watermark in the top-right corner.| Tag | Limit | Behaviour |
|---|---|---|
@name | 128 bytes | First non-empty value; defaults to the file name without .lua. |
@author | 128 bytes | First non-empty value. |
@version | 128 bytes | First non-empty value. |
@description | 512 bytes | Multiple values are joined with spaces. |
The parser reads at most 4096 bytes and 64 lines. It skips a UTF-8 BOM and blank lines, and stops at the first non-comment line. Values are truncated at a UTF-8 boundary.
Supported comment forms are --, --- and --[[ ... ]]. Block comments may contain one tag per line; long-bracket forms such as --[==[ are not supported. Tags use @key value; keys are lowercase. Unknown keys are ignored.
Library actions
| Action | Effect |
|---|---|
| Load / Unload | Creates or closes the script's Lua state. Also available through the row's start/stop button. |
| Reload | Unloads the script, then loads its file again. |
| Open settings | Selects the script's settings sub-tab, if one exists. |
| Show in folder | Locates the script file. |
| Autoload | Saves the autoload flag in the configuration. |
| Copy error | Copies the full error and traceback. |
| Delete | Unloads the script and permanently deletes its file. |
Load and unload are available on the script card. Reload is in its title bar; Show in folder, Autoload, Copy error and Delete are in the card's overflow menu.
Load and unload order
On load:
- A new Lua state is created and the API is registered.
- The file executes from top to bottom.
- Registered callbacks begin on the next frame.
If execution fails during load, registered shutdown callbacks run and the state is closed.
On unload:
shutdowncallbacks run while the script's UI and controls are still available.- Control values, key binds and the settings of the script's ESP elements are retained for the next load.
- UI nodes, textures, particle effects, ESP elements, callbacks and timers are removed.
- The Lua state is closed, including
__gcprocessing.
utils.unload_script() schedules unloading at the end of the current frame, after render callbacks.
Errors
Calls into Lua are protected. Error handling depends on where the failure occurs:
| Context | Result |
|---|---|
| Initial file execution | The script remains unloaded and displays Error. |
| Callback | The failing callback is disabled until reload; other callbacks continue. |
| Timer | The timer is removed, including repeating timers. |
| UI handler | The failing handler is disabled; see the relevant UI method. |
| ESP element function | That element is disabled until reload and counts as a disabled callback; see esp errors. |
Errors include a file name, line number and traceback. They are printed in red in the game console as [lua] name.lua: ..., shown on the script card, and displayed as a notification containing the first line for five seconds. A loaded script with disabled callbacks displays Loaded · N callbacks disabled.
Non-string error values use __tostring, if available; otherwise the message is (error object is a <type> value).
An error whose message names a removed global, such as attempt to call global 'color_t' (a nil value), gets a second line naming the replacement, for example 'color_t' was removed from the Lua API; use color(r, g, b, a) instead.
Configuration and persistence
Lua globals, module state and upvalues are not shared between scripts and do not survive unload or reload. Files remain accessible through io, os and fs; Lua-state isolation is not filesystem isolation.
The configuration stores the following under each script's file name:
- loaded and autoload flags;
- control values, keyed by control ID;
- control key binds.
Renaming the file loses this association. Non-ASCII file names do not survive a configuration round trip. Hotkey modes, labels, item lists and tooltips are not saved; they are supplied by the script.
When a configuration is loaded:
- scripts marked loaded or autoload are loaded;
- scripts marked neither are unloaded;
- scripts that remain loaded receive the configuration's control values, triggering
on_changehandlers; - scripts absent from the configuration remain running.
Saving a configuration while a script is loaded records that loaded state, so the script is loaded with that configuration even without a separate autoload flag.