Class SnapshotManager

Namespace

KeenEyes.Serialization

Assembly

KeenEyes.Core.dll

Provides functionality for creating, serializing, and restoring world snapshots.

public static class SnapshotManager

Inheritance

object

SnapshotManager

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Create a snapshot of the current world state
var snapshot = SnapshotManager.CreateSnapshot(world);

// Serialize to JSON
var json = SnapshotManager.ToJson(snapshot);

// Save to file
File.WriteAllText("save.json", json);

// Later, load and restore
var loadedJson = File.ReadAllText("save.json");
var loadedSnapshot = SnapshotManager.FromJson(loadedJson);
SnapshotManager.RestoreSnapshot(world, loadedSnapshot, typeResolver);

Remarks

The SnapshotManager is the central handler for world persistence. It captures the complete state of a world including all entities, components, hierarchy relationships, and singletons.

Snapshots can be serialized to JSON format for storage and later restored. The serialization uses System.Text.Json for efficient processing.

Methods

CreateSnapshot(World, IComponentSerializer, IReadOnlyDictionary<string, object>?)

Creates a snapshot of the current world state using AOT-compatible serialization.

public static WorldSnapshot CreateSnapshot(World world, IComponentSerializer serializer, IReadOnlyDictionary<string, object>? metadata = null)

Parameters

world World

The world to capture.

serializer IComponentSerializer

Component serializer for AOT-compatible serialization. Pass an instance of the generated ComponentSerializationRegistry which implements this interface for components marked with [Component(Serializable = true)].

metadata IReadOnlyDictionary<string, object>

Optional metadata to include in the snapshot.

Returns

WorldSnapshot

A snapshot containing all entities, components, hierarchy, and singletons.

Remarks

The snapshot captures:

• All entities and their IDs
• All components attached to each entity
• Entity names (if assigned)
• Parent-child hierarchy relationships
• All world singletons

Component and singleton data is pre-serialized to JSON using the provided serializer for Native AOT compatibility. This eliminates the need for reflection during JSON serialization.

Exceptions

ArgumentNullException

Thrown when world or serializer is null.

FromBinaryStream<TSerializer>(Stream, TSerializer)

Deserializes a snapshot from a stream in binary format using native binary deserialization.

public static WorldSnapshot FromBinaryStream<TSerializer>(Stream stream, TSerializer serializer) where TSerializer : IComponentSerializer, IBinaryComponentSerializer

Parameters

stream Stream

The stream to read from.

serializer TSerializer

Component serializer that implements both IComponentSerializer and IBinaryComponentSerializer.

Returns

WorldSnapshot

The deserialized snapshot.

Type Parameters

TSerializer

Remarks

Use this overload for streaming scenarios or when reading directly from files to avoid intermediate byte array allocations.

Component data is read using native binary deserialization via ReadFrom(string, BinaryReader), then converted to JsonElement using Serialize(Type, object) for storage in the snapshot.

Exceptions

ArgumentNullException

Thrown when any parameter is null.

InvalidDataException

Thrown when the binary data is invalid or corrupted.

FromBinary<TSerializer>(byte[], TSerializer)

Deserializes a snapshot from binary format.

public static WorldSnapshot FromBinary<TSerializer>(byte[] data, TSerializer serializer) where TSerializer : IComponentSerializer, IBinaryComponentSerializer

Parameters

data byte[]

The binary data to deserialize.

serializer TSerializer

Component serializer that implements both IComponentSerializer and IBinaryComponentSerializer.

Returns

WorldSnapshot

The deserialized snapshot, or null if the data is invalid.

Type Parameters

TSerializer

Examples

var binary = File.ReadAllBytes("save.bin");
var snapshot = SnapshotManager.FromBinary(binary, serializer);
SnapshotManager.RestoreSnapshot(world, snapshot, componentSerializer);

Remarks

This method validates the binary header before attempting deserialization. If the magic bytes or version are invalid, an exception is thrown.

Component data is read using native binary deserialization via ReadFrom(string, BinaryReader), then converted to JsonElement using Serialize(Type, object) for storage in the snapshot.

Exceptions

ArgumentNullException

Thrown when data or serializer is null.

InvalidDataException

Thrown when the binary data is invalid or corrupted.

FromJson(string)

Deserializes a snapshot from JSON format using AOT-compatible source generation.

public static WorldSnapshot? FromJson(string json)

Parameters

json string

The JSON string to deserialize.

Returns

WorldSnapshot

The deserialized snapshot.

Remarks

