Bridge The Gap: Chat Bridge Protocol v1

[SpaceWalkerRS]

Setup

The chat bridge consists of several components.

There are several clients, which interface with users. Clients listen to chat messages, users joining/leaving, and other user-related events. The clients currently in use are the Khaos SMP and CMP Minecraft servers, and the Khaos Discord bot.

Lastly, there is the server, which connects all BTG clients together. It broadcasts messages dispatched by BTG clients to the other clients.

Terms

• BTG: abbrevition for Bridge The Gap, which is the name of the chat bridge.
• client: a BTG client.
• server: the BTG server
• send: describes a packet being sent over a specific connection, either client to server or server to client.
• broadcast: describes the server sending a packet to all connected clients.

Common Data

Platform

For a client, specifies what kind of client it is.

enum Platform {
    MINECRAFT,
    DISCORD
}

User Selection

For users request packets, specifies which group of users is requested.

enum UserSelection {
    ALL,
    ONLINE,
    ACTIVE
}

Protocol

The clients are connected to the server through a web socket connection. The handshake header must contain the protocol version that is used, as well as the auth token for the server.

protocol: <number> // the protocol version that is used
token: <string>    // the auth token for the server

Packets are sent as string-ified JSON. The structure of a packet can be seen below.

{
    packet: <number>, // packet id
    payload: {        // packet data
        ...
    }
}

The structure for each type of payload is detailed in the next sections.

Server-bound Packets

These are packets sent by clients to the server.

1. Client Connect

This packet is sent after the connection with the server has been established.

{
    platform: <string>, // name of the platform of the client
    name: <string>,     // display name of the client
    color: <number>     // display color of the client
}

2. Client Disconnect

This packet is sent before the client disconnects from the server.

{
    platform: <string>, // name of the platform of the client
    name: <string>,     // display name of the client
    color: <number>     // display color of the client
}

3. User Connect

This packet is sent when a user connects to the client.

{
    id: <string>,   // a user identifier that is unique within the client
    name: <string>, // display name of the user
    color: <number> // display color of the user
}

4. User Disconnect

This packet is sent when a user connects to the client.

{
    id: <string>,   // a user identifier that is unique within the client
    name: <string>, // display name of the user
    color: <number> // display color of the user
}

5. Client Message

This packet is sent when a client sends a message to chat.

{
    message: <string> // the message
}

6. User Message

This packet is sent when a user sends a message to chat.

{
    id: <string>,    // a user identifier that is unique within the client
    name: <string>,  // display name of the user
    color: <number>, // display color of the user
    message <string> // the message
}

7. Client Whisper

This packet is sent when a client whispers to another client or user.

{
    targetClient: <string>, // name of the target client
    targetUser: <string>,   // id of the target user, or an empty string if all users are targeted
    message <string>        // the message
}

8. User Whisper

This packet is sent when a user whispers to another client or user.

{
    userId: <string>,       // a user identifier that is unique within the client
    userName: <string>,     // display name of the user
    userColor: <number>,    // display color of the user
    targetClient: <string>, // name of the target client
    targetUser: <string>,   // id of the target user, or an empty string if all users are targeted
    message <string>        // the message
}

9. Request

The client requests some data from the target client (or all clients if none is specified).

{
    targetClient: <string>, // the name of the target client, or an empty string if all clients are targeted
    transaction: <number>,  // a unique number identifying this request-response exchange
    request: <number>,      // request id
    data: {                 // request data
        ...
    }
}

10. Response Denied

This packet is sent upon receiving a client-bound request packet, if the request is denied.

{
    targetClient: <string>, // the name of the client to which is being responded
    transaction: <number>,  // a unique number identifying this request-response exchange
    reason: <string>        // the reason the request was denied
}

11. Response Granted

This packet is sent upon receiving a client-bound request packet, if the request is granted.

{
    targetClient: <string>, // the name of the client to which is being responded
    transaction: <number>,  // a unique number identifying this request-response exchange
    response: <number>,     // response id
    data: {                 // response data
        ...
    }
}

Client-bound Packets

These are packets sent by the server to clients.

1. Client Connect

This packet is broadcast after a server-bound client connect packet has been received. It contains information about the client that has connected.

{
    platform: <string>, // name of the platform of the client
    name: <string>,     // display name of the client
    color: <number>     // display color of the client
}

2. Client Disconnect

This packet is broadcast after a server-bound client disconnect packet has been received.

{
    platform: <string>, // name of the platform of the client
    name: <string>,     // display name of the client
    color: <number>     // display color of the client
}

