Tachyon is the name of this protocol, designed to replace the old Spring Lobby Protocol, primarily intended for use in Beyond All Reason. It describes the message schema that clients should use to communicate with the master server and vice-versa. The exchange format is JSON sent over a WebSocket connection. JSONSchema is used to define the structure of commands, which can be found in the schema directory. Server and client implementations of this protocol are encouraged to use a JSONSchema validator to validate and sanitize message requests and responses.
| Term | Meaning |
|---|---|
| AI | User-owned game AI instances, e.g. ScavengersAI or BARbarianAI. Can only exist within lobbies/battles |
| Autohost | A bot which is specifically intended to host battles |
| AutohostClient | An autohost instance that is connected to the server |
| Battle | Either custom or matchmaking |
| Bot | An automated UserClient, marked as a bot |
| Client | A WebSocket client that communicates with the Tachyon server via the Tachyon protocol |
| Client Application | Top level application that connectsE.g. SpringLobby, Chobby, BAR Lobby |
| Command | The JSON data sent in a message. The shape of these objects are primarily what this Tachyon schema describes |
| Command ID | The unique string which represents the command type. E.g. system/connected/response or lobby/join/request |
| Endpoint | Represents a request->response command or a single response command E.g. register, login or join |
| Engine | A version of the engine (Recoil), e.g. 105.1.1-1544-g058c8ea BAR105 |
| Host | The host of a battle. Typically these users are bots |
| Game | A version of the core game files, e.g. Beyond All Reason test-22425-e6c0e37 |
| Lobby | A room or waiting area from which a Battle can be launched, one Lobby can have multiple Battles over the course of its lifetime |
| Message | The request/response sent over the network that contains a command |
| Message ID | A unique identifier for a pair of request/response commands which links them together |
| Server | The provider of the protocol and what clients connect to. i.e. the master/middleware server |
| Service | A collection of endpoints that are categorically related, E.g. user or lobby |
| User | Syonymous with an account, and strictly represents the data which is stored in the server database |
| UserClient | A registered user that is connected to the server |
Tachyon uses OAuth 2 for authenticating and authorizing clients. The OAuth token should then be sent in the WebSocket connection request which the Tachyon server should validate and permit the connection if valid, or close the connection if not.
The full auth process is detailed here.
See connection for details on how to establish the WebSocket connection to the server.
JSON messages in this protocol are referred to as "commands".
Every command shares the following properties:
| Property | Type | Description |
|---|---|---|
| commandId | string | The identifier of this command's type, e.g. lobby/create/request |
| messsageId | string | A unique identifier for a pair of request/response commands which links them together |
Request commands can be sent from either side, and expect the other side to send a correlating response command. They are typically used when asking the other side to perform an action or fetch some data which they require, or simply to acknowledge their request has been fulfilled.
Every request command contains these additional properties:
| Property | type | Description |
|---|---|---|
| data (optional) | object | A object containing data specific to the command |
Sent in response to a request.
Every response command contains these additional properties:
| Property | type | Description |
|---|---|---|
| status | "success" | "failed" | A object containing data specific to the command. This may be omitted if the command does not require it |
| data (optional) | object | Command-specific data object. Only present for "success" responses |
| reason (if status is "failed") | string | An error code only present for "failed" responses |
All failed responses that are initiated by a request can return one of the following reasons, even though not explicitly defined in each command's definition file:
| Reason | Description |
|---|---|
| unauthorized | When a client sends a request command of which they do not have the role required to use |
| internal_error | When the server fails to handle the request in some way |
| invalid_request | When the request command doesn't match the schema |
| command_unimplemented | When the server hasn't implemented a response handler for the command |
Events are commands which require no response. They are typically sent when the sending party does not care if the message has been acted upon, such as the server sending periodic update data.
Every event command contains these additional properties:
| Property | type | Description |
|---|---|---|
| data (optional) | object | A object containing data specific to the command |
The dist and docs/schema directories are automatically generated based on the files in src/schema. The source files are written in TypeScript for Node.js, using the TypeBox library for JSONSchema generation.