plugin documentation

README.md

@@ -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:
+See [Plugin API](docs/plugins.md)
-- 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

docs/plugins.md

@@ -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.