Bitpacking

Search…
Bitpacking
DOTSNET uses Bitpacking via BitWriter to serialize, and BitReader to deserialize data down to the bit.
Usage
For example, this is how we serialize an int and a float3 position in a message:
1
using DOTSNET;
2
​
3
public struct TestMessage : NetworkMessage
4
{
5
    public int classIndex;
6
    public float3 position;
7
    
8
    public byte GetID() => 0x31;
9
​
10
    public bool Serialize(ref BitWriter writer) =>
11
        writer.WriteInt(classIndex) &&
12
        writer.WriteFloat3(position);
13
​
14
    public bool Deserialize(ref BitReader reader) =>
15
        reader.ReadInt(out classIndex) &&
16
        reader.ReadFloat3(out position);
17
}
Copied!
Reading and Writing is:
Atomic: WriteInt either writes all 4 bytes int, or none if there is not enough space. ReadInt either reads all 4 bytes int, or none if the buffer doesn’t have enough data.
Allocation Free: all reads and writes are allocation free for maximum performance.
Fast: the Bitpacker’s internal buffer writes are always word aligned. This makes unaligned writes (byte/ushort/etc.) as fast as aligned writes (uint, float, etc.).
Reference Passing
To avoid allocations, BitReader/Writer are value types (structs). When passing a reader/writer through functions, make sure to pass it as reference:
1
public bool Serialize(ref BitWriter writer) =>
2
    writer.WriteInt(level);
3
​
4
public bool Deserialize(ref BitReader reader) =>
5
    reader.ReadInt(out level);

Copied!
If you don’t pass it as reference, then it will create a copy of the Writer/Reader, which would not modify the original writer/reader’s Position.
In other words, always pass BitReader/Writer as reference!

Bit Compression
BitWriter/Reader default functions always write the full type unless bitpacking parameters are specified. For example, let’s serialize/deserialize a player’s level which requires 32 bits uint by default:
1
writer.WriteUInt(5);
2
reader.ReadUInt(out uint value);
Copied!
If we know the value’s minimum and maximum data range, then we can do heavy bandwidth optimizations by packing it into the minimum amount of bits needed for that range. Our player’s level is always in the range of [1..60] so we can Bitpack it down from 32 bits to 6 bits:
1
// a player level of '5' with an expected range of [1..60]
2
// => 60 possible values in that range
3
// => they all fit into 6 bits
4
// => so the value is encoded into 6 bits, instead of 32 bits uint!
5
writer.WriteUInt(5, 1, 60);
6
reader.ReadUInt(out uint value, 1, 60);
Copied!
DOTSNET’s Bitpacking automatically does all the complicated bit math internally. All we need to do is specify the data type ranges if we know them.
This also works for float/double where we specify min, max, precision
1
writer.WriteFloat(1.23f, -10f, 10f, 0.1f);
2
reader.ReadFloat(out float value);
Copied!
Another interesting example is bool, which C# stores into 8 bit = 1 byte by default. A bool is always either 1 or 0, which fits perfectly into just 1 bit. DOTSNET packs bools automatically!
1
writer.WriteBool(true);
2
reader.ReadBool(out bool value);
Copied!
For a deeper understanding about Bitpacking, please read the excellent article by Glenn Fiedler!
Burst
DOTSNET also provides burstable BitReader/Writer implementations:
BitReader128
BitWriter128
The burstable Bitpackers are fixed size and can be used in IComponentData.
Extending BitReader/Writer
You can extend BitReader/Writer with C#’s extension system:
1
public struct MyStruct
2
{
3
    public int level;
4
    public int experience;
5
}
Copied!
1
using DOTSNET;    
2
​
3
public static class Extensions
4
{
5
    public static bool WriteMyStruct(this BitWriter writer, MyStruct value)
6
    {
7
        return writer.WriteInt(value.level) &&
8
               writer.WriteInt(value.experience);
9
    }
10
   
11
    public static bool ReadMyStruct(this SBitReader reader, out MyStruct value)
12
    {
13
        value = new MyStruct();
14
        return reader.ReadInt(out value.level) &&
15
               reader.ReadInt(out value.experience);
16
    }
17
}
Copied!
User Manual - Previous
PrefabSystem
Next - User Manual
Authentication
Last modified 5mo ago
Copy link
Contents
Extending BitReader/Writer