Commits

Lars J. Nilsson  committed d99a7a9

Edited online

  • Participants
  • Parent commits e45813d

Comments (0)

Files changed (1)

 == Welcome ==
 
-Welcome to your wiki! This is the default page we've installed for your convenience. Go ahead and edit it.
+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#.
 
-=== Wiki features ===
+=== 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.
 
-This wiki uses the [[http://www.wikicreole.org/|Creole]] syntax, and is fully compatible with the 1.0 specification.
+The serialized object data is streamed immediately after the header.
 
-The wiki itself is actually a mercurial repository, which means you can clone it, edit it locally/offline, add images or any other file type, and push it back to us. It will be live immediately.
+Lists are serialized with a 32 bit length prefix and strings are serialized with a 16 bit length prefix.
 
-Go ahead and try:
+The following basic primitives are supported:
 
 {{{
-$ hg clone https://bitbucket.org/cubeia/cubeia-styx/wiki
+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 – UTF-8 String value with length prefix
+bool – Boolean value serialized as a int8 (0 or 1)
 }}}
 
-Wiki pages are normal files, with the .wiki extension. You can edit them locally, as well as creating new ones.
+All integer types wider than 8 bits are sent in network byte order (big-endian, most significant bit first).
 
-=== Syntax highlighting ===
+=== 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.
 
-You can also highlight snippets of text, we use the excellent [[http://www.pygments.org/|Pygments]] library.
+Experimental generation for C# and for generating a protobuf definition file is also included but not yet fully supported.
 
-Here's an example of some Python code:
+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:
 
 {{{
-#!python
-
-def wiki_rocks(text):
-    formatter = lambda t: "funky"+t
-    return formatter(text)
+<enum name=”name_of_enum”>
+  <value>MYENUM</value>
+</enum>
 }}}
 
-You can check out the source of this page to see how that's done, and make sure to bookmark [[http://pygments.org/docs/lexers/|the vast library of Pygment lexers]], we accept the 'short name' or the 'mimetype' of anything in there.
+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".
 
-Have fun!
+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"/>
+</struct>
+}}}
+
+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"/>
+</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)
+
+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 elegible for compression:
+
+{{{
+{
+  "classId":2,
+  "test_packet_list":
+  [
+    { 
+      "classId":1,
+      "test_packet":"test"
+    }
+  ]
+}
+}}}