Script environment
Script discovery, sandbox, loading, reloading and cleanup; Lua 5.4 with a private environment per script.
Topics
Script folders
Each *.lua directly in C:\xhook <game>\scripts\ (system drive, created on first start) is its own script.
- Subfolders, hidden and system files are skipped; precompiled bytecode is refused.
- Script name is the file name without .lua.
- lib\ holds require() modules, config\<name>.cfg saved settings, data\<name>\ files.* and db.*.
Event handlers
callbacks.register(event, fn)callbacks.register("on_xxx", fn) adds a handler, callbacks.unregister removes one; global functions like on_paint never run.
- Event names are unchecked: "on_pain" registers and never fires.
- Unregistering mid-dispatch skips the rest of that dispatch.
Sandbox globals
Base functions, string, table, math, coroutine, utf8, a safe os, and every xhook library; memory, ffi and hook need the native tier.
- Missing: io, package, debug, dofile, collectgarbage. load runs text chunks only.
- _G is shared by all scripts; writing into it leaks everywhere.
- State survives hot reloads and toggles, not full Reload; persist with files.* or db.*.
require
require(name) -> any| Name | Type | Description |
|---|---|---|
| name | string | Path under scripts\lib\, no .lua. |
Loads scripts\lib\<name>.lua once, in the caller's environment; its registrations belong to the caller.
Returns Module's return value, or true.
- Cached per script; lib edits need the parent script reloaded.
- Dots are not folder separators: "a.b" loads a.b.lua.
- A missing file, bad name or syntax error raises an error.
Native tier
memory.*, ffi.* and hook.* exist only while "Raw memory access" is ON in the Scripts tab.
- Global to all scripts; a script cannot request it.
- Toggling reloads every script, loses state, and skips on_script_unload.
- Off means the namespaces are nil: test
if memory then ... end.
Errors
A failing callback stays registered; the error shows as a popup and an Output dock line.
- Load errors mark the script failed and drop everything it registered.
- An error in a task.* coroutine ends only that task.
- The same message reports at most once a second.
Limits
Each handler, task resume, UI callback or command gets 50 ms; top-level load gets 2 s.
- Overruns abort with "script exceeded CPU budget (50 ms)"; pcall cannot catch it.
- The whole Lua state has a 128 MB cap.
- Spread long work over frames with task.spawn and task.wait.
Threads
Render thread: on_paint, on_round_start, tasks, network.*, ui callbacks, keybinds; engine thread: on_create_move, on_weapon_fire, message events, on_sound, commands.
- One lock serialises both threads; script code never runs concurrently.
- draw.* in engine-thread events draws nothing; draw in on_paint.
Reload & cleanup
Files are polled every 250 ms; a changed file reloads only that script, keeping state and control values.
- Reload restarts every script and clears all state.
- Unload runs on_script_unload, then frees everything the script registered, saving control values first.
- Kept: engine.add_command commands (inert), draw.create_font fonts; chams.set overrides expire a frame later.
Per-script data
files.* and db.* use scripts\data\<name>\, so file names never collide; db.* stores key-value pairs in db.json.
- Paths with "..", ":" or a leading slash are rejected.
- A required module writes into the requiring script's folder.
- files.script_dir() returns the folder; unusual name characters become _.