Class ScyllaSerialization

Static facade providing the main public entry point for the Scylla serialization system. Exposes thread-safe methods for serializing and deserializing objects to and from JSON and binary formats, registering custom type serializers, and managing schema migrations.

Inheritance
object
ScyllaSerialization
Inherited Members
Namespace: Scylla.Core.Util.Serialization
Assembly: ScyllaCore.dll
Syntax
public static class ScyllaSerialization
Remarks

ScyllaSerialization is a stateless facade over SerializationEngine. All serialization state (settings, reference tracking, depth tracking) is created per operation and discarded when the call returns. The class itself is safe to call concurrently from multiple threads.

Internally, the class maintains object pools for ScyllaJSONWriter, ScyllaJSONReader, and StringBuilder instances to avoid per-call allocations. The pools are initialized during the static constructor, which also ensures the SerializationEngine is initialized with all built-in type serializers.

Supported types out of the box: all C# primitive types, string, byte[], common System value types (DateTime, TimeSpan, Guid, DateTimeOffset), Unity primitive types (Vector2, Vector3, Vector4, Quaternion, Color, Color32, Bounds, Rect, RectInt, LayerMask), enums (serialized as their string names), arrays, List<T>, Dictionary<TKey,TValue>, HashSet<T>, Queue<T>, Stack<T>, and any class or struct handled by ReflectionSerializer.

Custom types: classes and structs that do not have a registered serializer are handled automatically by the ReflectionSerializer, which uses cached reflection to read and write public fields and properties. Decorate types with ScyllaSerializableAttribute to enable schema versioning and migration. Use ScyllaPropertyAttribute to customize property names and ordering, ScyllaIgnoreAttribute to exclude members, and ScyllaIncludeAttribute to include non-public members.

Binary format note: the Binary format is not yet implemented. When requested, all binary operations transparently fall back to UTF-8-encoded JSON.

Basic round-trip serialization using default settings:

[ScyllaSerializable(version: 1)]
public class PlayerData
{
    [ScyllaProperty(Name = "name", Required = true)]
    public string Name { get; set; }

[ScyllaProperty(Name = "level")]
public int Level { get; set; }

[ScyllaIgnore]
public Texture2D CachedPortrait { get; set; }



}


// Serialize
var player = new PlayerData { Name = "Hero", Level = 42 };
var result = ScyllaSerialization.ToJSON(player);
if (result.IsSuccess)
Debug.Log(result.Value);


// Deserialize
var fromResult = ScyllaSerialization.FromJSON<PlayerData>(result.Value);
if (fromResult.IsSuccess)
Debug.Log(fromResult.Value.Name);

Methods

FromBytes<T>(byte[])

Deserializes an object of type T from a byte array using the default SerializationSettings.

Declaration
public static SerializationResult<T> FromBytes<T>(byte[] bytes)
Parameters
Type Name Description
byte[] bytes

The UTF-8-encoded byte array to deserialize. Must not be null or empty.
Returns
Type Description
SerializationResult<T>

A SerializationResult<T> containing the deserialized instance on success, or an error message on failure.
Type Parameters
Name Description
T

The target type to deserialize into.
See Also

FromBytes<T>(byte[], SerializationSettings)

Deserializes an object of type T from a byte array using the specified SerializationSettings.

Declaration
public static SerializationResult<T> FromBytes<T>(byte[] bytes, SerializationSettings settings)
Parameters
Type Name Description
byte[] bytes

The byte array to deserialize, encoded per settings: the tagged binary output of ScyllaBinaryWriter when Format is Binary, or UTF-8-encoded JSON otherwise. Must not be null or empty.
SerializationSettings settings

The settings governing this operation. Must not be null, and must specify the same Format the bytes were written with.
Returns
Type Description
SerializationResult<T>

A SerializationResult<T> containing the deserialized instance on success. On failure, the error message from the underlying deserialization step is propagated.
Type Parameters
Name Description
T

The target type to deserialize into.
Remarks

The binary path acquires a pooled ScyllaBinaryReader for the duration of the call and releases it in a finally block, the same pooling discipline FromJSON<T>(string, SerializationSettings) uses for its reader.

See Also

FromJSON<T>(string)

Deserializes an object of type T from a JSON string using the default SerializationSettings.

Declaration
public static SerializationResult<T> FromJSON<T>(string json)
Parameters
Type Name Description
string json

The JSON string to deserialize. Must not be null or empty; if it is, a failure result is returned immediately.
Returns
Type Description
SerializationResult<T>

