diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 404 |
1 files changed, 7 insertions, 397 deletions
@@ -46,9 +46,9 @@ For each response JSON parameter, the format is: `(JSON path)` (type, limit, always present or conditions): Description. -## Installation +## Installing the mod -To build this mod, you need to run `gradle build`, and the output JAR will be at `build/libs/acron-x.x.jar`. +To build this mod, you need to run `gradle build` inside `mod/`, and the output JAR will be at `build/libs/acron-x.x.jar`. Then, copy it to the `mods/` folder in your Minecraft server working directory. @@ -164,402 +164,12 @@ Note, listen port and address cannot be changed during runtime. > it will print a warning and skip the whole new configuration file until the > error is fixed. -## Client API +## Using the client -Acron uses polymorphic JSONs when communicating with clients. Therefore, each JSON -has to contain a valid `type` parameter indicating its type: +As Acron has an open protocol, it is easy to implement the client-side service on your own. However, Acron officially +has [libacron](client/libacron), a client library written in C. -```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. +Acron also provides a cli tool: [acronc(1)](client/acronc) for administrators. ## Contributing @@ -569,4 +179,4 @@ the email subject. If you are sending a patch, please include `[PATCH]` in the s ## License -Acron is licensed under GPL-2.0-only except libac is licensed under LGPL-2.1-only. +Acron is licensed under GPL-2.0-only except [libacron](client/libacron) is licensed under LGPL-2.1-only. |