path: root/mod/README.md

# 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, Acron will send the following response:

```json
{
  "type": "cmd_result",
  "id": 1,
  "result": 0,
  "success": true
}
```

All parameters always present.

> **Important:**
> 
> For `cmd` requests, the response will be either a single `error`, or a series of:
> single `ok` (Successfully scheduled) -> zero or more `cmd_out` (Output) -> single `cmd_result` (Final result)
> The response will always end with either error or cmd_result.
> After that, the server should not return anything with the same ID.

### 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": "",
    "type": "",
    "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.
  * `.type` (string, namespace:path, always present): Entity type.
  * `.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": "",
    "type": "",
    "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.
  * `.type` (string, namespace:path, always present): Entity type.
  * `.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": "",
    "type": "",
    "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.
  * `.type` (string, namespace:path, always present): Entity type.
  * `.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": "",
    "type": "",
    "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.
  * `.type` (string, namespace:path, always present): Entity type.
  * `.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.