Firebase Protocol

Protocol Version: 1.8

Firebase Version: 1.8

Firebase Protocol 1.8

Copyright © 2009, 2010, 2011, 2012 Cubeia Ltd

This work is licensed under the Creative Commons Attribution-Share Alike 2.5 Sweden License.

To view a copy of this licence, visit http://creativecommons.org/licenses/by-sa/2.5/se/ or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California 94105, USA.

Table of Contents

General

Binary Packaging

JSON Packaging

Identifiers

Communication

Request / Response

Notifications

Type List

General Packets

Version

Game Version

Good

Bad:

System Message:

Parameter

Parameter Filter

Ping

Attribute

Player / Client Information Packets

Login Request

Login Response

Logout

Player Info

Forced Logout

Seat Info

Player Query Request

Player Query Response

System Info Request

System Info Response

Table Requests and Responses

Join Request

Join Response

Watch Request

Watch Response

Unwatch Request

Unwatch Response

Leave Request

Leave Response

Table Query Request

Table Query Response

Create Table Request

Create Table Response

Invite Players Request

Notify Invited

Server To Client Notifications

Notify Join

Notify Leave

Notify Joined

Notify Watching

Kick Player

Dual Way Packets (Server <--> Client)

Table Chat

Game / 3rd Party Specific Packets

Game Transport

Service Transport

Local Service Transport

MTT Transport

Encrypted Transport

Channel Chat Packets

Join Chat Channel Request

Join Chat Channel Response

Leave Chat Channel Request

Notify Channel Chat

Channel Chat

Lobby Handling Packets

Lobby Query

Table Snapshot

Table Update

Lobby Subscribe

Lobby Unsubscribe

Table Removed

Tournament Snapshot

Tournament Update

Tournament Removed

Lobby Object Subscribe

Lobby Unsubscribe

Table Snapshot Packet List

Table Update Packet List

Tournament Snapshot Packet List

Tournament Update Packet List

Filtered Join Table Request

Filtered Join Table Response

Filtered Join Cancel Response

Filtered Join Cancel Response

Filtered Join Table Available

Probe Stamp

Probe

MTT Register Request

MTT Register Response

MTT Unregister Request

MTT Unregister Response

MTT Seated

MTT Picked Up

Enumerations

Definitions

Parameter Type

Parameter Filter

Lobby Type

Service Identifier

Player Status

Response Statuses

Response Status

Join Response Status

Watch Response Status

Filtered Join Response Status

Tournament Register Response Status

General

The Firebase protocol is either encoded in a binary version for ordinary socket communications, or in JSON when communicating over HTTP, ie. Web Sockets or Comet. In other words, the packaging is determined by the transport:

Binary Packaging

Packet format

The packets first four bytes will contain the total size of the entire packet (32 bit signed integer).

0      4        N

+------+--- ... +

| Size | Body   |

+------+--- ... +

Body

The body of the packet will firstly contain a byte that specifies the type of the packet.

0      1           N

+------+--- ... ---+

| Type | Arguments |

+------+--- ... ---+

Strings

Maximum length is 215 characters.

0        2              N

+--------+--- ... ----- +

| Length | Characters   |

+--------+--- ... ------+

Arrays

All arrays are prefixed by the length as an integer

0        4              N

+--------+--- ... ----- +

| Length | Elements     |

+--------+--- ... ------+

Integers

Unsigned or Signed, big-endian, 32 bit unless specified otherwise.

Signed or Unsigned is specified in the protocol xml-definition.

Structs

Structs that are contained within a struct does not include the header, i.e. size and type.

JSON Packaging

The packet format follows the JSON specification. All integers, strings and structs are trivially converted between the protocol format and its JSON equivalense, except for those noted below.

Packet Type

Each packet will have a “classId” field with an integer value which correspond to the packet ID specified in the protocol XML definition. This can be used for polymorphic parsing of the packets.

Binary Data

All byte array fields will be Base64 encoded and packaged as a JSON string.

Enums

Enumerations are encoded as JSON strings.

Identifiers

All identifiers below are integers, and will be abbreviated as follows in this document:

PID 0 belongs to the server.

Communication

Request / Response

