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 UTF-8-encoded byte array to deserialize. The bytes are decoded to a string using UTF8 before parsing. Must not be null or empty.
SerializationSettings settings

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

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

The target type to deserialize into.
Remarks

When Format is Binary, the bytes are still interpreted as UTF-8 JSON because a dedicated binary reader is not yet implemented.

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 is intended for use by the deserialization pipeline (e.g. ReflectionSerializer) to look up registered migrations. Application code typically does not need to call this method directly; migrations are applied automatically during FromJSON<T>(string).

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 via this method supplement (or replace) those found by reflection via ScyllaMigrationAttribute. If both exist for the same version pair, the behaviour depends on which is discovered first by the ReflectionSerializer - prefer attribute-based migrations on the type itself and use this method only when the type cannot be modified.

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.

When deserializing a value whose serialized $version is older than the current type version, the engine applies all migration steps sequentially - for example, version 1 data going into a version 3 type runs the 1->2 migrator, then the 2->3 migrator. Gaps in the migration chain (e.g. missing 2->3 step) are silently skipped.

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[] containing the UTF-8 encoded JSON text. Returns a failure result if serialization fails.
Type Parameters
Name Description
T

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

Currently the binary format is not implemented; this method always produces UTF-8-encoded JSON regardless of the Format setting. Use ToJSON<T>(T) when a string is preferred.

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, the byte array is the UTF-8 encoding of the JSON output produced by ToJSON<T>(T, SerializationSettings). On failure, the error message from the inner JSON serialization is propagated.
Type Parameters
Name Description
T

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

When Format is Binary, the method currently falls back to JSON-as-bytes as the dedicated binary writer is not yet implemented.

The returned byte array is UTF-8 encoded with no byte-order mark (BOM). Pass it directly to FromBytes<T>(byte[], SerializationSettings) to round-trip.

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), type information will still be written when IncludeTypeInfo is enabled.
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