Ceiralizer.Generator 3.2.0

Ceiralizer

A C# source-generated serialization library for converting structs and classes into compact binary data and back. Designed for network packet serialization.

NuGet:

• https://www.nuget.org/packages/Ceiralizer
• https://www.nuget.org/packages/Ceiralizer.Generator (source generator — required alongside the main package)

How It Works

Ceiralizer uses a Roslyn incremental source generator to automatically emit Serialize() and Deserialize() methods at compile time for any type implementing IPacket. Just mark fields with [PacketField] and make the type partial.

Quick Start

1. Define Your Packet

using Ceiralizer;
using Ceiralizer.Attributes;

public partial struct MyPacket : IPacket
{
    [PacketField] public int Id;
    [PacketField] public string Name;
    [PacketField] public float[] Values;
}

2. Serialize & Deserialize

var packet = new MyPacket
{
    Id = 42,
    Name = "Hello",
    Values = [1.5f, 2.5f, 3.0f]
};

// Serialize to byte[]
byte[] data = packet.Serialize();

// Deserialize from byte[]
MyPacket result = MyPacket.Deserialize(data);

Console.WriteLine(result.Name); // Output: Hello

Supported Field Types

[PacketBitPacked(int bitLength = 1)]

Pack boolean and integer fields into individual bits instead of their full byte size. Multiple consecutive [PacketBitPacked] fields are grouped into the minimum number of bytes needed. Only consecutive bit-packed fields are packed together — a non-bit-packed field breaks the group.

public partial struct BitPackedPacket : IPacket
{
    [PacketField] [PacketBitPacked] public bool IsEnabled;   // 1 bit
    [PacketField] [PacketBitPacked] public bool IsVisible;   // 1 bit
    [PacketField] [PacketBitPacked(5)] public int Health;    // 5 bits
    [PacketField] public int NormalInt;                       // full int32
    [PacketField] [PacketBitPacked] public bool IsAlive;     // 1 bit
    [PacketField] [PacketBitPacked(3)] public int Level;     // 3 bits
}

The generator emits inline bit operations — no runtime overhead:

// Serialize (7 bits packed into 1 byte, another 4 bits into 1 byte):
byte IsEnabled_bits = (byte)0;
IsEnabled_bits = (byte)(IsEnabled_bits | (byte)(IsEnabled ? 1 : 0) << 0);
IsEnabled_bits = (byte)(IsEnabled_bits | (byte)(IsVisible ? 1 : 0) << 1);
IsEnabled_bits = (byte)(IsEnabled_bits | (byte)(Health & 0x1F) << 2);
writer.Write((byte)(IsEnabled_bits >> 0));
writer.Write(NormalInt);
byte IsAlive_bits = (byte)0;
IsAlive_bits = (byte)(IsAlive_bits | (byte)(IsAlive ? 1 : 0) << 0);
IsAlive_bits = (byte)(IsAlive_bits | (byte)(Level & 0x7) << 1);
writer.Write((byte)(IsAlive_bits >> 0));

Size reduction example: BitPackedPacket above takes 6 bytes instead of 15 (normal).

The accumulator type scales with the group size: | Group bits | Accumulator | Bytes written | |-----------|-------------|---------------| | 1-8 | byte | 1 | | 9-16 | ushort | 2 | | 17-32 | uint | 4 | | 33-64 | ulong | 8 |

Bit length is automatically clamped to the field type's capacity (e.g. [PacketBitPacked(100)] on a byte becomes 8).

Configuration Attributes

[PacketFieldOrder(int order)]

Control serialization order. Fields are sorted ascending (unmarked fields have implicit order -1, serialized first in declaration order).

public partial struct OrderedPacket : IPacket
{
    [PacketField] [PacketFieldOrder(3)] public int Third;
    [PacketField] [PacketFieldOrder(1)] public int First;
    [PacketField] [PacketFieldOrder(2)] public int Second;
}

[PacketStringOptions(encoder, stringPrefixLength)]

Control string encoding and length prefix per-field or per-type.

using Ceiralizer.Models;

public partial struct StringOptionsPacket : IPacket
{
    [PacketField]
    [PacketStringOptions(encoder: TextEncoding.ASCII, stringPrefixLength: PrefixType.Short)]
    public string AsciiShort;

    [PacketField]
    [PacketStringOptions(encoder: TextEncoding.Unicode)]
    public string UnicodeString;
}

Apply to the type itself for a default:

[PacketStringOptions(encoder: TextEncoding.ASCII, stringPrefixLength: PrefixType.Short)]
public partial struct TypeLevelPacket : IPacket
{
    [PacketField] public string Name;
}

Encoding options: ASCII, UTF7, UTF8 (default), UTF32, Unicode, BigEndianUnicode

Prefix options: Byte, SByte, Short, UShort, Int (default)

[PacketCollectionOptions(size)]

Control array serialization. size = 0 (default) = dynamic (length-prefixed). size > 0 = fixed-size (no prefix).

public partial struct CollectionOptionsPacket : IPacket
{
    [PacketField] [PacketCollectionOptions(size: 0)] public int[] Dynamic;
    [PacketField] [PacketCollectionOptions(size: 5)] public int[] FixedSize; // exactly 5 elements
}

Apply to the type itself:

[PacketCollectionOptions(size: 3)]
public partial struct FixedArrayPacket : IPacket
{
    [PacketField] public int[] Values; // always 3 elements
}

