Skip to main content

Bit Count

The bit count of Integer based fields can be set using the BitCountAttribute.

This will truncate the bits so that only the small bits are sent. There is no runtime range checking for values using BitCount, so the value that is too big or negative will not be unpacked correctly. Enum values are checked when weaving, see Enum Types.

This means that BitCount should not be used with values that can be negative because this data will be lost. If you do need to send negative values then use ZigZagEncode or BitCountFromRange

Use cases​

  • A Value with a maximum value
  • An index in an array of known size
    • eg array with 10 elements, the index can be sent as 4 bits
  • A Random int hash where you only need to send 16 bits

Supported Types​

  • Byte
  • Short
  • UShort
  • Int
  • Uint
  • Long
  • ULong
  • Enum

Example 1​

Health which is between 0 and 100

public class MyNetworkBehaviour : NetworkBehaviour 
{
[SyncVar, BitCount(7)]
public int Health;
}

BitCount = 7 so max value of Health is 127

health = 57 will serialize to 011_1001

health = -1 (out of range) will serialize to 111_1111

health = 130 (out of range) will serialize to 000_0010

Example 2​

Weapon index in a list of 6 weapons

public class MyNetworkBehaviour : NetworkBehaviour 
{
[SyncVar, BitCount(3)]
public int WeaponIndex;
}

BitCount = 3 so max value of Health is 7

WeaponIndex = 5 will serialize to 101

Enum Types​

BitCount can also be placed on an enum type. The bit count is then used everywhere that enum is sent:

  • SyncVars
  • RPC parameters
  • Fields in messages and structs
  • Collections and nullables, eg List<T>, T[] and T?

A BitCount on a field or parameter will override the one on the enum.

[BitCount(2)]
public enum WeaponType
{
Pistol = 0,
Rifle = 1,
Shotgun = 2,
Rocket = 3,
}

public class MyNetworkBehaviour : NetworkBehaviour
{
// sent using 2 bits, from the attribute on WeaponType
[SyncVar]
public WeaponType PrimaryWeapon;

// attribute on field overrides the one on WeaponType
[SyncVar, BitCount(4)]
public WeaponType SecondaryWeapon;

// each element in the list is sent using 2 bits
[ClientRpc]
public void RpcSetLoadout(System.Collections.Generic.List<WeaponType> weapons) { }
}

ZigZagEncode and BitCountFromRange can also be placed on an enum type.

Weave time checks​

When an enum is packed using BitCount, either from the enum type or from a field, Weaver checks every value defined in the enum. Weaver will give an error if:

  • A value does not fit in the bit count
  • A value is negative and ZigZagEncode is not used

This means that adding a new value to an enum that no longer fits will fail to compile, instead of being silently truncated.

note

Only defined values are checked. A value created by casting, eg (WeaponType)10, will still be truncated.

If you write your own write function for the enum, it will be used instead and the attribute on the enum is ignored.

Generated Code​

Source:

[SyncVar, BitCount(7)]
public int myValue;

Generated:

public override bool SerializeSyncVars(NetworkWriter writer, bool initialState)
{
ulong syncVarDirtyBits = base.SyncVarDirtyBits;
bool result = base.SerializeSyncVars(writer, initialState);

if (initialState)
{
writer.Write((ulong)this.myValue, 7);
return true;
}

writer.Write(syncVarDirtyBits, 1);
if ((syncVarDirtyBits & 1UL) != 0UL)
{
writer.Write((ulong)this.myValue, 7);
result = true;
}

return result;
}

public override void DeserializeSyncVars(NetworkReader reader, bool initialState)
{
base.DeserializeSyncVars(reader, initialState);

if (initialState)
{
this.myValue = (int)reader.Read(7);
return;
}

ulong dirtyMask = reader.Read(1);
if ((dirtyMask & 1UL) != 0UL)
{
this.myValue = (int)reader.Read(7);
}
}

Last updated for Mirage v101.8.0.