Skip to content

Game.CheckPrefabReferencesSystem

Assembly:
Namespace: Game.Serialization

Type: class

Base: GameSystemBase

Summary:
A Unity ECS system used during serialization to verify which prefab entities are referenced and to enable their PrefabData component accordingly. The system schedules a parallel job (CheckPrefabReferencesJob) that iterates over a NativeArray of prefabs and an UnsafeList marking referenced prefabs; if an element is marked referenced the job enables the PrefabData component for that prefab entity. The system manages job dependencies and the lifetime of the temporary UnsafeList used to track references. This type is intended to be used as part of the game's prefab serialization/load pipeline and relies on Unity's Job System and component lookups.

Fields

  • private Unity.Collections.NativeArray<Entity> m_PrefabArray
    Holds the array of prefab entities to check. Supplied via BeginPrefabCheck and consumed by the scheduled job. Cleared/reset by EndPrefabCheck.

  • private Unity.Collections.LowLevel.Unsafe.UnsafeList<bool> m_ReferencedPrefabs
    A temporary per-prefab boolean list indicating whether a prefab was referenced. Allocated in BeginPrefabCheck with Allocator.TempJob, resized to match the prefab array length and cleared. Accessed from the scheduled job and disposed in EndPrefabCheck using the combined dependencies.

  • private Unity.Jobs.JobHandle m_DataDeps
    Tracks data dependencies that must be satisfied before the check/scheduling. Provided into BeginPrefabCheck (dependencies parameter) and used to combine dependencies for scheduling and disposal.

  • private Unity.Jobs.JobHandle m_UserDeps
    Aggregates user-side job dependencies added by callers via AddPrefabReferencesUser. Combined with m_DataDeps and the system base dependency when scheduling the job.

  • private System.Boolean m_IsLoading
    Flag indicating whether the operation is part of a loading process. Passed into PrefabReferences returned by GetPrefabReferences, so callers can adapt behavior based on loading vs runtime.

Properties

This type exposes no public properties.

Constructors

  • public CheckPrefabReferencesSystem()
    Default constructor. Marked with [Preserve] (to avoid code stripping). No special initialization logic is performed in the constructor; the system's working state is set up when BeginPrefabCheck is called.

Methods

  • protected override void OnUpdate()
    Schedules the CheckPrefabReferencesJob as an IJobParallelFor. The job is constructed with:
  • m_PrefabArray: the prefab Entity array
  • m_PrefabData: a ComponentLookup obtained via GetComponentLookup()

  • m_ReferencedPrefabs: the UnsafeList marking referenced prefabs The job is scheduled with a batch size of 64 and JobHandle.CombineDependencies(m_DataDeps, m_UserDeps, base.Dependency). The resulting combined handle is stored into both m_DataDeps and m_UserDeps as well as base.Dependency, so the system's dependency tracks the scheduled work.

  • public void BeginPrefabCheck(NativeArray<Entity> array, bool isLoading, JobHandle dependencies)
    Initializes internal state for a prefab check run:

  • Stores the provided prefab entity array in m_PrefabArray.
  • Allocates m_ReferencedPrefabs as a new UnsafeList with Allocator.TempJob and resizes it to array.Length, cleared to false.
  • Stores the incoming dependencies into m_DataDeps.

  • Records isLoading into m_IsLoading. Call this before scheduling or otherwise using the system to indicate the set of prefabs to check.

  • public void EndPrefabCheck(out JobHandle dependencies)
    Finalizes a prefab check run:

  • Combines m_DataDeps and m_UserDeps into the out parameter dependencies.
  • Schedules disposal of m_ReferencedPrefabs using that combined dependencies (m_ReferencedPrefabs.Dispose(dependencies)).

  • Resets m_PrefabArray, m_ReferencedPrefabs, m_DataDeps, and m_UserDeps to their default values. This ensures the temporary UnsafeList is disposed only after all jobs that read it have completed.

  • public PrefabReferences GetPrefabReferences(SystemBase system, out JobHandle dependencies)
    Returns a PrefabReferences helper constructed from the current internal state:

  • Provides m_PrefabArray and m_ReferencedPrefabs.
  • Gets a read-only ComponentLookup from the provided system (system.GetComponentLookup(isReadOnly: true)).

  • Passes through m_IsLoading. Also sets the out parameter dependencies to m_DataDeps so callers can chain or synchronize on the same data dependencies.

  • public void AddPrefabReferencesUser(JobHandle dependencies)
    Combines an external user JobHandle into the internal m_UserDeps. Use this to register additional job dependencies that must be considered before disposing the temporary list or before scheduling the check job.

  • Nested job: private struct CheckPrefabReferencesJob : IJobParallelFor ([BurstCompile])
    Job fields:

  • [ReadOnly] NativeArray m_PrefabArray
  • [NativeDisableParallelForRestriction] ComponentLookup m_PrefabData
  • UnsafeList m_ReferencedPrefabs Job Execute(int index):
  • If m_ReferencedPrefabs[index] is true, calls m_PrefabData.SetComponentEnabled(m_PrefabArray[index], value: true) to enable the PrefabData component on that prefab entity, and writes false back to m_ReferencedPrefabs[index] (clearing the mark). Notes:
  • ComponentLookup is marked without parallel-for restriction; SetComponentEnabled is used to enable components from multiple threads.
  • The job runs in parallel over the prefab array; the batch size used when scheduling is 64.

Notes and safety considerations: - The system uses UnsafeList for a compact, indexable list usable inside jobs; because it's unsafe, it must be allocated with a job-capable allocator (Allocator.TempJob) and explicitly disposed with a JobHandle that ensures no jobs are still reading it. - BeginPrefabCheck must be called before scheduling the system (so the job has valid data) and EndPrefabCheck must be called to dispose temporary resources; otherwise memory leaks or race conditions may occur. - The scheduling pattern combines m_DataDeps, m_UserDeps, and base.Dependency so callers must manage dependencies correctly via AddPrefabReferencesUser and by passing dependencies into BeginPrefabCheck to avoid races.

Usage Example

// Example pattern for a serialization pipeline:

// Begin a prefab check pass (called from serialization code before scheduling dependent jobs)
var prefabArray = /* NativeArray<Entity> populated with prefab entities */;
JobHandle incomingDeps = /* any job handle that must complete first */;
checkPrefabReferencesSystem.BeginPrefabCheck(prefabArray, isLoading: true, incomingDeps);

// Allow other systems/jobs to add producer/user dependencies that also read/write the reference marks:
checkPrefabReferencesSystem.AddPrefabReferencesUser(otherJobHandle);

// Optionally obtain a PrefabReferences helper that callers can use to mark prefabs as referenced:
JobHandle depForUsers;
var prefabRefs = checkPrefabReferencesSystem.GetPrefabReferences(this /* SystemBase */, out depForUsers);
// pass prefabRefs into jobs that will mark entries in the UnsafeList

// The system's OnUpdate will schedule the CheckPrefabReferencesJob; when done, finalize:
checkPrefabReferencesSystem.EndPrefabCheck(out JobHandle finalDeps);

// Ensure finalDeps completes before freeing prefabArray if needed
finalDeps.Complete();
prefabArray.Dispose();

Notes: - The system's OnUpdate schedules a Burst-compiled IJobParallelFor that enables PrefabData on referenced prefabs and clears the reference flags. - Ensure you respect the dependency handles returned by GetPrefabReferences and EndPrefabCheck; UnsafeList is disposed using the combined dependencies so callers must not access it after scheduling unless they synchronize with those handles.