xhookLua
Game

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
NameTypeDescription
namestringPath 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 _.
Script environment ยท Lua API ยท xhook