Packets that have the name xxxRequestPacket are all client --> server and is for a single player only. Packets that matches xxxResponsePacket are all single responses for a request done by the receiving client.

A Response packet for a client  will never be sent to another client.

Notifications

All packets that starts with Notify are notifications from the server. Notifications are related to actions performed by other players.  Information regarding a request made by client A can thus be propagated to many players in the form of a Notify packet.

Type List

Below is the mapping of type identifiers to packet definition.

General Packets

Version

Used by client to verify Firebase protocol version.

Type id: 0

Game Version

Used by client to verify a Game version. The game must implement the version handling and since we do not know of the preferred format, we send the game version as String.

Type id: 1

Good

A command / request was accepted.

Type id: 2

Bad:

Command was not accepted, error code describes the problem.

CMD: Command code such as LOGIN, etc.

ERROR: See bottom of this document for the list of error codes.

Type id: 3

System Message:

Global system message. Can be sent by Admin or by implementing game. Type and Level are not defined within Firebase, i.e. They are free to use as suited.

Type id: 4

Parameter

A data structure which is contained within other packets. The Parameter models a key-value parameter of the specified type. Type is defined in the Parameter enumeration.

Type id: 5

Parameter Filter

A data structure which is contained within other packets. The Parameter Filter applies a constraint on top of a Parameter. This is typically used for creating lobby filters (e.g. Filtered Join).

Operator is defined in the Parameter Filter enumeration.

Type id: 6

Example:

• Key:         '_SEATED'
• Type:         INT
• Value:         0
• Op:         GREATER THAN

The Parameter Filter above will match every entity that has an attribute (key) called SEATED with a number greater then 0.

Ping

A simple packet sent by the server to detect client failures.

Type id: 7

Attribute

A simple name-value packet.

Type id: 8

Player / Client Information Packets

Login Request

Request to login. Will receive a Login Response as response from the server.

Type id: 10

Login Response

Response to a login request.

Status is defined in the Response Status enumeration.

Type id: 11

Logout

Logout from the server. No response will be sent since we will never deny a logout.

If the leave tables flag is set then Firebase will send a leave request to all tables the player is currently seated at. If the flag is false then players at table will be handled similar to a client disconnect, i.e. they will be flagged WAIT_REJOIN and finally DISCONNECTED.

If you want to be able to logout the client and then get 'notify seated at' messages when login in again (if before reaper timeout), then you should set the flag to 'false'.

Type id: 12

Player Info

A minimal information struct regarding a player.

Type id: 13

Forced Logout

The client was forcibly logged out by the server. The use of a code-response is strongly suggested. Using string-format messages uses high bandwidth and does not allow for different client side locales.

The client will be removed from all tables he is seated at the same way a regular logout would.

Code:

1 = Client logged in remotely

2 = Kicked by server

Type id: 14

Seat Info

Information regarding a seat at a table. This will be part of a table info response.

Status is defined in the Player Status enumeration and is the status of the player.

Type id: 15

Player Query Request

Request extended information about a player. This request will be routed to an implementation specific handler.

Type id: 16

Player Query Response

Extended information about a player. If you provide your own player lookup implementation then use the Status flag to mark invalid entities.

Type id: 17

System Info Request

Request system information from the game server. The packet contains no contextual fields.

Type id: 18

System Info Response

Contains current number of logged in players together with customizable parameters. The parameters are defined and inserted by 3rd party service implementation (if present).

Type id: 19

Table Requests and Responses

Join Request

Join a table. A Join Response will be sent back. If you are seated at the table and you have not watching the table then you will also get a SeatInfoPacket for every player seated at the table including yourself.

You can include any game specific needed attributes in the params field.

If you set seat id = -1 then the server will place at any free seat if available.

Type id: 30

Join Response

Response to a join request.

Status is defined in the Join Response Status enumeration.

Type id: 31

Watch Request

Watch a table. A Watch Response will be sent back. If successful, a set of SeatInfoPacket will be sent, one for each seated player at the table. After that you will receive GameTransportPackets as defined by the implementing game.

Type id: 32

Watch Response

Response to a watch request.

Status is defined by the Watch Response Status enumeration.

Type id: 33

