Field settings

Many of the primitive data types in coherence support configuration to make it possible to optimize the data being sent over the network. These settings can be made individually for each field of a component and will then be used throughout your code base.

Syntax

The field settings uses the meta data syntax in the schema, which looks like this:

[key1 "value1", key2 "value2", etc...]

The meta data always goes at the end of the line and can be set on both definitions and the fields within a definition, like this:

component Health [prio "low"]
  value Float [bits "8"]

In this example, a component named Health would be created, but instead of using the default 24 bits when sending its value, it would just use 8. Any updates to it would also be deprioritized compared to other components, so it could potentially be sent a bit late if bandwidth is scarce.

Component updates do not only contain the actual data of the update, but also information about what Entity should be affected, etc. This means that the total saving of data won't be quite as large as you'd think when going from 24 to 8 bits. Still, it's a great improvement!

Priority

All components support a piece of meta data that affects how highly the Replication Server will prioritize sending out updates for that particular component.

This meta data is set on components, like this:

component House [prio "low"]

The available priority levels are:

• "very-low"

• "low"

• "mid" (default)

• "high"

• "very-high"

Bit optimizations

Some of the primitive types support optimizing the number of bits used to encode them when sending the over the network. It's worthwhile to think through if you can get away with less information than the default, to make room for more frequent updates.

Float, Vector2, Vector3

All of these types support the same two settings:

• compression - type of compression used

  • None - no compression - full float will be sent

  • FixedPoint - user specified value range is divided equally using a defined precision. Requires range-min, range-max, bits and precision meta data.

  • Truncated - floating point precision bits are truncated, resulting in a precision loss, however with a full float value range available

• bits – how many bits the type should use to encode its floating point values. Usable only with FixedPoint and Truncated compressions

• precision – how much precision will be guaranteed. Usable only with FixedPoint compression. Strictly related to bits and shouldn't be set manually

Int32, UInt32

Integers can be configured to only hold a certain range via:

• range-min – the lowest possible value that the integer can hold

• range-max – the largets possible value that the integer can hold

Using these settings you can emulate other numeric types like char, short, unsigned int, etc.

Quaternions

Quaternions can have a number of bits per component specified using the bits meta data. Serialization requires writing 3 components and an additional sign bit, thus the total amount of bits used for quaterion is bits * 3 + 1.

Colors

Quaternions can have a number of bits per component specified using the bits meta data. Serialization requires writing 4 components (RGBA), thus the total amount of bits used for color is bits * 4.

Other types

The other types don't have any settings that affect the number of bits they use. If they take up too much bandwidth you'll have to try to send them less often, using priority, update frequency, or LODing.