Bus Doc

All messages on the bus are encoded using JSON. All messages should contain a bare minimum of the fields shown below. A message without these fields would be considered invalid.

• type (string): An event identifier. The headlines below are the identifiers for their respective events.
• source (string): The source of the event. Whereas a custom server field may be used to specify where a event happened/should happen, the source field should always be used to show the origin of an event. If the event originates from a minecraft server, it should contain server:<server_id>

---

Standardized fields

UUID

This field is a string. It should contain a 32 byte hex string (without dashes, mojang format).

Server

This field is a string. It should contain a server id in the format of server:revision. It must be registered in the database of the website.

Location

This field is a dictionary. It contains all the information you would need to represent the position of something in the entire server network. It should contain the following keys:

• server (server)
• world (string): The name of the world on the server.
• x (double)
• y (double)
• z (double)
• pitch (float) (optional)
• yaw (float) (optional)

Player

This field is a dictionary. It contains all the information you would normally need to know about a player. It should contain the following keys:

• name (string)
• uuid (uuid)
• location (location)

PlayerDescriptor

This field is a dictionary. It contains all the information you would need to uniquely identify a minecraft player. It should contain the following fields:

• uuid (uuid)
• name (string)

WebUser

This field is a string. It represents the name of a website user. For this field to be valid, there must be a user with this name registered on the website.

DateTime

This field is a string. It contains all information needed to identify a single point of time to the precision of 1 second. TODO: Add format, should be the same as the REST api uses. (yay consistency)

---

Events

server_start (S>C)

This event should be sent out by every Minecraft server on the bus on server startup. This should always be the first event emitted from a server when starting.

It should contain the following fields:

• server (string): The server identifier (server-revision-id in the config, in the format of server:revision, registered in the www database)
• nanotime (long): The current System.nanotime() of the sending server.

server_stop (S>C)

Same as server_start, except sent on server shutdown. Should always be the last event emitted.

It should contain the same fields as server_start.

server_heartbeat (S>C)

This event should be sent out by every Minecraft server on the bus with an interval of 100 (20 * 5, 5 seconds at 20tps) ticks.

It should contain the same fields as server_start.

player_join (S>C)

Emitted by a Minecraft server when a player joins.

It should contain the following fields:

• server (server)
• player (player)

player_quit (S>C)

Emitted by a Minecraft server when a player leaves.

It should contain the same fields as player_join

player_chat (S>C)

Emitted by a Minecraft server when a player chats. Everything that could be relevant to a conversation (directly user generated content) should be emitted under this event. (TODO: How do we deal with console chat?)

It should contain the following fields:

• server (server)
• player (player)
• message (string)

player_banned (W>C)

Emitted by the REST api on the website when a player is banned. This could for example be used to kick players from servers automatically when they are banned, regardless of which one of our servers they are on.

It should contain the following fields:

• server (server): The server the ban occurred on. (Make this optional in the future, enable banning from irc?)
• target (player)
• issuer (webuser)
• time (datetime): The time when the ban occurred. This might be of importance if we are processing old, queued messages.