Unwatch Request

Stop watching a table. You will stop receiving updates from the game when the request has been handled.

Type id: 34

Unwatch Response

Response to unwatch request.

Status is defined in the Response Status enumeration.

Type id: 35

Leave Request

Request to Leave Table. If you send this to a table where you are not seated then you will get a Leave Response with status = FAILED.

Type id: 36

Leave Response

Response to Leave Table request.

Status is defined in the Response Status enumeration.

Type id: 37

Table Query Request

Request extended table information.

Type id: 38

Table Query Response

Extended information about a table. The Status flag is used to mark invalid entities.

Type id: 39

Create Table Request

Send this to request a table to be created. You will receive a Create Table Response with a response status and response code set by the game implementation (if applicable). The response will contain the sequence id as matched by the request.

The request can contain a list of player ids that will be invited to the table upon creation. All invited players will receive a Notify Invitation packet for the table. The activator can flag if the seats should be reserved as well, if so then the invitation notification will contain a seat value > -1 as well.

The game activator contains a possibility to alter the invitation player ids. This makes it possible to send in an internal group id instead, but then you need to match this behavior with the game implementation.

Type id: 40

Create Table Response

Response for Create Table Request. If status is OK, then you would normally respond with a Join Table Request for the given table and seat. The “code” of the response is only used if the creation request was denied.

Status is defined in the Response Status enumeration.

Type id: 41

Invite Players Request

Sent by client to invite other players to a specific table. This request will generate a Notify Invited Packet to all logged in recipients. There is no response packet for this request.

There is also no check for table or player ids, i.e. we do not check if the supplied table id does exist in the game space. All invitations are routed as-is.

Type id: 42

Notify Invited

You were invited to a table by another table. If the seat is > -1, then the given seat has been reserved for you. If you do not claim the seat it will be cleaned up after a while and you are no longer guaranteed the spot.

Type id: 43

Server To Client Notifications

Notify Join

A player has join a table you are registered to as a watcher (or seated player).

Type id: 60

Notify Leave

A player has left a table you are registered to as a watcher (or seated player).

Type id: 61

Notify Joined

If you have been disconnected (without a proper logout) and reconnect within the reconnect grace period (configurable, but default is 60 seconds), then you will receive one notify joined for each table you were seated at. To rejoin that table you should send a regular join request for the given table and seat.

Type id: 62

Notify Watching

If you have been disconnected (without a proper logout) and reconnect within the reconnect grace period (configurable, but default is 60 seconds), then you will receive one notify watching for each table you were watching. To watch that table again you should send a regular watch request for the given table.

Type id: 63

Kick Player

Sent when a player is kicked from a table. The reason codes are game specific and should be defined by the game. This packet will only be sent to the player that was kicked, the other players at the table will receive a leave notification as normal.

NB: Currently not used, only forced logout is available

Type id: 64

Dual Way Packets (Server <--> Client)

Table Chat

A player is chatting at the table. The information contained is the same regardless of direction.

Type id: 80

Game / 3rd Party Specific Packets

Game Transport

This packet wraps the game specific protocol data.

Player id can be omitted on incoming packets (i.e. sent from client to server) since it will be overridden in the client session.

Type id: 100

Service Transport

This packet wraps the service specific protocol data. A service can be identified in two ways, by namespace or by contract. Both identifiers are specified in the service’s deployment descriptor (service.xml).

Player id can be omitted on incoming packets since it will be overridden in the client session.

Id Types are defined in the Service Identifier enumeration.

Type id: 101

Local Service Transport

This packet wraps service specific data that will be directed to the deployed local service (if any). This service can be addressed before a client has login (as opposed to Service Transport which requires a logged in client).

Type id: 103

MTT Transport

This packet wraps the tournament specific protocol data.

Type id: 104

Encrypted Transport

This packet wraps encrypted protocol data. The funtion byte can be one of the following (as defined in CryptoConstants):

• -1 : ILLEGAL_PACKET : Sent by the server if it does not support encryption
• 0 : ENCRYPTED_DATA : Actual transport payload
• 1 : SESSION_KEY_REQUEST : Sent by client to request key
• 2 : SESSION_KEY_RESPONSE : Send by server after key request

