98 lines
6.4 KiB
Markdown
98 lines
6.4 KiB
Markdown
# quectocraft plugins
|
|
|
|
## File structure
|
|
|
|
Plugins are located in the `plugins` directory. Plugins may either be stored as a single file in the `plugins` directory or in a subdirectory, in which case the plugin will be loaded from a file named `main.lua`.
|
|
|
|
## Versioning
|
|
|
|
Server and plugin versions use [Semantic Versioning](https://semver.org/) to specify versions, specifically the variety used by Cargo, rust's package manager. Refer to [the Cargo docs](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html) for information on specifying versions and version requirements
|
|
|
|
## Plugin table
|
|
|
|
The plugin's main file returns a table representing the plugin. The `id` property is required or the plugin will fail to load. The `server_version` property is recommended to ensure that the plugin is running under a compatible server version. The `priority` field, which defaults to 50 and must be between 1 and 100 inclusive, controls the order that events are sent to plugins; plugins with higher priority will be initialized and recieve events before those with lower priority.
|
|
|
|
All other fields listed are optional and are currently unused by the server, although they may be used by the server in the future or by other plugins.
|
|
|
|
| Key | Type | Required? | Description |
|
|
|------------------|---------|-------------|-------------------------------------------------------------------|
|
|
| `id` | string | required | The plugin's id, which should be a unique `snake_case` identifier |
|
|
| `server_version` | string | recommended | The version requirement for the server |
|
|
| `priority` | integer | optional | Determines the order in which plugins recieve events |
|
|
| `name` | string | optional | The plugin's name |
|
|
| `version` | string | optional | The plugin's version |
|
|
| `description` | string | optional | The plugin's description |
|
|
| `authors` | table | optional | A list of plugin authors |
|
|
| `license` | string | optional | The plugin's license |
|
|
|
|
The table may also contain the following functions that serve as event handlers. All functions take an initial `self` argument holding the plugin's own table.
|
|
|
|
- `init(self)` - run for each plugin after all have been loaded
|
|
- `on_join(self, uuid, name)` - a player joined the server
|
|
- `on_leave(self, uuid, name)` - a player left the server
|
|
- `on_message(self, message, uuid, name)` - a player sent a message
|
|
- `on_command(self, command, args, full_command, uuid, name)` - a player ran a command
|
|
- `command`: the command that was run (with the plugin namespace removed if present)
|
|
- `args`: a table of the arguments to the command created by naïvely splitting the command string on whitespace
|
|
- `full_command`: the full command message containing the (possibly namespaced) name and arguments but not including the initial slash
|
|
|
|
Returning `true` from any of these methods besides `init` will cancel the event: it will not be sent to any other plugins. This does not prevent the action that caused the event.
|
|
|
|
Plugins may use their tables to store arbitrary extra data.
|
|
|
|
## Data types
|
|
|
|
- `uuid`: A UUID, probably of a player. Supports testing for equality via `==` and conversion to a string via `tostring()`.
|
|
- `srv`: The interface to the server, as described below.
|
|
- `msg`: A Minecraft JSON chat component represented as a table. A string may also be used if no formatting is needed, or `nil` may be passed to use an empty or default message.
|
|
|
|
## `srv`
|
|
|
|
Plugins can use the global `srv` object to perform logging and communicate to and query the server.
|
|
|
|
### Logging
|
|
|
|
The methods `trace`, `debug`, `info`, `warn`, and `error` can be used for logging. Each takes a single string argument and logs it to the terminal using the same logging interface as used by the server.
|
|
|
|
### Players
|
|
|
|
The method `players` retrieves a table listing the users connected to the server where the keys are UUIDs and the values are player names.
|
|
|
|
The method `get_name(uuid)` will get a player's name given a UUID, and the method `get_uuid(name)` will get a player's UUID given their name.
|
|
|
|
The method `get_info(uuid)` returns a table containing the following:
|
|
- `addr` - the address the player connected to the server with
|
|
- `port` - the port the player connected with
|
|
- `proto_name` - the name of the protocol the player is using (ex. `1.20.1`)
|
|
- `proto_version` - the numerical version of the protocol (ex. `763`)
|
|
|
|
`kick(uuid, msg)` can be used to disconnect a player from the server. If `msg` is `nil`, the default, localized kick message will be used.
|
|
|
|
### Chat
|
|
|
|
- `send_msg(msg, target)` sends a system message to the player specified by the `target` UUID, or to all players if no UUID is specified
|
|
- `send_chat(msg, target)` does the same but as a chat message
|
|
|
|
Chat messages should be used for messages with content originating from players, system messages should be used for information from the server or in response to commands.
|
|
|
|
### Commands
|
|
|
|
Plugins will only recieve `on_command` events for commands they have registered.
|
|
|
|
- `register_command(name)` will register the commands `id:name`, where `id` is the plugin's id, and `name`, provided that another plugin has not already registered a command named `name`.
|
|
- `add_command(name)` is a convenience method for registering a command and creating basic Brigadier nodes to indicate to clients that the command exists. (note: full Brigadier API is WIP)
|
|
- `update_commands()` will resend the command data to connected clients. This is only necessary if adding new commands after the `init` phase completes, which should be avoided if possible.
|
|
|
|
### Utility
|
|
|
|
NOTE: these are functions, not methods.
|
|
|
|
- `parse_uuid(str)` will attempt to parse a UUID from a string, returning `nil` if the argument is not a valid string representation of a UUID.
|
|
- `check_semver(ver, req)` checks if the semantic version `ver` matches the version requirement `req`. It will error if either the version or version requirement fails to parse.
|
|
|
|
## Fields
|
|
|
|
- `version` is the quectocraft server version (this is not a Minecraft protocol version)
|
|
- `plugins` is a table containing all loaded plugins, where the keys are plugin IDs.
|
|
|