Plugin API

Everything below is a global in the plugin's Lua state, next to the standard library (string, table, math, utf8, os without its process functions, coroutine, pcall and the rest). Events are in Plugin events; packaging and limits are in Plugins.

A call with the wrong argument types raises a Lua error. In a handler, that error is logged and counts as a failure (five in a row disable the plugin).

Identity and logging#

log functions accept any value (converted to text) and cut lines at 4096 bytes. They return nothing.

config#

config is a table built from the plugin's .toml files (see Plugins). Values keep their TOML types: strings, integers, floats, booleans, arrays (1-based sequences) and tables. A key with a dash is also available with an underscore.

local lobby = config.lobby
local limit = config.limits.max_players

The table is built once when the plugin loads, so editing the files takes a reload to apply.

Text#

send, broadcast, kick and the console's send take a message in MiniMessage format (<red>, <gradient:aqua:green>Hi</gradient>, <click:...>). Plain text works as is. Every one resolves the message the same way:

1. A message that starts with @ is a key into the plugin's lang/*.toml files; the rest of the message is the key ("@shop.bought"). A key nobody defines is used as is, without the @.
2. Each {name} is replaced by the field name of the table given as the last argument, as text. A name the table does not have is left as {name}.
3. The result is cut at 4096 bytes.

broadcast("<yellow>{name} joined the proxy", { name = e.player_name })
local line = t("shop.bought", { item = "apple" })

Players#

A player is a table:

These are methods: call them with a colon. A player table is a snapshot of what the proxy knew when it was created, so player.server does not follow later moves; look the player up again or use the player.server_change event.

A player appears in these functions from their player.join event and disappears after player.quit. Between login and join they are not listed.

Servers#

Commands#

cmd(spec, handler, [options])

Registers a command that the console and players can run. handler is called as handler(source, ...). options may carry permission (a string; see Plugins). A registration that fails (bad spec, reserved or invalid name, duplicate) raises an error, which stops the plugin from loading when it happens at top level.

The spec is the command's words followed by its arguments:

cmd("coins top [limit: int 1..25]", function(src, limit)
    src:send("Top {limit}", { limit = limit or 10 })
end, { permission = "shop.top" })

The handler receives the source first and then one value per declared argument, with nil for an optional one that was not given. If the words do not fit (missing required argument, wrong type, out of range, extra words) the sender is told Usage: / followed by the spec, and the handler does not run. Several commands can share a name when their literal words differ (coins and coins top); the one with the most matching literals wins, and one that matches none is silent. Registering the same literals twice raises an error. Names of the proxy's own commands (help, servers, status, reload, send, stop, plugins) cannot be used.

Players run a command with /name ...; clients 1.13 and later complete it using the declared argument types and ranges. The console runs it without the slash.

source is a player table when a player ran the command, or the console:

A console source has no server, uuid, data, connect or kick; check is_console before using them. A command with a permission is refused for players who are not in operators; the console always passes.

Events#

on(event, [options], handler)
watch(event, [options], handler)

Registers handler for an event. on and watch register the same handler; the only difference is that watch refuses the plugin.enable and plugin.disable events, which belong to the plugin. An unknown event name raises an error listing the valid ones, and so does a handler that is not a function.

options is an optional table:

on("player.server_change", { server = "survival" }, function(e)
    log.info(e.player_name .. " arrived in survival")
end)

The events, their fields and when they fire are in Plugin events. None of them can be cancelled or changed by a handler.

Time#

Durations are in ticks of 50 ms (20 per second).

A handle has a cancel() function that stops the timer; call it as handle:cancel() or handle.cancel().

wait only works where Lua can pause: inside event and command handlers, timer callbacks and plugin.enable. At the top level of a script, while the plugin is loading, it raises an error. While one handler waits, the plugin thread serves everyone else. Timers are removed when the plugin is reloaded.

on("player.join", function(e)
    wait(40)
    e.player:send("<gray>Two seconds after joining.")
end)

Storage#

Needs storage = true for store and players_data = true for player.data, under [capabilities]. Without it, using them raises an error that names the missing capability. Values are strings, numbers or booleans; anything else raises only strings, numbers and booleans can be stored. Numbers keep their integer or float form.

player.data is a table on every player table. Read a value with player.data.visits, write with player.data.visits = 5, and delete with player.data.visits = nil. It is stored per plugin and per player (by UUID). There is no way to list the keys, and player.data is not available on the console source.

Exceeding a limit raises an error. Both are saved immediately, in the file set by database in plugins.toml.

Running commands#

run(line)

Runs a command line (without the slash) as if the console had typed it, and returns whether it named a command. It needs commands = true and the operator's grant, and it only reaches commands that plugins registered; the proxy's own commands are not reachable. Every call is logged as ran /<line>. Lines longer than 4096 bytes are cut. The command runs after the current handler finishes, so its effects are not visible to the code that follows the call.