|
| 1 | +# CloudLink 5 ("Omega") Protocol |
| 2 | +CL5 was the first version of CloudLink to switch away from a solely server-client to a hybrid server-client/peer-to-peer architecture. |
| 3 | + |
| 4 | +## In-band (peer-to-peer) schema |
| 5 | +```js |
| 6 | +{ |
| 7 | + "opcode": "...", |
| 8 | + "payload": { ... }, |
| 9 | + "id": "...", |
| 10 | + "method": "..." |
| 11 | +} |
| 12 | +``` |
| 13 | + |
| 14 | +`opcode` is a string that defines what the packet is used for. |
| 15 | +`payload` can be any arbitrary data type that can be serialized using JSON. |
| 16 | +`id` and `method` are optional properties that only apply when using the variable/list data synchronization feature. |
| 17 | + |
| 18 | +| `opcode` | Description | |
| 19 | +| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 20 | +| G_MSG | A Global Message intended to be broadcast. | |
| 21 | +| P_MSG | A Private Message intended only for the recipient. | |
| 22 | +| G_VAR/P_VAR | A Variable Sync message. The payload contains the new value, and an id key specifies which networked variable to update. | |
| 23 | +| G_LIST/P_LIST | List Sync message. The payload contains the new data, an id key specifies the networked list, and a method key (`set`, `replace`, `length`, etc.) specifies how the list should be modified. | |
| 24 | +| NEW_CHAN | A control message sent on the `default` channel to negotiate and open a new, named data channel between the two peers. | |
| 25 | +| HANGUP/DECLINE | Voice call control signals sent between peers to manage the state of a call. | |
| 26 | + |
| 27 | +## Out-of-band (server-to-client) schema |
| 28 | +```js |
| 29 | +{ |
| 30 | + "opcode": "...", |
| 31 | + "payload": { ... }, |
| 32 | +} |
| 33 | +``` |
| 34 | + |
| 35 | +Akin to the in-band schema, both `opcode` and `payload` are retained and have the same functionality. `id` and `method` are not included. |
| 36 | + |
| 37 | +| `opcode` | Description | |
| 38 | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 39 | +| INIT | Initializes a session with the server. A valid username, token, or credential must be supplied. An optional public key can be passed through for E2EE. | |
| 40 | +| CREATE_LOBBY | Requests the server to create a new lobby. The payload includes the lobby name, max players, password, and other settings. | |
| 41 | +| JOIN_LOBBY | Requests to join an existing lobby. The payload includes the lobby name and a password if required. | |
| 42 | +| LIST_LOBBIES | Requests an updated list of all public lobbies from the server. | |
| 43 | +| FIND_LOBBY | Requests detailed information about a single public lobby. | |
| 44 | +| MANAGE_LOBBY | Sent by the lobby host to manage the lobby (e.g., kick players, change password, transfer ownership). The payload contains a method and args. | |
| 45 | +| KEEPALIVE | Sent periodically to prevent the WebSocket connection from timing out, if enabled. | |
| 46 | +| INIT_OK | The server's successful response to an `INIT` request. The payload contains the client's newly assigned `instance_id`, `user_id`, and confirmed `username.` | |
| 47 | +| NEW_PEER/PEER_JOIN | Informs clients in a lobby that a new peer has joined. The payload is a user object containing the new peer's ID, username, and public key. | |
| 48 | +| PEER_LEFT | Informs clients that a peer has left the lobby. The payload contains the ID of the disconnected peer. | |
| 49 | +| LIST_ACK/FIND_ACK | The server's response to `LIST_LOBBIES` or `FIND_LOBBY`, with the requested lobby data in the payload. | |
| 50 | +| CREATE_ACK/JOIN_ACK | Confirms that a lobby was successfully created or joined. | |
| 51 | +| LOBBY_CLOSED | An alert that is sent to all clients when the host closes the lobby. | |
| 52 | +| TRANSITION | Informs a client that its role or "mode" has changed (e.g., from "peer" to "host"). | |
| 53 | +| RELAY | Instructs a client to connect to a specific peer that will act as a TURN-like relay for the lobby. | |
0 commit comments