Lifecycle, callbacks, and workers
Understand callbacks and how a module pauses between updates.
A loaded module can define these optional callbacks:
| Callback | When it runs | Arguments |
|---|---|---|
on_start() | After top-level source succeeds; also allowed in instant scripts | None |
on_tick(dt) | Repeatedly while a module is running | Seconds since the previous call |
on_stop() | During a normal module unload | None |
on_http(requestId, status, body, error) | When an async HTTP request completes | ID, status, response, error text |
on_defense(event) | For events selected with defense.watch | Defense event table |
on_defense receives the skill, phase, action, and result for events your module watches. See Auto Defense for the fields.
Background worker
Use script.start_worker(function) once from a module for work that needs to pause between steps. script.sleep(milliseconds) pauses only that worker; the allowed delay is 0–3,600,000 ms. Do not use a tight loop in on_tick.
function on_start()
local ok, err = script.start_worker(function()
while true do
local position = game.local_position()
if position then
log.info(string.format("X %.1f", position.x))
end
script.sleep(500)
end
end)
if not ok then log.error(err) end
endscript.start_worker returns true or nil, error when a worker cannot start or is already running. An uncaught worker error stops the module. Unloading stops its worker.
Use os.clock() for CPU time and os.time() for a calendar timestamp. Use script.sleep() to pause a worker.
Persistent module state
script.state_set(key, value) stores a nonempty string of up to 64 KiB across module reloads; script.state_get(key) reads it. Keys use the same 1–64 character ID rule. The setter returns true or nil, error; the getter returns a string, nil for a missing key, or nil, error on read failure. Instant scripts receive nil, error for both calls.
function on_start()
local text = script.state_get("counter")
log.info("previous count: " .. (text or "0"))
local ok, err = script.state_set("counter", tostring((tonumber(text) or 0) + 1))
if not ok then log.warn(err) end
end