Scripting Automation

Scripting: Automation Scripts

Automation scripts drive running servers. They react to console output, send commands, and schedule lifecycle events (such as restarts).

Automation scripts share the same sandbox, Permissions Model, and meta declaration as Provider scripts, but they interact with a different set of APIs.

Registration & Lifecycle

When an automation script is enabled in the UI, it is loaded into a dedicated LState. The engine executes the script once to allow it to register its event hooks (often placed inside an optional register() function).

After registration, the script goes idle. The engine fires the hooks when relevant events occur. All hook callbacks are serialized in a single goroutine to ensure safe execution in gopher-lua.

Event Hooks

Use global on_* functions to register callbacks.

• on_log(id, callback): Triggered for every console line emitted by the server with the given id.
  • Requires Permission: console_read
• on_start(id, callback): Triggered when the server with the given id starts up.
• on_stop(id, callback): Triggered when the server shuts down.
• on_join(id, callback): Triggered when a player joins the server. Powered by the internal player tracker (EventBus) - no console regex parsing required.
  • Requires Permission: player_manage
• on_leave(id, callback): Triggered when a player leaves the server.
  • Requires Permission: player_manage
• schedule(seconds, callback): Runs an action periodically on a timer.
  • Requires Permission: schedule

Server Control API (server.*)

The server table provides commands to control server instances interactively.

• server.send(id, command): Writes a command to the target server's standard input (stdin).
  • Requires Permission: console_write
• server.start(id): Starts the server.
  • Requires Permission: server_control
• server.stop(id): Stops the server.
  • Requires Permission: server_control
• server.restart(id): Shuts down and restarts the server.
  • Requires Permission: server_control
• server.logs(id): Fetches the recent console history of a server. Returns a table containing a lines array.
  • Requires Permission: console_read
• server.list(): Returns a list of all registered servers.
  • Requires Permission: server_query
• server.info(id): Returns info for a single server, or nil if unknown.
  • Requires Permission: server_query
• server.players(id): Returns a list of players currently online.
  • Requires Permission: player_manage
• server.kick(id, name[, reason]): Kicks a player (server must be running).
  • Requires Permission: player_manage, console_write
• server.ban(id, target[, reason]): Bans a player or IP (server must be stopped).
  • Requires Permission: player_manage
• server.unban(id, target): Removes a ban (server must be stopped).
  • Requires Permission: player_manage
• server.bans(id): Returns the current ban list.
  • Requires Permission: player_manage

Built-in Logging

You can write messages to the engine's automation log by calling log(...) or print(...). This does not require any special permissions.

Navigation

• Back to the Scripting Hub