3. User Connect

This packet is broadcast upon receiving a server-bound user connect packet. It contains information about the user that has connected and the client it has connected to.

{
    clientName: <string>,  // name of the client
    clientColor: <number>, // display color of the client
    userId <string>,       // a user identifier that is unique within the client
    userName: <string>,    // display name of the user
    userColor: <number>    // display color of the user
}

4. User Disconnect

This packet is broadcast upon receiving a server-bound user disconnect packet.

{
    clientName: <string>,  // name of the client
    clientColor: <number>, // display color of the client
    userId <string>,       // a user identifier that is unique within the client
    userName: <string>,    // display name of the user
    userColor: <number>    // display color of the user
}

5. Client Message

This packet is sent upon receiving a server-bound client message packet.

{
    clientName: <string>,  // name of the client
    clientColor: <number>, // display color of the client
    message: <string>      // the message
}

6. User Message

This packet is sent upon receiving a server-bound user message packet.

{
    clientName: <string>,  // name of the client
    clientColor: <number>, // display color of the client
    userId <string>,       // a user identifier that is unique within the client
    userName: <string>,    // display name of the user
    userColor: <number>,   // display color of the user
    message <string>       // the message
}

7. Client Whisper

This packet is sent upon receiving a server-bound client whisper packet.

{
    clientName: <string>,  // name of the client
    clientColor: <number>, // display color of the client
    targetUser: <string>,  // id of the target user, or an empty string if all users are targeted
    message <string>       // the message
}

8. User Whisper

This packet is sent upon receiving a server-bound user whisper packet.

{
    clientName: <string>,  // name of the client
    clientColor: <number>, // display color of the client
    userId <string>,       // a user identifier that is unique within the client
    userName: <string>,    // display name of the user
    userColor: <number>,   // display color of the user
    targetUser: <string>,  // id of the target user, or an empty string if all users are targeted
    message <string>       // the message
}

9. Request

This packet is sent upon receiving a server-bound request packet.

{
    clientName: <string>   // the name of the target client, or an empty string of all clients are targeted
    transaction: <number>, // a unique number identifying this request-response exchange
    request: <number>,     // request id
    data: {                // request data
        ...
    }
}

10. Response Denied

This packet is sent upon receiving a server-bound response denied packet.

{
    clientName: <string>   // the name of the target client
    transaction: <number>, // a unique number identifying this request-response exchange
    reason: <string>       // the reason the request was denied
}

11. Response Granted

This packet is sent upon receiving a server-bound response granted packet.

{
    clientName: <string>   // the name of the target client
    transaction: <number>, // a unique number identifying this request-response exchange
    response: <number>,    // response id
    data: {                // response data
        ...
    }
}

Requests

Responses

[SpaceWalkerRS]

I'll keep updating the original post as we discuss the protocol and make changes to it.

[SpaceWalkerRS]

We should also decide on the format in which we encode chat messages. It should allow for the different text formatting features in use in Minecraft and Discord.

[SpaceWalkerRS]

Connect/Disconnect Packets

The idea behind these packets was that information about clients and users would only need to be sent once (when they connect). The benefit of this is that chat message packets can be smaller, as they don't need to contain information like display name, display color, and other decorators (e.g. bot tags).

The downside is that each client will have to keep a list of all clients connected to the server, and all users connected to each client, in memory. This is not ideal, especially with Discord servers that can have hundreds or thousands of members.

Should we stick with the connect/disconnect packets? Or is the hit on packet size small enough that client/user display information can be added to the chat message packets?

[SpaceWalkerRS]

Request/Response Packets

One of the features envisioned for this bridge was a .list command on Discord that would display all players connected to the Minecraft server. I think there's two ways to implement this.

Firstly, we could make the Discord bot parse the command, request the list of players from the Minecraft server (through request/response packets), and display that in chat. This implementation gives more freedom in how the information is displayed, each client receives the same data, but can decide to display it differently to its users. But it requires a new set of request/response packets for each command that is added.

Secondly, the Discord bot could send the command to the Minecraft server, which parses it, and send a chat message with the player list to the Discord server. This implementation requires only the command packet, and the result is sent over chat. But it gives less freedom in the kind of commands that can be issued, as the result is always in the form of a chat message.

Which approach should we take?

[goof-bug]

i think the first option is best since we have a lot more freedom to add formatting using discord native features such as embeds or maybe even custom generated emojis for minecraft player heads to show in the list (ive implemented something similar to this before).

[SpaceWalkerRS]

Hmm you might be right. It feels a little more convoluted, but that might be worth it.