Prowl.Echo 1.2.0

Prowl.Echo Serializer

A lightweight, flexible serialization system (Built for the Prowl Game Engine). The serializer supports complex object graphs, circular references, and custom serialization behaviors.

Echo does what the name suggests, and create an "Echo" an intermediate representation of the target object. This allows for fast inspection and modification before converting to Binary or Text.

Features

• Type Support

  • Primitives (int, float, double, string, bool, etc.)
  • Complex objects and nested types
  • Collections (List, Array, HashSet)
  • Dictionaries
  • Enums
  • DateTime and Guid
  • Nullable types
  • Circular references
  • Multi-dimensional and jagged arrays
  • Support for custom serializable objects

• Flexible Serialization Control

  • Custom serialization through ISerializable interface
  • Attribute-based control ([FormerlySerializedAs], [IgnoreOnNull])
  • Support for legacy data through attribute mapping

• Misc

  • Battle Tested in the Prowl Game Engine
  • Supports both String & Binary formats
  • Mimics Unity's Serializer
  • GUID-based Resource Dependency Tracking built right in, No overhead when unused.

Usage

Basic Serialization

// Serialize an object
var myObject = new MyClass { Value = 42 };
var serialized = Serializer.Serialize(myObject);

// Deserialize back
var deserialized = Serializer.Deserialize<MyClass>(serialized);

Serializating to Text

var serialized = Serializer.Serialize(myObject);

// Save to Text
string text = serialized.WriteToString();

// Read to From
var fromText = EchoObject.ReadFromString(text);

var deserialized = Serializer.Deserialize<MyClass>(fromText);

Custom Serialization - Fastest mode Echo has to offer

public class CustomObject : ISerializable
{
    public int Value = 42;
    public string Text = "Custom";
	public MyClass Obj = new();

    public EchoObject Serialize(SerializationContext ctx)
    {
        var compound = EchoObject.NewCompound();
        compound.Add("value", new(Value));
        compound.Add("text", new(Text));
        compound.Add("obj", Serializer.Serialize(Obj, ctx));
        return compound;
    }

    public void Deserialize(EchoObject tag, SerializationContext ctx)
    {
        Value = tag.Get("value").IntValue;
        Text = tag.Get("text").StringValue;
		Obj = Serializer.Deserialize(tag.Get("obj"), ctx);
    }
}

Working with Collections

// Lists
var list = new List<string> { "one", "two", "three" };
var serializedList = Serializer.Serialize(list);

// Dictionaries
var dict = new Dictionary<MyClass, int> {
    { new("one"), 1 },
    { new("two"), 2 }
};
var serializedDict = Serializer.Serialize(dict);

// Arrays
var array = new int[] { 1, 2, 3, 4, 5 };
var serializedArray = Serializer.Serialize(array);

Handling Circular References

var parent = new CircularObject();
parent.Child = new CircularObject();
parent.Child.Child = parent; // Circular reference
var serialized = Serializer.Serialize(parent);

Using Attributes

public class MyClass
{
    [FormerlySerializedAs("oldName")]
    public string NewName = "Test";

    [IgnoreOnNull]
    public string? OptionalField = null;
}

Limitations

• Properties are not serialized (only fields)
• No benchmarks exist but performance is expected to be lacking

Performance

Echo prioritizes simplicity over raw performance. If your looking for an ultra-fast serializer you may want to consider alternatives. However, If you're using Echo and need better performance:

1. Implement ISerializable for your critical types - this can significantly outperform the default reflection-based approach
2. Minimize deep object graphs when possible
3. Consider using binary format instead of text, as the text format is significantly slower

License

This component is part of the Prowl Game Engine and is licensed under the MIT License. See the LICENSE file in the project root for details.