2011-01-13

cubeia

Using the Styx protocol in your Firebase games

Styx is the binary protocol that the Firebase Server uses for communication with clients.
The styx wire-format is a very efficient and simple binary data stream that can potentially save a lot of bandwith cost.

Packet Structure.

Each packet starts with a header that consist of the total packet length + packet identifier;
The length is a 32 bit integer. The indentifier is an unsigned 8 bit value (1-255) that identifies each packet.
The serialized object data is streamed immediately after the header.

Lists are serialized with a 32 bit length prefix and strings are serialized with a 16 bit length prefix.

The following basic primitives are supported:

  • int8 – signed 8 bit integer
  • int16 – signed 16 bit integer
  • int32 – signed 32 bit integer
  • int64 – signed 64 bit integer
  • uint8 – unsigned 8 bit integer
  • uint16 – unsigned 16 bit integer
  • uint32 – unsigned 32 bit integer
  • uint64 – unsigned 64 bit integer
  • string – String value with length prefix
  • bool – Boolean value serialized as a int8 (0 or 1)

All integer types wider than 8 bits are sent in network byte order (big-endian, most significant bit first).

Protocol Generator.

We use a protocol generator plugin for maven to automatically produce sources of different languages.

Supported languages:

  • Java
  • ActionScript 3.0
  • C++

Experimental generation for C# and for generating a protobuf definition file is also included but not yet supported.

The source for the generator is a XML  file that defines each object, it has a two different types that can be used:

* enums
* structs (Objects)

An enum can contain one or more values, example:

<enum name=”name_of_enum”>
<value>MYENUM</value>
</enum>
<enum name="name_of_enum">
    <value>MYENUM</value>
</enum>

All names will be camelcased and stripped from the underscore automatically by the generator, the above XML-snippet will produce an enum with the name NameOfEnum.

The struct parameters are name and an optional id, the id parameter defines the class id, if not specified, the styx generator will use the next availabe id (last seen +1).

A struct member can be either a var or a list of vars, both lists and vars have a name and type parameter, example:

<struct id="1" name="test_packet">
    <var name="name" type="string"/>
</struct>
The type can be of the basic primitives, enums or other structs.

To create a list of the above struct  in a new object called TestListPacket we define it like this in the xml file:

<struct id="2" name="test_list_packet">
    <list name="test_packet_list" type="test_packet"/>
</struct>

The byte serialized stream for the TestListPacket with one TestPacket object containing the string ”test” in the name member will look like this:

00 00 00 0f 02 00 00 00 01 00 04 74 65 73 74

If we break it down, we have the following:
Total length: 15 (first four bytes)
Class id: 2 (fifth byte)
Length of list: 1 (bytes 6-9)
String length: 4 (bytes 10-11)
String data: test (bytes 12-15)

As you clearly can see, Styx is a very efficient protocol that can save a lot of bandwith.

Download the sample , unzip to your directory of choice and execute: mvn clean package in this directory. The generator will compile the java files and create a jar ready for import.
The other languages is found under directory target/jruby-protocol-plugin/generated-sources.

Note: the pom.xml file is configured to use a snapshot version of the protocol plugin, I will update this article when the next release has been made.

Firebase protocol documentation