Class TypeMetadataCache

A global, thread-safe cache that stores TypeMetadata instances indexed by Type, and maintains a reverse mapping from type-alias strings to their corresponding runtime types.

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

This class is the central metadata registry for the Scylla serialization system. All serialization and deserialization paths obtain type metadata through GetMetadata(Type) or GetMetadata<T>(), ensuring that the expensive reflection work performed by TypeMetadata is done only once per type per application session.

Internally, both the type-to-metadata cache and the alias-to-type reverse index are backed by ConcurrentDictionary<TKey, TValue>. Read operations are lock-free. Write operations (first-time metadata creation) rely on GetOrAdd(TKey, Func<TKey, TValue>), which guarantees that at most one TypeMetadata is stored per type even under concurrent access - although the factory delegate may be called more than once on very rare occasions due to the non-atomic nature of GetOrAdd. Because TypeMetadata construction is idempotent, this is safe.

Call PreWarm(IEnumerable<Type>) during loading screens or application startup to front-load the reflection cost and avoid first-access latency spikes on hot paths.

Call Clear() to discard all cached metadata. This is mainly useful in editor hot-reload scenarios or in unit tests that need a clean slate between test runs.

Properties

Count

Gets the number of type metadata entries currently held in the cache.

Declaration
public static int Count { get; }
Property Value
Type Description
int

The count of distinct types for which TypeMetadata has been constructed and stored. Reflects the current snapshot count from the underlying ConcurrentDictionary<TKey, TValue>.

Methods

Clear()

Removes all entries from both the type-metadata cache and the alias reverse index, returning the cache to its initial empty state.

Declaration
public static void Clear()
Remarks

After this call, the next access to any type via GetMetadata(Type) will trigger a full metadata rebuild for that type. This method is primarily intended for use in unit tests and editor hot-reload scenarios. It should not be called during normal application runtime as it will cause performance regressions on the next serialization operations.

GetMetadata(Type)

Returns the cached TypeMetadata for the specified type, constructing and caching it on first access.

Declaration
public static TypeMetadata GetMetadata(Type type)
Parameters
Type Name Description
Type type

The runtime type whose metadata is required. Must not be null. May be any type - primitive, value type, reference type, generic, or abstract.
Returns
Type Description
TypeMetadata

The TypeMetadata instance for type. The same instance is returned on all subsequent calls for the same type within the application session (or until Clear() is called).
Exceptions
Type Condition
ArgumentNullException

Thrown if type is null.

GetMetadata<T>()

Returns the cached TypeMetadata for the type parameter T, constructing and caching it on first access.

Declaration
public static TypeMetadata GetMetadata<T>()
Returns
Type Description
TypeMetadata

The TypeMetadata instance for T. Equivalent to calling GetMetadata(Type) with typeof(T).
Type Parameters
Name Description
T

The type whose metadata is required. May be any type - primitive, value type, reference type, or generic.

IsCached(Type)

Determines whether TypeMetadata for the specified type is already present in the cache, without triggering metadata construction.

Declaration
public static bool IsCached(Type type)
Parameters
Type Name Description
Type type

The type to check. If null, returns false.
Returns
Type Description
bool

true if metadata for type has already been constructed and cached; false if the next call to GetMetadata(Type) would trigger a metadata rebuild.

PreWarm(IEnumerable<Type>)

Pre-populates the cache with TypeMetadata for a collection of types, triggering reflection and delegate compilation upfront rather than on first use.

Declaration
public static void PreWarm(IEnumerable<Type> types)
Parameters
Type Name Description
IEnumerable<Type> types

The collection of types to pre-cache. null entries within the sequence are silently skipped. If types itself is null, the call is a no-op.
Remarks

Call this method during loading screens or application initialization to amortize the one-time reflection cost of TypeMetadata construction across a period where frame-time latency is acceptable. This prevents first-access latency spikes during gameplay or time-critical serialization paths.

See Also

PreWarm(params Type[])

Pre-populates the cache with TypeMetadata for a variable-length list of types specified as a params array.

Declaration
public static void PreWarm(params Type[] types)
Parameters
Type Name Description
Type[] types

The types to pre-cache. Delegates to PreWarm(IEnumerable<Type>).
Remarks

Convenience overload for inline usage such as TypeMetadataCache.PreWarm(typeof(PlayerData), typeof(InventoryData));

See Also

RegisterAlias(string, Type)

Explicitly registers a mapping from an alias string to a runtime type in the alias index, enabling future resolution of that alias via ResolveAlias(string).

Declaration
public static void RegisterAlias(string alias, Type type)
Parameters
Type Name Description
string alias

The alias string to register. If null or empty, the call is silently ignored.
Type type

The runtime type to associate with alias. If null, the call is silently ignored. If alias is already registered, the existing mapping is preserved (the new type is not stored).
Remarks

This method is called automatically by CreateMetadata(Type) when a new TypeMetadata is created. It can also be called manually to pre-register aliases for types that have not yet been accessed through the cache, for example when deserializing data that references types in external assemblies.

See Also

ResolveAlias(string)

Resolves a type-alias string to the runtime Type it identifies, first checking the in-memory alias index and falling back to GetType(string) for fully-qualified assembly-qualified names.

Declaration
public static Type ResolveAlias(string alias)
Parameters
Type Name Description
string alias

The alias string to resolve. This is either a short alias declared via TypeAlias, or the fully-qualified type name (as returned by FullName) for types without an explicit alias. An empty or null value returns null.
Returns
Type Description
Type

The Type corresponding to alias if it is found in the alias index or resolvable via GetType(string); otherwise, null. When resolved via GetType(string), the result is automatically registered in the alias index for future lookups.
See Also

See Also