Type id: 105

Channel Chat Packets

Join Chat Channel Request

Request to join a chat channel. A Join Chat Channel Response will be sent back. If successful you will start to receive Chat Notifications and can send Channel Chat packets.

Type id: 120

Join Chat Channel Response

Response to join chat channel.

Status is defined in the Response Status enumeration.

Type id: 121

Leave Chat Channel Request

Request to join a chat channel. No response is sent back since we will never deny a leave chat channel request.

Type id: 122

Notify Channel Chat

Someone has said something in the chat.

Type id: 123

Channel Chat

Chat in a Chat Channel.

Type id: 124

Lobby Handling Packets

Lobby Query

Query the lobby for table information. This is very resource demanding so if you are planning on successive updates, please use the subscription model instead.

You must specify which lobby by setting the type accordingly. The possible lobby types are defined in the LobbyType enum. The value used should be the ordinal of the enum.

The query uses a relative path based on the lobby tree.

Gameid is used as a universal id for the deployment identifier, e.g. For games it is the id in the game.xml, for tournaments it is the id in the tournament.xml.

Type id: 142

Example:

Given a  lobby tree like (top level node is always game id):

/99/a/b/c

/99 /a/b/d

You can use address like this:

• /99/a/b/c – Gives all tables under the end node of /99/a/b/c
• /99/a/b – Gives all tables under the end nodes /99/a/b/c and /99/a/b/d
• /99 – Gives all tables for game with id = 99

Table Snapshot

Full information regarding a Table. If you are subscribing to a lobby path, then all successive packets for this table will be Table Update Packets.

A table snapshot will contain all default attributes, but since the parameters are set runtime Firebase cannot guarantee that all game-specific attributes are set before a table snapshot is sent out. If your lobby specifies a specific parameter, then the client needs to handle the case of a missing parameter.

Type id: 143

Table Update

Delta changes for the given table. This packet assumes that you hold a reference for the table id which contains the non-changed attributes. The Parameter map contains all attributes that are changed.

Type id: 144

Lobby Subscribe

Start a subscription to the lobby. The subscription will be active on the given lobby path as well as all sub-nodes.

E.g.

If the lobby tree is:

a/b/c

a/b/d

a/e/f

And you send in a subscription request for: a/b/, then you will receive updates for nodes:

a/b

a/b/c

a/b/d

You must specify which lobby by setting the type accordingly. The possible lobby types are defined in the LobbyType enum. The value used should be the ordinal of the enum.

Gameid is used as a universal id for the deployment identifier, e.g. For games it is the id in the game.xml, for tournaments it is the id in the tournament.xml.

When subscribing you will first receive a full snapshot for all tables contained in all nodes affected (i.e. the sub nodes). After the full snapshot you will start to receive delta updates. Delta updates can (and will) include full snapshots, delta snapshots and table removed packets. All according to changes in the lobby.

It is possible to subscribe to lobby before logging in.

Type id: 145

Lobby Unsubscribe

Stop your subscription. This will unsubscribe you to the given address and all sub nodes. This means that if you can unsubscribe to a sub set of your total subscriptions.

You must specify which lobby by setting the type accordingly. The possible lobby types are defined in the LobbyType enum. The value used should be the ordinal of the enum.

Gameid is used as a universal id for the deployment identifier, e.g. For games it is the id in the game.xml, for tournaments it is the id in the tournament.xml.

E.g.

If the lobby tree is:

a/b/c

a/b/d

a/e/f

And you have subscribed to: 'a' (which means you will receive updates for the whole tree in this example).

If you now unsubscribe to 'a/b' you will continue to receive update for 'a/e/f', since that node will not be included in the sub-tree of 'a/b'.

Type id: 146

Table Removed

This table has been removed from the lobby.  Table removed packets can be received for tables not included in the initial snapshot.

Type id: 147

Tournament Snapshot

Full lobby information regarding a tournament. If you are subscribing to a lobby path, then all successive packets for this table will be Tournament Update Packets.

Since tournaments are more diverse then tables, the common parameters capacity, registered, name and players are not included as fixed fields but rather as parameters. This way they will be included in the delta changes which is a more efficient way of sending out volatile data.

