Ceiralizer.Generator 4.1.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.

Pre-Processing Pipeline (Payload Groups)

Ceiralizer supports an extensible pre-processing pipeline that transforms serialized byte blobs before they are written to the wire, and reverses the transform on deserialization. This is useful for encryption, compression, checksums, or any byte-level transform.

Architecture

How It Works

1. Declare payload groups on the packet type with [PacketPayloadGroup]
2. Assign fields to a group with [PayloadGroup] — fields in the same group must be contiguous in serialization order
3. Apply pre-processor attributes (your custom subclasses of PacketPreprocessAttribute) with GroupName and Order
4. The generator emits a dedicated GetGroup_{name}_Preprocessors() method per group
5. At runtime, the group's field blob is serialized to an inner buffer, run through the pipeline, then written as [length: int][blob: bytes]

Example

// Define a pre-processor
public class ReversePreprocessor : IPacketPreprocessor
{
    public byte[] Process(ReadOnlySpan<byte> data)
    {
        var arr = data.ToArray();
        Array.Reverse(arr);
        return arr;
    }
    public byte[] Unprocess(ReadOnlySpan<byte> data) => Process(data);
}

public class ReverseTransformAttribute : PacketPreprocessAttribute
{
    public override IPacketPreprocessor CreateProcessor() => new ReversePreprocessor();
}

// Use it on a packet
[PacketPayloadGroup("g1")]
[ReverseTransform(GroupName = "g1", Order = 0)]
public partial struct MyPacket : IPacket
{
    [PacketField]
    [PacketFieldOrder(0)]
    public int Id;

    [PacketField]
    [PacketFieldOrder(1)]
    [PayloadGroup("g1")]
    public int Value;
}

Ordering

Set Order on pre-processor attributes to control pipeline order within a group. Lower values run first during Process (serialize) and last during Unprocess (deserialize):

[PacketPayloadGroup("g1")]
[XorTransform(0xAA, GroupName = "g1", Order = 0)]  // runs first on serialize
[ReverseTransform(GroupName = "g1", Order = 1)]     // runs second on serialize

During deserialize, ReverseTransform.Unprocess runs first, then XorTransform.Unprocess.

Wire Format

[group_blob_length: int32][group_blob: byte[]]

The group blob is the result of running the pre-processor chain (Process) on the serialized fields. The length prefix allows the reader to extract the blob before reversing the pipeline.

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. Guid: 16 bytes. First three groups (4, 2, 2 bytes) are little-endian, last two groups (2, 6 bytes) are in display order — matches Guid.TryWriteBytes().
8. DateTime / TimeSpan: 8 bytes — Ticks as little-endian int64.
9. DateTimeOffset: 10 bytes — Ticks (int64, LE) then Offset.TotalMinutes (int16, LE).
10. Decimal: 16 bytes — four int32 values from decimal.GetBits(), each in little-endian order.
11. 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