diff options
Diffstat (limited to 'mod/README.md')
| -rw-r--r-- | mod/README.md | 403 |
1 files changed, 403 insertions, 0 deletions
diff --git a/mod/README.md b/mod/README.md new file mode 100644 index 0000000..d84a718 --- /dev/null +++ b/mod/README.md @@ -0,0 +1,403 @@ +# Acron Server-Side Mod + +## Installation and Configuration + +See [README.md](../README.md). + +## Client API + +Acron uses polymorphic JSONs when communicating with clients. Therefore, each JSON +has to contain a valid `type` parameter indicating its type: + +```json +{ + "type": "cmd", + "id": 1, + "cmd": "list" +} +``` + +### Request ordering + +To work in a full-duplex environment, each command can specify a `id` parameter. Acron will +return any results or errors with the same ID. + +Sample request: + +```json +{ + "type": "cmd", + "id": 1, + "cmd": "list" +} +``` + +The parameter `id` can be any integer, but it is the client developer's responsibility to +make it a unique value, so he or she can identify it. + +Parameter `id` defaults to -1. + +In response, any non-server-push responses (i. e. messages) will include the same `id` parameter: + +```json +{ + "type": "cmd_result", + "id": 1, + "result": 0, + "success": true +} +``` + +If the server fails to parse the request and returns an error, it will report the default ID `-2`. + +### Error Handling + +Error handling: Besides from the handshake request, which will send errors using HTTP status +codes, all faulty WebSocket requests will receive error in the following format: + +```json +{ + "type": "error", + "id": 1, + "code": 500, + "message": "Error message. Not machine-readable." +} +``` + +Parameters: + +* `.code` (int, HTTP status codes, always present): The machine-readable error code (e. g. 400 for Bad Request). +* `.message` (string, any, always present): The human-readable error message. + +Global error codes: + +* 400: The request is invalid. +* 500: The server encountered an unknown error. + +**`.type` and `.id` are included in every request / response, except for further noticed. Thus, +this document excludes them from the parameter lists.** + +### Handshaking + +Clients need to use the following connection string when connecting to the Acron server: + +``` +ws://host:port/ws?id=client_id&token=client_token&version=0 +``` + +*A better approach for specifying the authentication parameters is using HTTP headers, +but the JavaScript client does not allow so. To extend compatibility, Acron forces +all users to use HTTP query parameters to supply information.* + +Parameters: + +* `id` (required): Client ID set by the administrator. +* `token` (required): Client token set by the administrator. +* `version` (default: 0): API version. Only 0 is accepted at this time. + +Responses: + +* HTTP 400 (Bad Request): If either `id` or `token` is missing, or `version` is not 0. +* HTTP 401 (Unauthorized): If either `id` is not found or `token` does not match the record. +* HTTP 101 (Switching Protocols): The handshake is complete, and the server is upgrading to +WebSocket. + +### Setting Configuration + +This allows clients to set a per-connection default configuration to execute commands. + +Clients can override the configuration temporarily when executing commands. + +Request: +```json +{ + "type": "set_config", + "id": 1, + "world": "overworld", + "pos": { + "x": 0.0, + "y": 0.0, + "z": 0.0 + }, + "rot": { + "x": 0.0, + "y": 0.0 + }, + "name": "" +} +``` + +Parameters: + +* `.world` (enum, overworld / nether / end, overworld): The world to run commands in. +* `.pos` (vec3d, *see below*, spawn point of `.world`): The position to run commands at. + * `.x` (double, any within border limit, 0.0): X + * `.y` (double, any within border limit, 0.0): Y + * `.z` (double, any within border limit, 0.0): Z +* `.rot` (vec2f, *see below*, `0.0 0.0`): Rotation. + * `.x` (float, ?, 0.0): X + * `.z` (float, ?, 0.0): Z +* `.name` (string, any, random): Name when running commands. + +When the client connects, Acron will set the configuration to default values. + +Successful response: + +```json +{ + "type": "ok" +} +``` + +This shows that the configuration update is successful. + +### Executing Commands + +The main goal of Acron is to allow clients to run commands. A client can send +any commands, and Acron will schedule them in the background. + +Request: + +```json +{ + "type": "cmd", + "id": 1, + "cmd": "list", + "config": { + + } +} +``` + +Parameters: + +* `.cmd` (string, any valid command, required): The command to execute. It may or may not begin with `/`. +* `.config` (set_config, *see above*, current connection default configuration): Temporary configuration +when running this command. It is the same `set_config` object in the above section, but `type` and `id` +must not be supplied. + +Successful response: + +```json +{ + "type": "ok" +} +``` + +This shows that the command is scheduled. + +If the connection breaks before it is done, it is still executed without any output to the connection. + +Possible failures: + +* 403: This client is not allowed to execute this command. (Configured by rules) + +**Command output:** + +When the command prints a line, Acron will send the following response: + +```json +{ + "type": "cmd_out", + "id": 1, + "sender": "UUID", + "out": "..." +} +``` + +Parameters: + +* `.sender` (UUID, any UUID, always present): Sender UUID. +* `.out` (string, any, always present): Output. + +**Command result:** + +When the command finishes without issues (?), Acron will send the following response: + +```json +{ + "type": "cmd_result", + "id": 1, + "result": 0, + "success": true +} +``` + +All parameters always present. + +> **Note** +> +> The result completely depends on Minecraft server's response. +> It may not be reliable, and the values of `.result` and `.success` are +> undocumented. + +### Receiving Messages + +Another major part of Acron is to allow clients receive events from the server. + +Every event will have a pre-defined `type` with other custom parameters. Parameter `id` will not +present in events. + +> **Contributor Guide** +> +> Internally, all message Acron sends to clients are called events, including +> command results. + +#### Player joined + +Response: + +```json +{ + "type": "join", + "player": { + "name": "", + "uuid": "", + "pos": { + "x": 0.0, + "y": 0.0, + "z": 0.0 + }, + "world": "end" + } +} +``` + +Parameters: + +* `.player` (entity, see below, always present): The player. + * `.name` (string, any valid Minecraft username, always present): Username. + * `.uuid` (uuid, UUID, always present): UUID. + * `.pos` (vec3d, see below, always present): The position he or she joins. + * `.x` (double, any within border limit, 0.0): X + * `.y` (double, any within border limit, 0.0): Y + * `.z` (double, any within border limit, 0.0): Z + * `.world` (enum, overworld / nether / end, not present if Acron cannot determine the world): The dimension +he or she joins. + +#### Player Disconnected + +Response: + +```json +{ + "type": "disconnect", + "player": { + "name": "", + "uuid": "", + "pos": { + "x": 0.0, + "y": 0.0, + "z": 0.0 + }, + "world": "end" + }, + "reason": "" +} +``` + +Parameters: + +* `.player` (entity, see below, null only when the server cannot verify the user): The player. + * `.name` (string, any valid Minecraft username, always present): Username. + * `.uuid` (uuid, UUID, always present): UUID. + * `.pos` (vec3d, see below, always present): The position he or she leaves. + * `.x` (double, any within border limit, 0.0): X + * `.y` (double, any within border limit, 0.0): Y + * `.z` (double, any within border limit, 0.0): Z + * `.world` (enum, overworld / nether / end, not present if Acron cannot determine the world): The dimension + he or she leaves. +* `.reason` (string, any valid disconnect reason, always present): Disconnect reason. + +#### Player Message + +Response: + +```json +{ + "type": "message", + "player": { + "name": "", + "uuid": "", + "pos": { + "x": 0.0, + "y": 0.0, + "z": 0.0 + }, + "world": "end" + }, + "text": "" +} +``` + +Parameters: + +* `.player` (entity, see below, always present): The player. + * `.name` (string, any valid Minecraft username, always present): Username. + * `.uuid` (uuid, UUID, always present): UUID. + * `.pos` (vec3d, see below, always present): The position he or she sends the message. + * `.x` (double, any within border limit, 0.0): X + * `.y` (double, any within border limit, 0.0): Y + * `.z` (double, any within border limit, 0.0): Z + * `.world` (enum, overworld / nether / end, not present if Acron cannot determine the world): The dimension +he or she sends the message. +* `.text` (string, any valid Minecraft message, always present): The message. + +#### Entity Death + +Response: + +```json +{ + "type": "death", + "entity": { + "name": "", + "uuid": "", + "pos": { + "x": 0.0, + "y": 0.0, + "z": 0.0 + }, + "world": "end" + }, + "message": "" +} +``` + +Parameters: + +* `.entity` (entity, see below, always present): The entity. + * `.name` (string, any, always present): Default name or custom name of the entity. + * `.uuid` (uuid, UUID, always present): UUID. + * `.pos` (vec3d, see below, always present): The position of the entity when died. + * `.x` (double, any within border limit, 0.0): X + * `.y` (double, any within border limit, 0.0): Y + * `.z` (double, any within border limit, 0.0): Z + * `.world` (enum, overworld / nether / end, not present if Acron cannot determine the world): The dimension +of the entity when died. +* `.message` (string, any valid death message, always present): The user-readable death message. + +> **Roadmap** +> +> Parsing the death message and sending a more machine-readable message is on the roadmap. + +#### Server Lagging + +Acron will send this event when the server prints +`Can't keep up! Is the server overloaded? Running 4313ms or 86 ticks behind` to the standard output. + +Response: + +```json +{ + "type": "lagging", + "ms": 100, + "ticks": 1000 +} +``` + +Parameters: + +* `.ms` (long, >= 0, always present): Running {}ms behind. +* `.ticks` (long, >= 0, always present): Running {} ticks behind. + |