A SerializationResult<T> containing the deserialized instance on success, or an error message on failure. No exception is propagated to the caller.
Type Parameters
Name Description
T

The target type to deserialize into. Must match the type that was used during serialization, or be a base type / interface when polymorphic type information ($type) is present in the JSON.
See Also

FromJSON<T>(string, SerializationSettings)

Deserializes an object of type T from a JSON string using the specified SerializationSettings.

Declaration
public static SerializationResult<T> FromJSON<T>(string json, SerializationSettings settings)
Parameters
Type Name Description
string json

The UTF-8 JSON string to parse. Must not be null or empty.
SerializationSettings settings

The settings governing this operation - custom serializers, reference handling, and depth limit. Must not be null.
Returns
Type Description
SerializationResult<T>

A SerializationResult<T> containing the deserialized instance on success, or an error message on failure. Both SerializationException and unexpected runtime exceptions are caught and reported as failures.
Type Parameters
Name Description
T

The target type to deserialize into. Must match the type used during serialization, or be a compatible base type when the JSON contains a $type discriminator.
Remarks

The method acquires a pooled ScyllaJSONReader for the duration of the call and releases it in a finally block, making concurrent calls safe.

A fresh ReferenceTracker is created per call. Reference IDs embedded in the JSON (via $id / $ref markers) are resolved within the scope of the single deserialization operation.

Schema migrations are applied automatically when the serialized $version is older than the current Version declared on the type. Migrations registered via RegisterMigration<T>(int, int, Func<T, T>) or via ScyllaMigrationAttribute on the type itself are applied sequentially step-by-step from the serialized version up to the current version.

See Also

GetMigration(Type, int, int)

Returns the migration function registered for type that upgrades instances from fromVersion to toVersion, or null if no such migration was registered.

Declaration
public static Func<object, object> GetMigration(Type type, int fromVersion, int toVersion)
Parameters
Type Name Description
Type type

The managed type whose migration registry is queried. Must not be null.
int fromVersion

The source schema version of the migration step.
int toVersion

The target schema version of the migration step.
Returns
Type Description
Func<object, object>

A Func<T, TResult> of object -> object that accepts an instance of the old schema and returns an upgraded instance, or null if no matching migration was found in the registry for the given type and version pair.
Remarks

This method exists for a future deserialization-pipeline integration and currently has no callers: ReflectionSerializer applies only ScyllaMigrationAttribute-decorated static methods discovered via TypeMetadata, not migrations registered through RegisterMigration<T>(int, int, Func<T, T>). See the remarks on that method.

See Also

RegisterMigration<T>(int, int, Func<T, T>)

Registers a schema migration function that upgrades an instance of type T from fromVersion to toVersion.

Declaration
public static void RegisterMigration<T>(int fromVersion, int toVersion, Func<T, T> migrator)
Parameters
Type Name Description
int fromVersion

The source schema version that this migration handles. Must be a positive integer and strictly less than toVersion.
int toVersion

The target schema version after this migration step. Must be strictly greater than fromVersion.
Func<T, T> migrator

A function that takes an instance deserialized from the old schema and returns the upgraded instance. The returned object may be the same reference (mutated) or a new instance. Must not be null.
Type Parameters
Name Description
T

The type whose schema is being migrated. Must match the type decorated with ScyllaSerializableAttribute.
Remarks

Migrations registered through this method are not currently consulted during deserialization. The only migrations the deserialize path applies are ScyllaMigrationAttribute-decorated static methods discovered on the type itself via TypeMetadata; GetMigration(Type, int, int), the lookup this method's registry exists to serve, has no callers anywhere in the framework. Declare migrations with ScyllaMigrationAttribute on the type instead. This method and its registry are kept as public API for a future runtime-registration path; calling it today has no observable effect on deserialization.

Migration functions are stored thread-safely in a ConcurrentDictionary<TKey, TValue> and can be registered at any point during application lifetime, even after the first serialization call.

Exceptions
Type Condition
ArgumentNullException

Thrown if migrator is null.
See Also

RegisterSerializer<T>(ITypeSerializer<T>)

Registers a custom type serializer globally for the type T, replacing any previously registered serializer for that type (including the built-in default serializers).

Declaration
public static void RegisterSerializer<T>(ITypeSerializer<T> serializer)
Parameters
Type Name Description
ITypeSerializer<T> serializer

The serializer instance that implements ITypeSerializer<T>. Must not be null.
Type Parameters
Name Description
T