This method deserializes the WorldSnapshot envelope (metadata, entity list, etc.), not component data. Component data deserialization is handled by IComponentSerializer for AOT compatibility.

Uses source-generated JSON serialization which is fully Native AOT compatible. The deserialization expects camelCase naming and supports fields.

Exceptions

ArgumentNullException

Thrown when json is null.

JsonException

Thrown when the JSON is invalid.

RestoreSnapshot(World, WorldSnapshot, IComponentSerializer)

Restores a world from a snapshot using AOT-compatible deserialization.

public static Dictionary<int, Entity> RestoreSnapshot(World world, WorldSnapshot snapshot, IComponentSerializer serializer)

Parameters

world World

The world to restore into. Will be cleared before restoration.

snapshot WorldSnapshot

The snapshot to restore from.

serializer IComponentSerializer

Component serializer for AOT-compatible deserialization. Pass an instance of the generated ComponentSerializationRegistry which implements this interface for components marked with [Component(Serializable = true)].

Returns

Dictionary<int, Entity>

A dictionary mapping original entity IDs from the snapshot to newly created entities.

Remarks

This method first clears the world using Clear(), then recreates all entities with their components. Entity IDs in the restored world may differ from the original IDs in the snapshot.

Hierarchy relationships are reconstructed after all entities are created.

The source generator creates ComponentSerializationRegistry which implements IComponentSerializer for components marked with [Component(Serializable = true)].

Exceptions

ArgumentNullException

Thrown when world, snapshot, or serializer is null.

ToBinaryStream<TSerializer>(WorldSnapshot, TSerializer, Stream)

Serializes a snapshot to a stream in binary format using native binary serialization.

public static void ToBinaryStream<TSerializer>(WorldSnapshot snapshot, TSerializer serializer, Stream stream) where TSerializer : IComponentSerializer, IBinaryComponentSerializer

Parameters

snapshot WorldSnapshot

The snapshot to serialize.

serializer TSerializer

Component serializer that implements both IComponentSerializer and IBinaryComponentSerializer.

stream Stream

The stream to write to.

Type Parameters

TSerializer

Remarks

Use this overload for streaming scenarios or when writing directly to files to avoid intermediate byte array allocations.

This method uses native binary serialization for component data. The JsonElement data in the snapshot is first deserialized using IComponentSerializer, then serialized to binary using IBinaryComponentSerializer.

Exceptions

ArgumentNullException

Thrown when any parameter is null.

ToBinary<TSerializer>(WorldSnapshot, TSerializer)

Serializes a snapshot to binary format using AOT-compatible serialization.

public static byte[] ToBinary<TSerializer>(WorldSnapshot snapshot, TSerializer serializer) where TSerializer : IComponentSerializer, IBinaryComponentSerializer

Parameters

snapshot WorldSnapshot

The snapshot to serialize.

serializer TSerializer

Component serializer that implements both IComponentSerializer and IBinaryComponentSerializer. Pass an instance of the generated ComponentSerializer which implements both interfaces for components marked with [Component(Serializable = true)].

Returns

byte[]

A byte array containing the serialized snapshot.

Type Parameters

TSerializer

Examples

var snapshot = SnapshotManager.CreateSnapshot(world, serializer);
var binary = SnapshotManager.ToBinary(snapshot, serializer);
File.WriteAllBytes("save.bin", binary);

Remarks

Binary format provides significant benefits over JSON:

• Smaller file sizes (typically 50-80% reduction)
• Faster serialization/deserialization
• No string parsing overhead

This method uses native binary serialization for component data, avoiding the overhead of JSON string parsing. The serializer must implement both IComponentSerializer (to deserialize JsonElement data) and IBinaryComponentSerializer (to write native binary).

The binary format is versioned to support future evolution while maintaining backwards compatibility.

Exceptions

ArgumentNullException

Thrown when snapshot or serializer is null.

ToJson(WorldSnapshot)

Serializes a snapshot to JSON format using AOT-compatible source generation.

public static string ToJson(WorldSnapshot snapshot)

Parameters

snapshot WorldSnapshot

The snapshot to serialize.

Returns

string

A JSON string representing the snapshot.

Remarks

This method serializes the WorldSnapshot envelope (metadata, entity list, etc.), not component data. Component data serialization is handled by IComponentSerializer for AOT compatibility.

Uses source-generated JSON serialization which is fully Native AOT compatible. The serialization uses camelCase naming, includes fields, and omits null values.

Exceptions

ArgumentNullException

Thrown when snapshot is null.