Describing kNet Messages in XML

Describing kNet Messages in XML

Letting the (de)serialization code serve as the sole reference and documentation of your application-level protocol can be very fragile for maintenance and future development. The kNet Application-level specification provides an XML schema for defining messages in the kNet Message Model. These XML files have the following uses:

• They serve as a good single source reference for the whole protocol.
• It is possible to implement type-safe immediate-mode (de)serialization by using the Message Template feature. See Type-safe serialized transmission using message templates.
• The MessageCompiler tool uses these XML files to generate serialization structures for declarative-mode serialization.

The XML format is best introduced using an example. The following XML snippet introduces a message that is used in a networked grid computing architecture when a new node introduces itself to the master server.

<message id="9" name="NetCrunchMsgClientIntroduction" reliable="true" inOrder="false" priority="100">
  <u32 name="Version" />
  <string name="ID" maxLength="256" />
  <string name="Name" maxLength="256" />
  <string name="Team" maxLength="256" />
  <string name="OS" maxLength="256" />
  <string name="Processor" maxLength="256" />
  <string name="CPUID" maxLength="256" />
  <u32 name="NumCores" />
  <u32 name="NumThreads" />
  <u32 name="ClockSpeed" />
  <u32 name="Memory" />
  <bit name="DedicatedClient" />
</message>

A message can contain the following types:

• bit, u8, s8, u16, s16, u32, s32, u64, s64: POD types of the given bit size. After a single bit, padding up to a full byte is not performed.
• float, double: Traditional IEEE-754 32-bit and 64-bit floating point values.
• string: A human-readable string. The encoding is not specified. The maxLength attribute specifies the maximum number of bytes the string contents can take up. If this field is not specified, the string length is not limited. If a string longer than this is received, it is truncated to the given size.
• struct: The given struct contains a nested structure inside it.

Field Count

A type can contain one of the attributes count="numElements" or dynamicCount="numBits" to specify that the given type occurs several time in the message. The count attribute defines a fixed multiplicity, i.e. the number of instances of the variable is always the same. The dynamicCount attribute specifies a variable-length multiplicity. Between different instances of this message, the number of instances of the field can change. The number of occurrences of this type is serialized to the stream, so the count can be recovered when deserializing. The numBits value specifies how many bits are used in the stream to store the count.

The following example shows the usage of the count and dynamicCount fields. This message is taken from a networked game application where the message sends a list of objects that have their physics updates inactivated due to them reaching a rest state. This message can send updates for at most 256 objects.

<message id="212" name="ECAObjectsStopped" reliable="true" inOrder="true" priority="100">
  <struct name="ObjectInfo" dynamicCount="8">
    <float name="position" count="3" />
    <u16 name="rotation" count="3" />    
  </struct> 
</message>