Custom Serialization

ISerializable — Custom logic on the type itself

Implement ISerializable for types that need manual serialization:

public class FooBar : ISerializable
{
    public int A { get; set; }
    public string B { get; set; } = string.Empty;

    public void Serialize(ChunkWriter writer)
    {
        writer.Write(A);
        writer.Write(B.Length);
        writer.Write(B, Encoding.UTF8);
    }

    public void Deserialize(ChunkReader reader)
    {
        A = reader.ReadInt();
        int len = reader.ReadInt();
        B = reader.ReadString(Encoding.UTF8, len);
    }
}

public partial struct PacketWithSerializable : IPacket
{
    [PacketField] public FooBar Data;
}

ICustomSerializer<T> — External serializer for types you don't control

public readonly record struct Vector3(float X, float Y, float Z);

public class Vector3Serializer : ICustomSerializer<Vector3>
{
    public static void Serialize(Vector3 vec, ChunkWriter writer)
    {
        writer.Write(vec.X);
        writer.Write(vec.Y);
        writer.Write(vec.Z);
    }

    public static Vector3 Deserialize(ChunkReader reader)
    {
        return new Vector3(reader.ReadFloat(), reader.ReadFloat(), reader.ReadFloat());
    }
}

public partial struct PacketWithCustomSerializer : IPacket
{
    [PacketField] public Vector3 Position;
}

Note: Fields using ISerializable or ICustomSerializer<T> must still be marked with [PacketField].

Delta Compression

Ceiralizer supports delta compression for frequently updated packets via the IDeltaPacket interface. Instead of sending the full packet every time, you send only the fields that changed since the last known state — reducing bandwidth for repeated transmissions.

Enable Delta Compression

Change your packet from IPacket to IDeltaPacket:

public partial struct PlayerState : IDeltaPacket
{
    [PacketField] public int Health;
    [PacketField] public float X;
    [PacketField] public float Y;
}

The source generator produces two additional methods:

// Writes only the fields that differ from `previous`
void SerializeDelta(ChunkWriter writer, PlayerState previous);

// Reads a delta and applies it to `previous`, returning the new state
static PlayerState DeserializeDelta(ChunkReader reader, PlayerState previous);

Usage

var prev = new PlayerState { Health = 100, X = 1.5f, Y = 2.5f };
var curr = new PlayerState { Health = 100, X = 3.5f, Y = 4.5f };

// SerializeDelta — only the changed fields (X, Y) are written
var writer = new ChunkWriter(new ArrayBufferWriter<byte>());
curr.SerializeDelta(writer, prev);
byte[] delta = writer.GetWrittenData();

// DeserializeDelta — applies the delta to the previous state
var reader = new ChunkReader(delta);
PlayerState result = PlayerState.DeserializeDelta(reader, prev);
Console.WriteLine(result.X); // 3.5f (updated)
Console.WriteLine(result.Health); // 100 (unchanged, preserved)

Wire Format

[bitmask: ceil(N/8) bytes] [changed field values...]

Each [PacketField] occupies one bit in the bitmask. A 1 means the field changed and its value follows. A 0 means the field is unchanged and skipped. The mask size scales: 1-8 fields → 1 byte, 9-16 → 2 bytes, 17-32 → 4 bytes, 33-64 → 8 bytes.

Comparison strategy:

[DeltaIgnore]

Skip a field from delta compression entirely — it contributes no bit to the mask, is never compared, and is never written/read during delta operations.

public partial struct PlayerState : IDeltaPacket
{
    [PacketField] public int Health;
    [PacketField] [DeltaIgnore] public int SessionFlags;  // excluded from delta
    [PacketField] public string Name;
}

Changes to SessionFlags do not appear in SerializeDelta output and are preserved from the previous state during DeserializeDelta.

Delta Saves Bandwidth

// Full serialization sends everything
byte[] full = curr.Serialize(); // 12 bytes (int + float + float)

// Delta sends only changed bits + values
prev = new PlayerState { Health = 100, X = 1.5f, Y = 2.5f };
curr = new PlayerState { Health = 100, X = 3.5f, Y = 4.5f };
// mask(1) + X(4) + Y(4) = 9 bytes vs 12

With only one field changed, the delta is even smaller: mask(1) + value(4) = 5 bytes vs 12 full.

How Serialization Works

1. Source generation: At compile time, the generator produces Serialize(ChunkWriter), Serialize() (returns byte[]), Deserialize(ChunkReader), and Deserialize(byte[]) for every partial type implementing IPacket.
2. Field ordering: Fields are serialized in [PacketFieldOrder] ascending order; unmarked fields come first in declaration order.
3. Strings: Stored as byte-length prefix (configurable) + encoded bytes.
4. Arrays: Stored as element-count prefix (int) for dynamic arrays, or no prefix for fixed-size arrays.
5. Bit packing: Consecutive [PacketBitPacked] fields are packed into the minimum number of bytes using bitwise operations. Groups are written separately — a non-bit-packed field breaks the group.
6. Nested packets: Fields are serialized sequentially (flattened).
7. Byte order: All multi-byte values are little-endian.

Binary Format Example

For a SimplePacket with fields int Id and string Name ("AB"):

[int: 256]     [int: 2 (string byte length)]   [bytes: "AB"]
00 01 00 00  | 02 00 00 00                   | 41 42