Serialization

Nebula writes messages as little-endian byte streams with NetworkWriter and reads them with NetworkReader. The default format does not apply bit packing, quantization, or delta compression.

Read each field in the same order and with the same type used to write it. A mismatched reader can corrupt the rest of the message or throw when it reaches the end.

Implement INetworkSerializable on custom structs and classes. NetworkVariable<T> and RPC arguments use the serializers registered in NetworkSerialization.

NetworkWriter and NetworkReader

NetworkWriter is a growable buffer; reuse one instance and call Reset() between messages. NetworkReader wraps an ArraySegment<byte> and throws InvalidOperationException on any read past the end, so a malformed packet fails loudly instead of returning garbage.

Primitives

Strings and bytes

Unity types

Compact forms

NetworkTransform exposes precision and compression options for root and child updates. Root velocity uses half floats when enabled.

Reserve and patch

When a count or a length is only known after writing the payload, reserve the slot and patch it:

int at = writer.ReserveUShort();      // writes a placeholder, returns its position
ushort n = 0;
foreach (var item in items) { item.Serialize(writer); n++; }
writer.PatchUShort(at, n);

Rewind(int length) drops everything written after a previous Length, which is how a message that turned out to be empty is discarded without allocating. ToSegment() returns the written bytes without a copy; ToArray() copies.

On the reader, Remaining and Position tell you where you are, Skip(int) advances without reading, and Set(ArraySegment<byte>) re-points an existing reader at a new buffer.

INetworkSerializable

Implement INetworkSerializable on a struct (or class) to use it as a NetworkVariable<T> value, an RPC argument, or a predicted input (INetworkInput is INetworkSerializable with no extra members). Deserialize must mirror Serialize exactly:

public struct PlayerInput : INetworkInput
{
    public Vector2 Move;
    public float Yaw;
    public float Pitch;
    public byte Buttons;
    public uint AimTick;

    public void Serialize(NetworkWriter writer)
    {
        writer.WriteVector2(Move);
        writer.WriteFloat(Yaw);
        writer.WriteFloat(Pitch);
        writer.WriteByte(Buttons);
        writer.WriteUInt(AimTick);
    }

    public void Deserialize(NetworkReader reader)
    {
        Move = reader.ReadVector2();
        Yaw = reader.ReadFloat();
        Pitch = reader.ReadFloat();
        Buttons = reader.ReadByte();
        AimTick = reader.ReadUInt();
    }
}

When Nebula deserialises such a type by reflection (an RPC argument, a NetworkVariable value) it creates the instance with Activator.CreateInstance, so a class needs a public parameterless constructor; a struct always has one. Writing a null reference of an INetworkSerializable class throws; use a struct or a sentinel value instead.

NetworkSerialization

NetworkSerialization is the type-driven table behind NetworkVariable<T> and RPC arguments. Write<T> and Read<T> (and their object-typed forms) look the type up and either call a registered delegate, write an enum as its int value, or call INetworkSerializable.

Built-in types

CanSerialize(Type) answers whether a type is in that set; the RPC table uses it to reject unserialisable parameters when a class is first bound.

Not built in: Vector4, Vector2Int, Vector3Int, Bounds, Rect, Matrix4x4, Color32, DateTime, Guid, arrays other than byte[], List<T>, Dictionary<K,V>, nullable value types. Register them or wrap them.

Register<T> for types you cannot modify

For a type you do not own, or a built-in you want on the wire in a different format, register a writer and reader pair. Registration replaces any existing entry for that type, and registered delegates take precedence over the enum and INetworkSerializable paths.

public static class GameSerializers
{
    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
    private static void Register()
    {
        NetworkSerialization.Register<Vector2Int>(
            (w, v) => { w.WriteInt(v.x); w.WriteInt(v.y); },
            r => new Vector2Int(r.ReadInt(), r.ReadInt()));

        NetworkSerialization.Register<Guid>(
            (w, v) => w.WriteBytes(v.ToByteArray()),
            r => new Guid(r.ReadBytes()));
    }
}

Register before the first entity spawns on every process, worker and client alike. The RPC table is built the first time a class is used, and it throws for an unregistered parameter type at that point.

Where serialization is used

Read exactly what you wrote

Network messages do not describe their own field types. If Deserialize reads a float where Serialize wrote a byte, it consumes three bytes that belong to later data. Follow these rules:

1. Write Serialize and Deserialize next to each other, one line per field, in the same order.
2. Never make a write conditional on state the reader does not have. Write a bool first and branch on it in both directions if a field is optional.
3. Keep the same build on every process. A worker and a client running different versions of a struct will desynchronise silently on the first message.

NetworkReader detects only reads past the end of its buffer. It cannot detect a type mismatch in the middle of a message.

Bounded chunks for handover and sync state

NetworkIdentity.WriteHandoverState writes a separate length-prefixed section for each behavior. ReadHandoverState gives each behavior a reader limited to its section.

If a behavior reads too much, Nebula logs the error and continues with the next section. If it reads too little, Nebula skips to the start of the next section.

The sync channel also limits each behavior to its own section. Nebula logs an error from ReadSyncState, skips an unknown behavior index, and continues reading later sections.

NetworkVariable blobs, RPC arguments and predicted inputs are not bounded this way: they are written back to back, and a mismatch cascades into whatever follows. For those, the "same code on every process" rule is the protection.