ObjectReferences

Serializes members typed as a Node, Component or DataAsset (or a list or array of them) as references — {"$ref": "<id>"} — instead of inline copies, and resolves them after load.

Remarks

Scene objects are resolved against the loaded scenes; DataAssets through an IAssetLoader, batch-loaded in parallel. An id whose target is missing is kept and written back, so saving never drops it, and resolves when its target loads. A destroyed target is written as null. SerializeInlineAttribute opts a member out.

Fields

RefProperty (string) = "$ref": Property name of a serialized reference.

Public Methods

IsReferenceMember

public static bool IsReferenceMember(Type memberType, bool allowSceneObjects)

Whether a member of memberType is serialized as a reference.

Parameters:

  • memberType (Type): The declared member type.
  • allowSceneObjects (bool): Whether nodes and components count; only components may reference them.

Returns: bool

  • True for a referenceable type or a list or array of one.

IsSavedAsReference

public static bool IsSavedAsReference(MemberInfo member, Type memberType, bool allowSceneObjects)

Whether member is saved as a reference: a reference member without SerializeInlineAttribute.

Parameters:

  • member (MemberInfo): The field or property.
  • memberType (Type): Its declared type.
  • allowSceneObjects (bool): Whether nodes and components are references (only on components).

Returns: bool

  • True when the member is written with TryWrite.

IsMissing

public static bool IsMissing(object? target)

Whether target is null or a destroyed node or component.

Parameters:

  • target (object?): The referenced object.

Returns: bool

  • True when the reference should be treated as empty.

TryGetUnresolved

public static bool TryGetUnresolved(IdClass owner, string member, Guid[] ids)

The member ids read from data whose targets are not resolved yet.

Parameters:

  • owner (IdClass): The object holding the member.
  • member (string): The member name.
  • ids (Guid[]): The pending ids; Empty marks an element that needs none.

Returns: bool

  • True when the member has pending ids.

Forget

public static void Forget(IdClass owner, string member)

Drops pending ids for a member, so a value assigned by the user (including null) is what gets saved.

Parameters:

  • owner (IdClass): The object holding the member.
  • member (string): The member name.

Forget

public static void Forget(IdClass owner, string member, int index)

Drops the pending id of one element of a list or array member.

Parameters:

  • owner (IdClass): The object holding the member.
  • member (string): The list or array member name.
  • index (int): The element index.

Resolve

public static int Resolve(Node root, IAssetLoader? loader)

Resolves pending references on every component in root's hierarchy.

Parameters:

  • root (Node): The hierarchy that scene references resolve against.
  • loader (IAssetLoader?): Resolves DataAsset references; null leaves them pending.

Returns: int

  • How many references are still pending.

Resolve

public static int Resolve(IEnumerable<Node> roots, IAssetLoader? loader)

Resolves pending references on every component in the given hierarchies, against all of them, so a reference into another loaded scene resolves once that scene is loaded too.

Parameters:

  • roots (IEnumerable): The loaded hierarchies.
  • loader (IAssetLoader?): Resolves DataAsset references; null leaves them pending.

Returns: int

  • How many references are still pending.

ResolveAsync

public static async Task ResolveAsync(DataAsset data, IAssetLoader loader)

Resolves pending DataAsset references held by a DataAsset, loading the referenced assets in parallel first.

Parameters:

  • data (DataAsset): The DataAsset whose members are resolved.
  • loader (IAssetLoader): Resolves the referenced DataAssets.

Returns: Task

  • A task that completes when the references are assigned.

TryWrite

public static bool TryWrite(Utf8JsonWriter writer, IdClass owner, string member, Type memberType, object? value, bool allowSceneObjects)

Writes a reference member as {"$ref": id} (or an array of them), keeping pending ids for targets that are not loaded. Returns false, writing nothing, when the member is not a reference member.

Parameters:

  • writer (Utf8JsonWriter): The JSON writer, inside the owner's object.
  • owner (IdClass): The object holding the member.
  • member (string): The member name.
  • memberType (Type): The declared member type.
  • value (object?): The member value.
  • allowSceneObjects (bool): Whether nodes and components are references (only on components).

Returns: bool

  • True when the member was written.

TryRead

public static bool TryRead(IdClass owner, string member, Type memberType, JsonElement json, bool allowSceneObjects, object? value)

Reads a reference member written by TryWrite, recording its ids to resolve later. Returns false for a member that is not a reference member or JSON in another form (an inline value from older files).

Parameters:

  • owner (IdClass): The object holding the member.
  • member (string): The member name.
  • memberType (Type): The declared member type.
  • json (JsonElement): The member's JSON value.
  • allowSceneObjects (bool): Whether nodes and components are references (only on components).
  • value (object?): The value to assign now: null, or a list of nulls to be filled in.

Returns: bool

  • True when the member was read.