Game.Serialization.SecondaryPrefabReferencesSystem

Assembly: Game (managed runtime assembly used by the game)
Namespace: Game.Serialization

Type: public class

Base: GameSystemBase

Summary:
This system ensures that entity components which hold references to prefabs have those references validated and, if necessary, fixed/updated after serialization or content changes. It works by acquiring a PrefabReferences helper from CheckPrefabReferencesSystem and scheduling several Burst-compiled IJobChunk jobs in parallel. Each job iterates relevant chunks and calls PrefabReferences.Check(ref entity) on specific Entity fields contained in component types such as SpawnableBuildingData, PlaceholderBuildingData, ServiceObjectData, NetLaneData, TransportLineData and ContentPrerequisiteData. The system coordinates job dependencies and registers itself as a user of the CheckPrefabReferencesSystem so prefab reference state is tracked correctly.

---

Fields

• private CheckPrefabReferencesSystem m_CheckPrefabReferencesSystem
  This holds a reference to the CheckPrefabReferencesSystem managed system. It's used to obtain the PrefabReferences structure (and associated job dependencies) which provides the Check(ref Entity) API for validating/fixing prefab entity references.

• private EntityQuery m_SpawnableBuildingQuery
  Used to select entities with SpawnableBuildingData and PrefabData (excluding Deleted) so the corresponding job can run only on relevant entities.

• private EntityQuery m_PlaceholderBuildingQuery
  Query for entities with PlaceholderBuildingData & PrefabData (excluding Deleted) used by the placeholder-building job.

• private EntityQuery m_ServiceObjectQuery
  Query for entities with ServiceObjectData & PrefabData (excluding Deleted) used by the service-object job.

• private EntityQuery m_NetLaneQuery
  Query for entities with NetLaneData & PrefabData (excluding Deleted) used by the net-lane job.

• private EntityQuery m_TransportLineQuery
  Query for entities with TransportLineData & PrefabData (excluding Deleted) used by the transport-line job.

• private EntityQuery m_ContentPrerequisiteQuery
  Query for entities with ContentPrerequisiteData & PrefabData (excluding Deleted) used by the content-prerequisite job.

• private TypeHandle __TypeHandle
  Holds component type handles for the component types processed by the system. These are assigned via __AssignHandles to produce ComponentTypeHandle instances used by the jobs (and retrieved through InternalCompilerInterface.GetComponentTypeHandle in OnUpdate).

Properties

• None (the system does not expose public properties).
  This system is purely internal for serialization/fixup work and exposes no public properties.

Constructors

• public SecondaryPrefabReferencesSystem()
  Default parameterless constructor. The system relies on the ECS lifecycle methods (OnCreate/OnUpdate) for initialization and operation; the constructor does not perform additional setup.

Methods

• protected override void OnCreate()
  Called once when the system is created. The method:
• Calls base.OnCreate().
• Obtains the CheckPrefabReferencesSystem via World.GetOrCreateSystemManaged() and stores it in m_CheckPrefabReferencesSystem.

• Initializes EntityQuery instances for the relevant component sets (SpawnableBuildingData, PlaceholderBuildingData, ServiceObjectData, NetLaneData, TransportLineData, ContentPrerequisiteData), each requiring PrefabData and excluding Deleted entities. This prepares the system to schedule the jobs that will validate prefab references.

• protected override void OnUpdate()
  Main runtime logic. The method:

• Obtains a PrefabReferences struct and an initial JobHandle dependency from m_CheckPrefabReferencesSystem.GetPrefabReferences(this, out dependencies).
• Combines that dependency with the system's current dependency.
• Constructs six Burst-compiled IJobChunk job structs (FixSpawnableBuildingJob, FixPlaceholderBuildingJob, FixServiceObjectDataJob, FixNetLaneDataJob, FixTransportLineDataJob, FixContentPrerequisiteDataJob). Each job is provided a ComponentTypeHandle fetched via InternalCompilerInterface.GetComponentTypeHandle and the shared PrefabReferences instance.
• Schedules each job in parallel over the corresponding EntityQuery and combines all resulting JobHandles into a single dependency.