The type for which the custom serializer will handle all read and write operations.
Remarks

The registration is global and thread-safe. Once registered, every subsequent call to ToJSON<T>(T) or FromJSON<T>(string) that encounters T will use this serializer.

To register a serializer only for a specific operation rather than globally, use RegisterSerializer<T>(ITypeSerializer<T>) on the settings object passed to the per-call overloads.

Exceptions
Type Condition
ArgumentNullException

Thrown if serializer is null.
See Also

ToBytes<T>(T)

Serializes an object of type T to a UTF-8 byte array using the default SerializationSettings.

Declaration
public static SerializationResult<byte[]> ToBytes<T>(T value)
Parameters
Type Name Description
T value

The object to serialize. May be null for reference types.
Returns
Type Description
SerializationResult<byte[]>

A SerializationResult<T> of byte[], encoded per the default Format (JSON, encoded as UTF-8). Returns a failure result if serialization fails.
Type Parameters
Name Description
T

The compile-time type of the object to serialize.
Remarks

Use ToJSON<T>(T) when a string is preferred, or pass explicit SerializationSettings with Binary via ToBytes<T>(T, SerializationSettings) for the tagged binary format.

See Also

ToBytes<T>(T, SerializationSettings)

Serializes an object of type T to a UTF-8 byte array using the specified SerializationSettings.

Declaration
public static SerializationResult<byte[]> ToBytes<T>(T value, SerializationSettings settings)
Parameters
Type Name Description
T value

The object to serialize. May be null for reference types.
SerializationSettings settings

The settings governing this operation. Must not be null.
Returns
Type Description
SerializationResult<byte[]>

A SerializationResult<T> of byte[]. On success, when Format is Binary the bytes are the tagged binary output produced by ScyllaBinaryWriter; otherwise they are the UTF-8 encoding of the JSON output produced by ToJSON<T>(T, SerializationSettings). On failure, the error message from the underlying serialization step is propagated.
Type Parameters
Name Description
T

The compile-time type of the object to serialize.
Remarks

The binary path acquires a pooled ScyllaBinaryWriter for the duration of the call and releases it in a finally block, the same pooling discipline ToJSON<T>(T, SerializationSettings) uses for its writer. A fresh ReferenceTracker is created per call.

Pass the result directly to FromBytes<T>(byte[], SerializationSettings) with a matching Format to round-trip; the two formats are not interchangeable on read.

See Also

ToJSON<T>(T)

Serializes an object of type T to a JSON string using the default SerializationSettings.

Declaration
public static SerializationResult<string> ToJSON<T>(T value)
Parameters
Type Name Description
T value

The object to serialize. May be null for reference types; a JSON null literal will be written in that case.
Returns
Type Description
SerializationResult<string>

A SerializationResult<T> of string. On success, Value contains the complete JSON output. On failure, ErrorMessage describes what went wrong; no exception is propagated to the caller.
Type Parameters
Name Description
T

The compile-time type of the object to serialize. This type is used for serializer lookup; if the runtime type differs (polymorphism), a $type marker is written and the value is serialized as its runtime type, regardless of IncludeTypeInfo.
Remarks

This overload uses Default which has PrettyPrint disabled and Preserve enabled. Use the settings overload for fine-grained control.

See Also

ToJSON<T>(T, SerializationSettings)

Serializes an object of type T to a JSON string using the specified SerializationSettings.

Declaration
public static SerializationResult<string> ToJSON<T>(T value, SerializationSettings settings)
Parameters
Type Name Description
T value

The object to serialize. May be null for reference types; a JSON null literal will be written in that case.
SerializationSettings settings

The settings governing this operation - format, pretty printing, null/default value handling, reference handling, depth limit, and custom serializers. Must not be null.
Returns
Type Description
SerializationResult<string>

A SerializationResult<T> of string. On success, Value contains the complete JSON text. On failure, ErrorMessage contains the reason; both SerializationException and unexpected exceptions are caught and returned as failures rather than thrown.
Type Parameters
Name Description
T

The compile-time type of the object to serialize. This type is used for serializer lookup and determines which properties are reflected.
Remarks

The method acquires a pooled ScyllaJSONWriter and StringBuilder for the duration of the call and releases them in a finally block, making it safe to call concurrently.

A fresh ReferenceTracker is created per call, so reference IDs always start from 1 and are scoped to the single serialization operation.

Exceptions
Type Condition
ArgumentNullException

Not thrown - returns a failure result instead.
See Also

See Also