Clone wiki

Cubeia Styx / Home


Welcome to Cubeia Styx. It is a wire format supporting a compact binary packaging as well as text based JSON and contains a protocol generator tool (Maven plugin) for creating protocol objects in Java, C++, Flash, JavaScript and C#.

Binary Format

Each packet starts with a header that consist of the total packet length + packet identifier. The length is a 32 bit integer and The identifier is an unsigned 8 bit value (1-255) that identifies each packet within the protocol.

The serialized object data is streamed immediately after the header.

| 32 bit length | 8 bit ID | <data> | 

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 - NOTE: not fully supported in javascript and possibly other languages
uint16 – unsigned 16 bit integer
uint32 – unsigned 32 bit integer
string – UTF-8 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).

IMPORTANT: 64 bit integers (long) are not fully supported in most languages. In Java only signed 64 bit integers are supported (long). In Javascript numbers are 64 bit floats (IEEE-754) and can only handle 53 bit integers without approximation. If you need to handle big numbers with high precision please consider using strings for transport.

JSON Format

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.

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.

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

Enumerations are encoded as JSON strings.

Protocol Generator

The protocol generator is a Maven plugin that takes a protocol specification in an XML file and generates protocol objects in various languages such as Java, JavaScript, Flash, C++ etc.

Experimental generation for C# and for generating a protobuf definition file is also included but not yet fully 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”>

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). This ID is equivalent to the ID header in the binary wire format.

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"/>

The type can be of the basic primitives, enums or other structs. For example: 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"/>

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)

The JSON packaging of the same will look like below, note the "classId" members which are sued to identify each Styx struct type. Also, each member is identified by name, making the protocol more verbal than the binary packaging but also eligible for compression:


Language Specific Information