Lua Chat Commands

Register custom chat commands in Lua, optionally restricted to operators or overriding built-in commands.

Mods can register custom chat commands (e.g. /ping, /heal) using Lua. Commands can be restricted to operators only, or open to all players. Mods can also override built-in commands by registering a command with the same name.

See lua-modding-overview.md for a general introduction to Lua modding.

Quick Example

commands-config.yaml (in your mod root):

commands:
  - name: "ping"
    permission: "everyone"
    scripts:
      server-on-command: /commands/ping.lua

commands/ping.lua:

return function(executor, args)
    executor:send_message("Pong!")
end

Register this file in your mod’s root YAML:

commands-config: commands-config.yaml

commands-config.yaml Field Reference

commands:
  - name: "my_command"       # Required. The command name (no leading slash, lowercase).
    permission: "everyone"   # Required. Exactly "everyone" or "operator", lowercase.
    scripts:
      server-on-command: /commands/my_command.lua  # Required. Path to a Lua file that returns its handler, relative to your mod root.

All three fields are required, and every entry is validated when your mod loads. A missing field, an unrecognised permission value, or a misspelled key causes that command to be rejected with an error in the server log naming the problem — it is never silently given a default. This is deliberate: a typo like permission: "opperator" must not quietly leave an operator command open to every player.

Multiple commands can be declared in the same file:

commands:
  - name: "ping"
    permission: "everyone"
    scripts:
      server-on-command: /commands/ping.lua

  - name: "heal"
    permission: "operator"
    scripts:
      server-on-command: /commands/heal.lua

Lua Function Signature

Every command function receives two arguments:

return function(executor, args)
    -- executor: the player who typed the command
    -- args: a Lua table of string arguments (1-indexed), excluding the command name itself
end

Example — /greet Alice Hello there:

• args[1] is "Alice"
• args[2] is "Hello"
• args[3] is "there"

Replying to the Executor

Use executor:send_message(text) to send a private reply visible only to the player who typed the command:

return function(executor, args)
    executor:send_message("Pong!")
end

To send a message visible to all players, use the global broadcast_server_message:

return function(executor, args)
    broadcast_server_message("Something happened!")
end

Executor Methods

The executor object is a full server entity object — see lua-server-entity.md for everything available on it. Frequently used in commands:

Permission Levels

These are the only two accepted values, and they must be written exactly as shown, in lowercase. Anything else is a load-time error rather than a fallback to "everyone". In singleplayer the local player is always treated as an operator.

To designate operators, edit server_config/server_config.yaml:

operators:
  - "Alice"
  - "Bob"

The value must match the player’s login ID (the name used to create their save file) exactly — not their display name.

Overriding Built-in Commands

Register a command with the same name as a built-in to replace it:

commands:
  - name: "list"             # Overrides the built-in /list
    permission: "everyone"
    scripts:
      server-on-command: /commands/list.lua

Built-in commands (always available unless overridden):

Full Example — /heal Operator Command

commands-config.yaml:

commands:
  - name: "heal"
    permission: "operator"
    scripts:
      server-on-command: /commands/heal.lua

commands/heal.lua:

return function(executor, args)
    local amount = tonumber(args[1]) or 20
    executor:heal(amount)
    executor:send_message("Healed for " .. amount .. " HP.")
end

Usage in game: /heal 50

Client-Only Commands

The following commands are processed entirely by the game client. They are not sent to the server and cannot be overridden or intercepted by mods.

The ignore list is stored locally on your machine. Each server you connect to maintains a separate ignore list.