Payload

Payloads are packets that contain specific client or game information, either triggered by the client requesting a resource, e.g. The game list, or by new game data being received. Payload packets may either be unreliable, or reliable.

Reliable payloads require the client or server to acknowledge that the packet has been received. The sender will continue to send the packet until an acknowledgement has been received. Unreliable payloads, however, don't require an acknowledgement, and are typically used for common and high-rate packets such as movement packets, where individual packets are not absolutely necessary, and the client is OK with missing out on one or two.

Reliable and unreliable payloads both follow a very similar structure, except that reliable payloads also carry a nonce with them, used as an identification for the payload that the client must send back as an acknowledge packet for confirmation.

Either the client or the server can send payload packets, although the structure of the payload may depend on where the payload is bound.

Unreliable payloads are identified by a 0x00 opcode, while reliable payloads are identified by a 0x01.

Unreliable

Name	Type	Description
Length	uint16	The length of the data in this payload, except for the following payload identifier.
Payload ID	uint8	The identifier for this payload. Documentation for each payload ID is described below.
Data	...	The data for the payload.

Reliable

Name	Type	Description
Nonce	uint16	The acknowledgement identifier for the payload, the integer is in Big Endian.
Length	uint16	The length of the data in this payload, except for the following payload identifier.
Payload ID	uint8	The identifier for this payload. Documentation for each payload ID is described below.
Data	...	The data for the payload.

Example parsing code

const opcode = reader.uint8();

if (opcode === Opcode.Reliable || opcode === Opcode.Unreliable) {
    const reliable = opcode === 0x01;
    const nonce = reliable ? reader.uint16BE() : null;
    const length = reader.uint16LE();
    const payloadID = reader.uint8();
    switch (payloadID) {
    	// parse payload
    }
}

Example compose code

writer.uint8(packet.reliable);
writer.int32LE(packet.code);
const payload = new BufferWriter;
switch (packet.payloadid) {
    // compose payload
}
writer.uint32LE(payload.size);
writer.uint8(packet.payloadid);
writer.write(payload);

Payload IDs

0x00 Host Game

Client -> Server

Represents an intent to host a game. The server sends back the code of the created game if successful, or sends a Join Game Error payload if an error occurs.

Name	Type	Description
Options	Game Options	The options for hosting the game, e.g. max number of players, number of imposters, etc..

Example parsing code

case PayloadID.HostGame:
    const options = parseGameOptions(reader);
    break;

Example compose code

case PayloadID.HostGame:
    composeGameOptions(payload, packet.options);
    break;

Example packet

0000   01 00 02 2b 00 00 2a 02 0a 00 01 00 00 00 00 00   ...+..*.........
0010   30 40 00 00 80 3f 00 00 80 3f 00 00 34 42 01 01   0@...?...?..4B..
0020   02 01 00 00 00 02 01 0f 00 00 00 78 00 00 00 00   ...........x....
0030   0f

Server -> Client

Name	Type	Description
Code	Game Code	The code for the newly created game.

Example parsing code

case PayloadID.HostGame:
    const code = Int2V2Code(reader.int32LE());
    break;

Example compose code

case PayloadID.HostGame:
    payload.int32LE(V2Code2Int(packet.code));
    break;

Example packet

0000   01 00 01 04 00 00 df 41 00 80                     .......A..

0x01 Join Game

Client -> Server

Represents an intent to join a game. The server will send back a Joined Game payload if successful, or will send back the Join Game payload with an error in the format of a Disconnect packet.

Name	Type	Description
Code	Game Code	The code that the client wishes the join.
Map Ownership	byte	A bitfield of the maps that the client owns, as described in the Map bitfield. Set this to 0x07 for access to all maps.

Example parsing code

case PayloadID.JoinGame:
    const code = Int2V2Code(reader.int32LE());
    const mapOwnership = reader.byte();
    break;

Example compose code

case PayloadID.JoinGame:
    payload.int32LE(packet.code);
    payload.byte(packet.maps);
    break;

Example packet

0000   01 00 03 05 00 01 41 89 0f 80 07                  ......A....

Server -> Client

Used to indicate that a new player has joined a game, or that an error occurred while the client was attempting to join a game. I don't know how to identify the two properly, but if the packet length is 18 then it likely means someone new has joined the game.

Player joined

Name	Type	Description
Code	Game Code	The code for the game.
Client ID	uint32	The client id of the player that joined the game.
Host ID	uint32	The client id of the host that joined the game.

Example packet

Error occured

Name	Type	Description
Reason?	uint8	The reason for the error, as described in the Disconnect Reasons enum.
Message?	string	A custom message attached to the message if the error reason is Custom (0x08)

Example parsing code

case PayloadID.JoinGame:
    if (reader.size === 18) {
        const code = Int2V2Code(reader.int32LE());
        const clientid = reader.uint32LE();
        const hostid = reader.uint32LE();
    } else {
        const reason = reader.uint8();
        if (reason === DisconnectReason.Custom) {
            const message = reader.string();
        }
    }
    break;

Example compose code

case PayloadID.JoinGame:
    if (packet.error) {
        payload.uint8(error.reason);
        if (error.reason === DisconnectReason.Custom) {
            payload.string(error.message);
        }
    } else {
        payload.int32LE(V2Code2Int(code));
        payload.uint32LE(clientid);
        payload.uint32LE(hostid);
    }
    break;

Example packets

0000   01 00 17 0c 00 01 c8 55 58 8c 85 15 01 00 30 15   .......UX.....0.
0010   01 00                                             ..

0000   01 00 01 04 00 01 03 00 00 00                     ..........