Source generator for HexaEngine.Sappho serialization library. Automatically generates high-performance serialization code at compile-time for types marked with [SapphoObject] attribute. Part of the HexaEngine game engine ecosystem.
A high-performance, source-generated binary serialization library for .NET with support for polymorphism, cyclic references, and efficient memory management. Part of the HexaEngine game engine ecosystem.
Overview
HexaEngine.Sappho is a specialized serialization library designed for game development scenarios where performance is critical. Originally developed as a submodule for the HexaEngine game engine, it provides efficient binary serialization suitable for:
Game State Persistence: Save/load game states with complex object graphs
Network Communication: Fast serialization for multiplayer game data
Asset Management: Efficient binary formats for game assets
Scene Serialization: Handling complex game object hierarchies with circular references
While designed for game engines, Sappho is a standalone library suitable for any .NET application requiring high-performance binary serialization.
Features
🚀 High Performance: Optimized for speed with unsafe code and minimal allocations
🔄 Cyclic References: Automatic handling of circular object references
🎭 Polymorphism: First-class support for polymorphic serialization and deserialization
🔧 Flexible: Support for primitives, strings, enums, structs, and complex object graphs
💾 Efficient: Binary format with endian-aware operations
🎯 Type-Safe: Strongly-typed serialization with compile-time validation
Installation
dotnet add package HexaEngine.Sappho
Quick Start
1. Mark Your Classes
Use the [SapphoObject] attribute to mark classes or structs for serialization:
using HexaEngine.Sappho;
[SapphoObject]
public partial class Person
{
public string Name { get; set; }
public int Age { get; set; }
public float Height { get; set; }
}
Note: Classes must be marked as partial to allow the source generator to add serialization code.
2. Serialize and Deserialize
// Create a serialization context
var context = new SapphoSerializationContext();
// Create an object
var person = new Person
{
Name = "John Doe",
Age = 30,
Height = 5.9f
};
// Serialize
using var writer = new SapphoWriter(context);
writer.WriteObject(person);
// Deserialize
var reader = new SapphoReader(writer.Buffer, writer.Count, context);
var deserializedPerson = reader.ReadObject<Person>();
Advanced Features
Polymorphic Serialization
Use the [SapphoPolymorphic] attribute to enable polymorphic serialization:
[SapphoObject]
public partial class Animal
{
public string Name { get; set; }
}
[SapphoObject]
public partial class Dog : Animal
{
public string Breed { get; set; }
}
[SapphoObject]
public partial class Cat : Animal
{
public int LivesRemaining { get; set; }
}
[SapphoObject]
public partial class Zoo
{
[SapphoPolymorphic]
public Animal[] Animals { get; set; }
}
When using polymorphic types, register them with the serialization context:
context.RegisterType<Animal>(Animal.SapphoTypeId);
context.RegisterType<Dog>(Dog.SapphoTypeId);
context.RegisterType<Cat>(Cat.SapphoTypeId);
var zoo = new Zoo
{
Animals = new Animal[]
{
new Dog { Name = "Buddy", Breed = "Golden Retriever" },
new Cat { Name = "Whiskers", LivesRemaining = 9 }
}
};
Cyclic References
The library automatically handles cyclic references:
[SapphoObject]
public partial class Node
{
public string Name { get; set; }
public Node? Next { get; set; }
}
var node1 = new Node { Name = "Node 1" };
var node2 = new Node { Name = "Node 2" };
node1.Next = node2;
node2.Next = node1; // Cyclic reference
// Serialization will handle this correctly
Ignoring Properties
Use [SapphoIgnore] to exclude properties from serialization:
[SapphoObject]
public partial class CachedData
{
public string Data { get; set; }
[SapphoIgnore]
public string CachedValue { get; set; } // Not serialized
}
Custom Member Attributes
Use [SapphoMember] for fine-grained control over serialization:
[SapphoObject]
public partial class CustomClass
{
[SapphoMember]
public string ImportantField { get; set; }
}