# Events
Every event in this document has two forms, a request and a response, the event
type can be differentiated by the event prefix, `req` is an event going to the
server, and `res` is a response coming from the server to the client. Some events
may only have one of these types, if this is the case, it will be denoted in the
relevant section.

**Important**: Events with the `Broadcasted` event type, must be listened to
even if you don't send any `Request` events of that type. This is because other
clients connected to the server may trigger the server in such a way that the
event response gets sent to multiple clients. **Broadcasted events will use the**
`res` **event type prefix.**

Most request payload types inherit from `ServerRequest`, and all response
payloads inherit from the `ServerResponse` type.

---

## `error`
The event that is sent to clients when they cause a significant error to happen
in the server. When this is sent, the status property will never be set to a
value in the success range.

### Supported Event Types
| Request | Response | Broadcasted
| ------- | -------- | -----------
| No      | Yes      | No

### Payloads
Request Payload: N/A

Response Payload: `ServerResponse`
---

## `server.info`
Retrieves information about the server that the client is currently connected
to.

### Supported Event Types
| Request | Response | Broadcasted
| ------- | -------- | -----------
| Yes     | Yes      | No

### Payloads
Request Payload: N/A

Response Payload: `IServerInfo`

---

## `lobby.info`
Retrieves information about the lobby. In order for this event to return without
error, the client requesting the information **must** be in the lobby already.
This event is broadcasted to clients who are already in the lobby when the
player list or a player's design gets updated.

### Supported Event Types
| Request | Response | Broadcasted
| ------- | -------- | -----------
| Yes     | Yes      | Yes

### Payloads
Request Payload: `IGetLobbyInfo`

Response Payload: `ILobbyInfo`

---

## `lobby.create`
Creates a game lobby that allows for online play.

### Supported Event Types
| Request | Response | Broadcasted
| ------- | -------- | -----------
| Yes     | Yes      | No

### Payloads
Request Payload: `ICreateLobby`

Response Payload: `ILobbyInfo`

---

## `lobby.delete`
Deletes the game lobby, clearing all players from the lobby and preventing
others from joining the lobby. This endpoint errors whenever a client that isn't
the host tries to call the endpoint.

### Supported Event Types
| Request | Response | Broadcasted
| ------- | -------- | -----------
| Yes     | Yes      | Yes

### Payloads
Request Payload: `IDeleteLobby`

Response Payload: `ServerResponse`

---

## `lobby.players.join`
Allows a player to join a lobby based on the lobby identifier.

### Supported Event Types
| Request | Response | Broadcasted
| ------- | -------- | -----------
| Yes     | Yes      | No, causes `lobby.info` broadcast

### Payloads
Request Payload: `IJoinLobby`

Response Payload: `ILobbyInfo` (or `IGameState` if the game is in progress)

---

## `lobby.players.leave`
This allows non-host players to leave the lobby without destroying it entirely.
This endpoint errors when the client that created the lobby attempts to use the
endpoint.

### Supported Event Types
| Request | Response | Broadcasted
| ------- | -------- | -----------
| Yes     | Yes      | No, causes `lobby.info` broadcast

### Payloads
Request Payload: `ILeaveLobby`

Response Payload: `ServerResponse`

---

## `lobby.players.update`
Allows the player to update their own information, this is primarily used for
updating the ship design.

### Supported Event Types
| Request | Response | Broadcasted
| ------- | -------- | -----------
| Yes     | Yes      | No, causes `lobby.info` broadcast

### Payloads
Request Payload: `IUpdatePlayer`

Response Payload: `ServerResponse`

---

## `game.state`
Provides information about the current game state, used to help keep clients in
the correct state.

### Supported Event Types
| Request | Response | Broadcasted
| ------- | -------- | -----------
| No      | Yes      | Yes

### Payloads
Request Payload: N/A

Response Payload: `IGameState`