plugin documentation

This commit is contained in:
TriMill 2022-12-18 13:19:54 -05:00
parent 12677b2068
commit 459245bf8b
2 changed files with 50 additions and 5 deletions

View File

@ -8,9 +8,6 @@ Quectocraft is a minimal, extensible, efficient Minecraft server implementation
- Extensible: Via its Lua plugin system, Quectocraft can be configured to do a variety of things.
- Efficient: The vanilla Minecraft server, and even more efficient servers like Spigot and Paper, all use significant amounts of CPU even while idling with no players connected. Due to its low CPU and memory usage, Quectocraft is suitable for running on lower-end systems, or alongside another server without causing additional lag.
## Why?
## Plugin API
I'm mostly just writing this for fun, but here are some potential applications:
- A lobby for a server network
- A queue that players have to wait in before joining another server
- A server to send players to if they are AFK for too long
See [Plugin API](docs/plugins.md)

48
docs/plugins.md Normal file
View File

@ -0,0 +1,48 @@
# Quectocraft Plugin API
Quectocraft plugins are written in Lua. Examples can be seen in the [plugins directory](plugins). Plugins can either be a single Lua file or a directory containing a file named `main.lua`.
## Plugin table
All information about a plugin is stored in a table, which must be returned at the end of the plugin. This table contains both information about the plugin and functions that act as event handlers.
| Field | Description |
|--------------------|---------------------------------------------------------------------------------------------------------|
| `id` | The plugin's ID. This should consist of lowercase letters and underscores only. |
| `name` | The plugin's human-readable name. |
| `description` | The plugin's description. |
| `authors` | A list of the plugin's authors. |
| `version` | The plugin's version (semantic versioning encouraged). |
| `init` | Called when the plugin is initialized. The `server` table is available at this point. |
| `registerCommands` | Called to register the plugin's commands. Arguments: a `registry` table. |
| `playerJoin` | Called when a player joins. Arguments: the player's name, the player's UUID. |
| `playerLeave` | Called when a player leaves. Arguments: the player's name, the player's UUID. |
| `chatMessage` | Called when a player sends a chat message. Arguments: the message, the player's name and UUID. |
| `command` | Called when a player runs a command. Arguments: the command, the arguments, the player's name and UUID. |
## The `server` table
The `server` table is used to interact with the server. It has the following fields:
| Field | Description |
|---------------|--------------------------------------------------------------------------------------------------|
| `players` | A map from UUIDs to player names. |
| `sendMessage` | Send a player a message. Arguments: the player (name or UUID), the message. |
| `broadcast` | Broadcast a message to all online players. Arguments: the message. |
| `disconnect` | Disconnect a player from the server. Arguments: the player (name or UUID), the reason (optional) |
## The `registry` table
The `registry` table is used to register commands. It is only available from the `registerCommands` event handler.
| Field | Description |
|--------------|---------------------------------------------------|
| `addCommand` | Add a command. Arguments: the name of the command |
## The `logger` table
The `logger` table is used to log information the the console. It has the following functions for different logging levels: `trace`, `debug`, `info`, `error`, `warn`. A logger should be initialized in the `init` event handler.
## Chat components
Wherever a chat component is expected (chat messages, disconnect reasons), the plugin can either provide a string or a chat component. Lua tables are a very good approximation for JSON, and as such translating between JSON chat components and tables is not very difficult. See [the wiki.vg documentation for chat components](https://wiki.vg/Chat) for more information.