• Calls m_CheckPrefabReferencesSystem.AddPrefabReferencesUser(dependencies) to let the CheckPrefabReferencesSystem track that this system is using the prefab references, and sets base.Dependency to the combined dependency. This method is where chunked iteration jobs are scheduled to validate/fix entity prefab references in parallel.

• protected override void OnCreateForCompiler()
  Called by generated/compiled infrastructure to perform additional assignment needed by the compiler-time generated code. It:

• Calls base.OnCreateForCompiler().
• Calls __AssignQueries(ref base.CheckedStateRef) to ensure queries are assigned (the implementation here merely creates and disposes a temporary EntityQueryBuilder).

• Calls __TypeHandle.__AssignHandles(ref base.CheckedStateRef) to populate the ComponentTypeHandle fields stored in __TypeHandle.

• private void __AssignQueries(ref SystemState state)
  Internal helper used by OnCreateForCompiler. In this class the method only creates and disposes an EntityQueryBuilder(Allocator.Temp) — the real query initialization happens in OnCreate. This method exists to satisfy compiler-generated expectations when converting source to system code.

• (Nested job structs) FixSpawnableBuildingJob, FixPlaceholderBuildingJob, FixServiceObjectDataJob, FixNetLaneDataJob, FixTransportLineDataJob, FixContentPrerequisiteDataJob — each implements IJobChunk and is Burst-compiled.
  Each job:

• Holds a ComponentTypeHandle for its component type and a PrefabReferences instance.
• Iterates the chunk's native array for that component type using a ChunkEntityEnumerator (to respect enabled masks when applicable).
• For each element, inspects a specific Entity field (for example, SpawnableBuildingData.m_ZonePrefab, ServiceObjectData.m_Service, NetLaneData.m_PathfindPrefab, etc.). If the Entity field is not Entity.Null it calls m_PrefabReferences.Check(ref entityField) to validate/fix it.

• Writes the potentially-updated component value back into the native array.

• (Nested TypeHandle struct) public void __AssignHandles(ref SystemState state)
  Assigns the ComponentTypeHandle fields using state.GetComponentTypeHandle(). This prepares the raw handles that will be converted to runtime handles (via InternalCompilerInterface.GetComponentTypeHandle) when scheduling jobs in OnUpdate.

Notes: - Jobs use PrefabReferences (a value-type helper) passed by value; PrefabReferences.Check is invoked with ref to the Entity field so Check can update the reference if required. - Jobs are Burst-compiled and scheduled via JobChunkExtensions.ScheduleParallel for scalability. - The system ensures proper dependency chaining with CheckPrefabReferencesSystem so that prefab reference state remains consistent across multiple systems.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // The system implementation gets the CheckPrefabReferencesSystem and builds queries here.
    m_CheckPrefabReferencesSystem = World.GetOrCreateSystemManaged<CheckPrefabReferencesSystem>();
    m_SpawnableBuildingQuery = GetEntityQuery(ComponentType.ReadOnly<SpawnableBuildingData>(), ComponentType.ReadOnly<PrefabData>(), ComponentType.Exclude<Deleted>());
    // ... other queries initialized similarly
}

Additional example (what the system schedules each frame):

[Preserve]
protected override void OnUpdate()
{
    JobHandle dependencies;
    PrefabReferences prefabReferences = m_CheckPrefabReferencesSystem.GetPrefabReferences(this, out dependencies);
    dependencies = JobHandle.CombineDependencies(base.Dependency, dependencies);

    var job = new FixSpawnableBuildingJob {
        m_SpawnableBuildingType = InternalCompilerInterface.GetComponentTypeHandle(ref __TypeHandle.__Game_Prefabs_SpawnableBuildingData_RW_ComponentTypeHandle, ref base.CheckedStateRef),
        m_PrefabReferences = prefabReferences
    };

    JobHandle jobHandle = JobChunkExtensions.ScheduleParallel(job, m_SpawnableBuildingQuery, dependencies);
    // other jobs schedule similarly...
    dependencies = JobUtils.CombineDependencies(jobHandle, /* other job handles */);
    m_CheckPrefabReferencesSystem.AddPrefabReferencesUser(dependencies);
    base.Dependency = dependencies;
}

This system is intended for internal runtime/serialization use inside the game's ECS; when modding, be aware that it fixes up entity references to prefabs after content loads/changes — interfering with or replacing this flow may cause prefab/entity mismatches.