Skip to content

Game.Routes.ReferencesSystem

Assembly: Assembly-CSharp (game code)
Namespace: Game.Routes

Type: class

Base: GameSystemBase

Summary:
ReferencesSystem is an ECS system responsible for keeping route-related entity references in sync. It scans route entities (entities with Route, RouteWaypoint and RouteSegment buffers) and: - Updates Owner components on waypoint and segment entities so they reference the parent route entity. - Maintains SubRoute buffers on owner entities (adds/removes SubRoute entries when routes are created/deleted or when a route's Temp state changes). - Removes SubRoute entries when a route is deleted. The system uses a Burst-compiled IJob (UpdateRouteReferencesJob) operating over archetype chunks produced asynchronously, and it uses ComponentLookup/BufferLookup handles to read/write component and buffer data.

Fields

  • private EntityQuery m_RouteQuery
    Holds the EntityQuery used to find route entities. The query selects entities that have Route, RouteWaypoint and RouteSegment buffer types and that have either Created or Deleted tags. This query is required for the system to run (RequireForUpdate is called in OnCreate).

  • private TypeHandle __TypeHandle
    A compiler-generated struct that caches all the Entity/Component/Buffer type handles and ComponentLookup/BufferLookup instances used by the job and system. The handles are assigned in __AssignHandles and then converted to runtime handles in OnUpdate via InternalCompilerInterface helper calls.

Properties

  • (none)
    This system does not expose public properties.

Constructors

  • public ReferencesSystem()
    Default public constructor. Marked with [Preserve] to avoid being stripped by linking. Initialization of query and type handles happens in OnCreate / OnCreateForCompiler rather than in the constructor.

Methods

  • protected override void OnCreate()
    Initializes the m_RouteQuery. The query requires:
  • All: Route, RouteWaypoint (buffer), RouteSegment (buffer)

  • Any: Created or Deleted After creating the query, RequireForUpdate(m_RouteQuery) is called so the system only runs when matching entities exist.

  • protected override void OnUpdate()
    Main update logic:

  • Builds an archetype chunk list for the route query asynchronously (ToArchetypeChunkListAsync).
  • Constructs and schedules a Burst-compiled IJob (UpdateRouteReferencesJob) that operates over the chunk list. The job is supplied with entity/buffer/component handles obtained from the compiler-generated __TypeHandle via InternalCompilerInterface.Get* helpers and base.CheckedStateRef.
  • Disposes of the chunk list when the scheduled job completes.

  • Updates base.Dependency with the job handle.

  • protected override void OnCreateForCompiler()
    Compiler-oriented initialization: calls __AssignQueries and assigns the cached type handles by calling __TypeHandle.__AssignHandles with the system state reference (base.CheckedStateRef). This method is part of the generated plumbing that helps the job obtain handles safely.

  • private void __AssignQueries(ref SystemState state)
    Empty / compiler-generated place-holder for query assignment. In this class it simply constructs and disposes of an EntityQueryBuilder. Present to satisfy generated code patterns.

Nested types and important inner logic:

  • UpdateRouteReferencesJob : IJob (private, [BurstCompile])
  • Purpose: Iterate over route archetype chunks and update references and owner tracking.
  • Inputs:
    • m_RouteChunks (NativeList) — the chunk list to process.
    • EntityTypeHandle, BufferTypeHandle, BufferTypeHandle, ComponentTypeHandle, ComponentTypeHandle
    • ComponentLookup m_TempData (read-only)
    • ComponentLookup m_OwnerData (read/write)
    • BufferLookup m_SubRoutes (read/write)
  • Behavior:
    • For each chunk, get the entity array and buffer accessors.
    • If the chunk has Deleted component, remove SubRoute(entity) entries from the owner entity's SubRoute buffer for each route entity in the chunk.
    • Otherwise, for each route entity:
    • Iterate RouteWaypoint buffer, set the Owner component on each waypoint entity to reference the route entity.
    • Iterate RouteSegment buffer, set the Owner component on each non-null segment entity to reference the route entity.
    • If the route entity has an Owner component and the owner's Temp state equals the route's Temp flag presence, attempt to add a SubRoute entry for the route entity into the owner's SubRoute buffer (using CollectionUtils.TryAddUniqueValue to avoid duplicates).

  • Notes:

    • Uses CollectionUtils.RemoveValue / TryAddUniqueValue to manage SubRoute buffers.
    • The job relies on TryGetComponent and HasComponent calls on ComponentLookup and BufferLookup to safely access owner buffers.

  • TypeHandle (private struct)

  • Contains cached type handles and lookups:
    • EntityTypeHandle
    • BufferTypeHandle (read-only)
    • BufferTypeHandle (read-only)
    • ComponentTypeHandle (read-only)
    • ComponentTypeHandle (read-only)
    • ComponentLookup (read-only)
    • ComponentLookup (read/write)
    • BufferLookup (read/write)
  • Method: __AssignHandles(ref SystemState state) — called to initialize the type handles from the provided SystemState.

Attributes present: - [BurstCompile] on the UpdateRouteReferencesJob to enable Burst-compiled execution. - [Preserve] on OnCreate, OnUpdate and constructor to avoid stripping by build/linker.

Usage Example

// This system is created and used by the ECS runtime. Example pseudocode showing
// the same setup performed in the system's OnCreate/OnUpdate methods:

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();

    // Query routes with waypoints & segments, run only when created/deleted exist
    m_RouteQuery = GetEntityQuery(new EntityQueryDesc
    {
        All = new ComponentType[]
        {
            ComponentType.ReadOnly<Route>(),
            ComponentType.ReadOnly<RouteWaypoint>(),
            ComponentType.ReadOnly<RouteSegment>()
        },
        Any = new ComponentType[]
        {
            ComponentType.ReadOnly<Created>(),
            ComponentType.ReadOnly<Deleted>()
        }
    });

    RequireForUpdate(m_RouteQuery);
}

[Preserve]
protected override void OnUpdate()
{
    // Build chunk list asynchronously and schedule the Burst job to update owner references
    JobHandle queryHandle;
    var routeChunks = m_RouteQuery.ToArchetypeChunkListAsync(Allocator.TempJob, out queryHandle);

    var job = new UpdateRouteReferencesJob
    {
        m_RouteChunks = routeChunks,
        // job handles are filled via InternalCompilerInterface.Get* in the real system
        // (compiler-generated plumbing ensures correct handles from __TypeHandle)
    };

    JobHandle jobHandle = IJobExtensions.Schedule(job, JobHandle.CombineDependencies(queryHandle, base.Dependency));
    routeChunks.Dispose(jobHandle);
    base.Dependency = jobHandle;
}

Notes for modders: - This system is compiler-generated style code that relies on internal runtime helpers (InternalCompilerInterface) and compiler-generated handle caching. When creating or modifying systems that use chunked iteration and jobs, ensure correct use of ComponentLookup / BufferLookup and conversion of cached handles to runtime handles before scheduling jobs. - The system updates Owner components directly; code that relies on owner relationships should respect the system's update timing and job dependencies to avoid race conditions.