Plugin/docs/gateway.md

# Gateway

Listen to events from the server such as player movement.

Path: `ws(s)://crss.blurryface.xyz/api/v2/gateway`

## Table of Contents

* [Requesting API Endpoints](#requesting-api-endpoints)
* [Subscribing to Events](#subscribing-to-events)
* [Ping-Pong](#ping-pong)
* [Endpoints](#endpoints)
  * [`status`](#status)
  * [`players`](#players)
  * [`tile`](#tile)
* [Events](#events)
  * [`player_join`](#player_join)
  * [`player_leave`](#player_leave)
  * [`player_move`](#player_move)
  * [`player_chat`](#player_chat)
  * [`player_death`](#player_death)

## Requesting API Endpoints

Send a JSON object with the `type` field set to `api` and the `endpoints` field set to an array of endpoints you want to request.

### Possible Endpoints

* `status`
* `players`
* `tile`

### Example
```json
{
  "type": "api",
  "endpoints": [
    {
      "path": "status",
      "data": null
    },
    {
      "path": "players",
      "data": null
    }
  ]
}
```

## Subscribing to Events

Send a JSON object with the `type` field set to `subscribe` and the `events` field set to an array of events you want to subscribe to.

### Possible Events

* `player_join`
* `player_leave`
* `player_move`
* `player_chat`
* `player_death`

### Example
```json
{
  "type": "subscribe",
  "events": [
    "player_join",
    "player_leave",
    "player_move",
    "player_chat",
    "player_death"
  ]
}
```

## Ping-Pong

You need to send a "ping" message every 5 minutes to keep the connection alive:

```json
{
  "type": "ping"
}
```

The server will respond with:

```json
{
  "type": "pong"
}
```

If that doesn't happen, connect to the WebSocket again.

---

## Endpoints

### `status`

Request:
```json
{
  "type": "api",
  "endpoints": [
    {
      "path": "status",
      "data": null
    }
  ]
}
```

Response:
```json5
{
  "type": "api",
  "endpoint": "status",
  "response": "{ ... }" // see status endpoint docs
}
```

### `players`

Request:
```json
{
  "type": "api",
  "endpoints": [
    {
      "path": "players",
      "data": null
    }
  ]
}
```

Response:
```json5
{
  "type": "api",
  "endpoint": "players",
  "response": "{ ... }" // see players endpoint docs
}
```

### `tile`

Request:
```json
{
  "type": "api",
  "endpoints": [
    {
      "path": "tile",
      "data": {
        "world": "world",
        "x": 0,
        "z": 0,
        "size": 256,
        "zoom": 0
      }
    }
  ]
}
```

Response:
```json5
{
  "type": "api",
  "endpoint": "tile",
  "response": "...", // base64 encoded PNG image
  "request": { // the original request data
    "world": "world",
    "x": 0,
    "z": 0,
    "size": 256,
    "zoom": 0
  }
}
```

## Events

### `player_join`

Example:
```json
{
  "type": "player_join",
  "player": {
    "name": "TheClashFruit",
    "uuid": "942ae64d-e4e5-4dd0-a153-b6aba7817ca9"
  }
}
```

### `player_leave`

Example:
```json
{
  "type": "player_leave",
  "player": {
    "name": "TheClashFruit",
    "uuid": "942ae64d-e4e5-4dd0-a153-b6aba7817ca9"
  }
}
```

### `player_move`

Example:
```json
{
  "type": "player_move",
  "player": {
    "name": "TheClashFruit",
    "uuid": "942ae64d-e4e5-4dd0-a153-b6aba7817ca9"
  },
  "position": {
    "distance": 0.0785923757599716,
    "from": {
      "world": "world",
      "x": 98.31441469694991,
      "y": 83.0,
      "z": 254.93694099796153
    },
    "to": {
      "world": "world",
      "x": 98.38312726494456,
      "y": 83.0,
      "z": 254.8987920198995
    }
  }
}
```

### `player_chat`

Example:
```json
{
  "type": "player_chat",
  "player": {
    "name": "TheClashFruit",
    "uuid": "942ae64d-e4e5-4dd0-a153-b6aba7817ca9"
  },
  "message": "Hello, world!"
}
```

### `player_death`

Example:
```json
{
  "type": "player_death",
  "player": {
    "name": "TheClashFruit",
    "uuid": "942ae64d-e4e5-4dd0-a153-b6aba7817ca9"
  },
  "message": "TheClashFruit was slain by a zombie."
}
```