quectocraft2/PLUGINS.md

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 to specify versions, specifically the variety used by Cargo, rust's package manager. Refer to the Cargo docs 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.