Game.Serialization.PrefabReferences
Assembly:
{{ Likely part of the game's runtime/assembly that contains Game.* code (e.g., the main Game assembly). If you need the exact assembly name, check the compiled DLL that contains the Game.Serialization namespace in your project. }}
Namespace: Game.Serialization
Type: struct
Base: System.ValueType
Summary:
PrefabReferences is a lightweight, value-type helper used during serialization/deserialization to translate and track prefab Entity references. It maintains a small cache of the last input/output prefab to avoid repeated lookups and uses a per-prefab boolean list to mark which prefab indices are referenced. It supports two modes controlled by the isLoading flag: a loading mode (translating indices from a stored array into runtime Entities) and a non-loading mode (marking referenced prefabs directly). The struct relies on PrefabData (Game.Prefabs.PrefabData), a NativeArray
Fields
-
private ComponentLookup<PrefabData> m_PrefabData
ReadOnly lookup used to access PrefabData components for a given prefab Entity. Used to read the prefab's m_Index value. In job contexts this field is annotated with [ReadOnly] in the source to indicate no writes. -
private NativeArray<Entity> m_PrefabArray
Array of prefab Entities used when loading (maps stored indices to actual Entities). When isLoading is true, indices from PrefabData are resolved against this array. -
private UnsafeList<bool> m_ReferencedPrefabs
UnsafeList used as a bit/boolean list indicating which prefab indices have been referenced. Entries are set true when a prefab is referenced so caller can know which prefab resources are used. Because this is an UnsafeList, ensure proper lifetime and safety when using across jobs/threads. -
private Entity m_LastPrefabIn
Cache of the last input prefab Entity passed to Check/SetDirty to avoid repeated work when the same prefab appears consecutively. -
private Entity m_LastPrefabOut
Cache of the last resolved/output prefab Entity corresponding to m_LastPrefabIn. When loading, this is the prefab returned from m_PrefabArray at the resolved index; otherwise it's the same as input. -
private bool m_IsLoading
Mode flag: if true, the struct is operating in "loading" mode (translate indices from stored array into runtime Entities); if false, it operates in normal runtime mode (mark references directly).
Properties
- None. (This type exposes only fields, constructor and methods.)
Constructors
-
public PrefabReferences(NativeArray<Entity> prefabArray, UnsafeList<bool> referencedPrefabs, ComponentLookup<PrefabData> prefabData, bool isLoading)
Initializes the PrefabReferences helper. -
prefabArray: NativeArray
mapping stored prefab indices to runtime Entities (used when isLoading == true). - referencedPrefabs: UnsafeList
used to mark which prefab indices were referenced during the (de)serialization pass. - prefabData: ComponentLookup
used to read/modify PrefabData components (specifically m_Index). - isLoading: true when deserializing/loading (resolve indices -> Entities), false when in normal runtime use (just mark references).
- Initializes internal caches (m_LastPrefabIn/m_LastPrefabOut to Entity.Null).
Usage notes: Ensure prefabArray and referencedPrefabs lifetimes outlive this struct usage. ComponentLookup must be valid for the EntityManager/World context where used.
Methods
public void SetDirty(Entity prefab)
Marks the prefab as referenced (sets the boolean at the prefab's index in m_ReferencedPrefabs to true) unless in loading mode.
Behavior details: - If m_IsLoading is true, this method does nothing (references should be handled by Check during loading). - Reads PrefabData for the provided prefab Entity via m_PrefabData[prefab]. - If prefabData.m_Index >= 0, sets m_ReferencedPrefabs[prefabData.m_Index] = true. - Does not change m_LastPrefabIn/m_LastPrefabOut (no caching here). - Note: PrefabData is read-only; this method assumes the m_Index is meaningful in the current runtime context.
public void Check(ref Entity prefab)
Input: a prefab Entity passed by reference. Ensures the referenced prefab is translated/validated and marks the referenced index.
Behavior details: - If the incoming prefab equals m_LastPrefabIn, it simply assigns prefab = m_LastPrefabOut and returns (cache hit). - Otherwise reads PrefabData for the input prefab (using m_PrefabData[prefab]). - Resolves an index adjustment when prefabData.m_Index is negative: componentData.m_Index = math.select(componentData.m_Index, m_ReferencedPrefabs.Length + componentData.m_Index, componentData.m_Index < 0). This transforms a negative stored index into a positive index relative to the referenced list length (this pattern is used to encode offsets during serialization). - Sets m_LastPrefabIn to the incoming prefab. - If m_IsLoading is true: - Looks up m_LastPrefabOut = m_PrefabArray[prefabData.m_Index]. - If the resolved output equals the input (m_LastPrefabOut == m_LastPrefabIn), marks m_ReferencedPrefabs[prefabData.m_Index] = true. - Finally sets the ref prefab to m_LastPrefabOut. - If m_IsLoading is false: - Sets m_LastPrefabOut = prefab (no translation) and marks the index true in m_ReferencedPrefabs. - Sets the ref prefab to the same entity (m_LastPrefabOut).
Purpose: Use this when deserializing or validating references so that stored indices are translated to runtime Entities and referenced indices are recorded.
public Entity Check(EntityManager entityManager, Entity prefab)
Similar to the ref overload but operates using the provided EntityManager to read/write component data (useful when you cannot use ComponentLookup). Returns the resolved output Entity.
Behavior details:
- If prefab == Entity.Null: returns Entity.Null immediately.
- If m_IsLoading is true and entityManager.HasComponent
Notes:
- This method mutates no component on the entity manager; it reads PrefabData. When using entityManager.GetComponentData
Usage Example
// Example: creating and using a PrefabReferences helper during a serialization pass.
// Assume prefabArray, referencedPrefabs, and prefabData are prepared earlier.
var prefabRefs = new PrefabReferences(prefabArray, referencedPrefabs, prefabData, isLoading: true);
// Example of resolving a prefab reference by ref:
Entity prefabEntity = somePrefabEntityFromStream;
prefabRefs.Check(ref prefabEntity); // prefabEntity is now translated to the runtime prefab from prefabArray (or unchanged if not needed)
// The referenced index will be marked in referencedPrefabs as appropriate.
// Example of marking a prefab as referenced during runtime (non-loading):
var runtimePrefabRefs = new PrefabReferences(prefabArray, referencedPrefabs, prefabData, isLoading: false);
runtimePrefabRefs.SetDirty(prefabEntity); // marks the corresponding index in referencedPrefabs = true
// Example using EntityManager overload:
Entity resolved = prefabRefs.Check(entityManager, prefabEntity);
Additional notes and warnings:
- PrefabReferences uses UnsafeList