The fields supplied by Firebase are:

Type id: 148

Tournament Update

Delta changes for the given tournament. This packet assumes that you hold a reference for the tournament id(mttid) which contains the non-changed attributes. The Parameter map contains all attributes that are changed.

Se Tournament Snapshot for a list of fields provided by Firebase.

Type id: 149

Tournament Removed

This tournament has been removed from the lobby.

Type id: 150

Lobby Object Subscribe

Start a subscription to a specific lobby object.

To stop subscribe to a lobby object you must do an explicit Lobby Object Unsubscribe. Lobby object subscriptions will not be terminated by a regular Lobby Unsubscribe.

It is possible to subscribe to lobby objects before logging in.

Lobby enum, game id and update handling are the same as for a regular Lobby Subscription.

Type id: 151

Lobby Unsubscribe

Stop your subscription to a lobby object.

Lobby enum, game id and update handling are the same as for a regular Lobby Unsubscription.

Type id: 152

Table Snapshot Packet List

A list of table snapshots.

Type id: 153

Table Update Packet List

A list of table updates.

Type id: 154

Tournament Snapshot Packet List

A list of tournament snapshots.

Type id: 155

Tournament Update Packet List

A list of tournament updates.

Type id: 156

Filtered Join Packets

Filtered Join Table Request

Send a request to join a table with the given attributes. The handler on the server side will first try to match the request towards current tables. If no match is found then the request will be placed in the server side waiting list. In that case you will be prompted with a join packet when you are granted a seat.

The platform internal table attributes are:

Type id: 170

Example:

• Game: 99
• Address: /
• Key:         '_SEATED'
• Type:         INT
• Value:         0
• Op:         GREATER THAN

The request above will trigger when any tables for game id 99 has a table that has one or more seated players. (Internal fields like seated, game id etc. are all prefixed with an underscore, so seated = _SEATED).

Filtered Join Table Response

Response to the filtered request. This is not a seating response but rather a response that your request has been acknowledged.

Status is defined in the Filtered Join Response Status enumeration.

SEATING: A table was found and you will be seated / receive table available soon.

WAIT_LIST: No table was found right away so you are placed on the waiting list.

Type id: 171

Filtered Join Cancel Response

Cancel a request to join a table.

Type id: 172

Filtered Join Cancel Response

Response to the filtered request. This is not a seating response but rather a response that your request has been acknowledged.

Status is defined in the Response Status enumeration.

FAILED: An error was reported when removing the request (not expected)

DENIED: The request was not found. Perhaps we have found a match before the request was handled.

Type id: 173

Filtered Join Table Available

A table has been found that matches your filtered join request.

Type id: 174

Probe Packets

Probe Stamp

This is a data structure which is contained in other packets. It contains a class name and a time stamp (UTC)

Type id: 200

Probe

The probe is used for benchmarking and testing reasons. As the probe messages travels through the system it is stamped with different classes at strategical checkpoints. This allows for a fine grained latency check of the system.

Type id: 201

MTT Packets

MTT Register Request

Register for an MTT. An MTT Register Response will be returned by server.

Type id: 205

MTT Register Response

Response to a register request.

Status is defined in the Tournament Register Response Status enumeration.

Type id: 206

MTT Unregister Request

Unregister for an MTT. An MTT Unregister Response will be returned by server.

Type id: 207

MTT Unregister Response

Response to an unregister request.

Status is defined in the Response Status enumeration.

Type id: 208

MTT Seated

You have been seated at a table in a tournament.

Type id: 209

MTT Picked Up

You have been picked up from a table in a tournament. This could either be because you are out or that you are being move to a different table as a result of a table merge/balancing.

Type id: 210

Enumerations

Below are enumerations as defined in the protocol.

Definitions

Parameter Type

Parameter Filter

Lobby Type

Tournament Attributes

The name of the enumerations matches the supplied default attributes in the tournament lobby parameters.

Service Identifier        

Player Status

Response Statuses

Response Status

A generic response status enumeration.

Join Response Status

A generic response status enumeration.

Watch Response Status

Filtered Join Response Status

Tournament Register Response Status