Skip to content

Game.ApplyRoutesSystem

Assembly:
Namespace: Game.Tools

Type: class

Base: GameSystemBase

Summary:
ApplyRoutesSystem is a DOTS ECS system used by the routing/tool pipeline to "apply" temporary route edits (entities with a Temp component) to their original route entities. It processes Temp entities that represent edits to routes, waypoints, segments and path data and performs create, update and delete operations on the corresponding original entities. The system runs two Burst-compiled IJobChunk jobs:

  • PatchTempReferencesJob: Ensures ConnectedRoute buffers are updated when a waypoint's connected grouping changes (patches references from temp -> original connected groups).
  • HandleTempEntitiesJob: The main worker that inspects Temp entities and either creates (commits) a temp entity to become permanent, updates the original entity with data from a temp, or marks entities as Deleted. It also emits PathTargetMoved events and adjusts components like Position, Connected, RouteInfo, Owner, Hidden and timing/metadata.

The system uses a ToolOutputBarrier and an EntityCommandBuffer.ParallelWriter to enqueue structural and component changes safely from jobs. It requires the Temp query (entities carrying Temp and one of Route/Waypoint/Segment) to run.

Fields

  • private ToolOutputBarrier m_ToolOutputBarrier
    Used to obtain an EntityCommandBuffer.ParallelWriter for safely applying structural/component changes produced by the scheduled jobs. The barrier also tracks job handles produced by the system.

  • private EntityQuery m_TempQuery
    Query that selects entities with a Temp component and at least one of Route, Waypoint or Segment. The system is scheduled only when this query has matching entities (RequireForUpdate in OnCreate).

  • private EntityArchetype m_PathTargetEventArchetype
    Archetype used to create PathTargetMoved events (Event + PathTargetMoved components) when a route target position has moved.

  • private ComponentTypeSet m_AppliedTypes
    A set of component types (Applied, Created, Updated) that is applied to a temp entity when it is committed (Create method removes Temp and adds this set).

  • private TypeHandle __TypeHandle
    Internal container that stores all ComponentTypeHandle/BufferTypeHandle/ComponentLookup/BufferLookup and the EntityTypeHandle used by the two jobs. It provides a method to assign handles from the SystemState.

  • private struct PatchTempReferencesJob (nested)
    Burst-compiled IJobChunk that iterates Waypoint chunks and patches ConnectedRoute buffers to reflect changed connectivity when a Temp points to a different Connected entity than its original.

  • private struct HandleTempEntitiesJob (nested)
    Burst-compiled IJobChunk that performs the bulk of apply logic. It handles chunks containing Waypoint, Segment, RouteWaypoint/RouteSegment buffers, Path element buffers or generic Temp-containing chunks. It performs Delete/Update/Create operations, copies buffer/component data back to the original entity, emits PathTargetMoved events when positions change, manages Owner/Hidden/Deleted/Updated flags, and uses NativeParallelHashMap to detect references to temp -> original mapping when copying buffers. Uses EntityCommandBuffer.ParallelWriter for all writes.

  • private struct TypeHandle (nested)
    A struct holding all required handles and lookups for job scheduling (EntityTypeHandle, ComponentTypeHandle, BufferTypeHandle, ComponentLookup, BufferLookup, etc.). It has a method __AssignHandles to fetch the appropriate handles from the SystemState.

Properties

  • (none)

Constructors

  • public ApplyRoutesSystem()
    Default constructor (preserved). The system sets up its runtime behavior in OnCreate and OnCreateForCompiler.

Methods

  • protected override void OnCreate()
    Initializes the system: obtains the ToolOutputBarrier, builds the m_TempQuery (Temp + any of Route/Waypoint/Segment), creates the m_PathTargetEventArchetype (Event + PathTargetMoved), initializes the m_AppliedTypes (Applied, Created, Updated), and calls RequireForUpdate(m_TempQuery) so the system only runs when there are Temp entities to process.

  • protected override void OnUpdate()
    Prepares and schedules the two jobs:

  • Builds PatchTempReferencesJob with EntityTypeHandle, Temp/Waypoint component handles and lookup/buffer lookup for ConnectedRoute buffers and Connected component lookup.
  • Builds HandleTempEntitiesJob with all required component type handles, buffer/lookup handles, archetype and ComponentTypeSet, and a parallel EntityCommandBuffer from m_ToolOutputBarrier.

  • Schedules PatchTempReferencesJob (Schedule) and HandleTempEntitiesJob (ScheduleParallel) against m_TempQuery, combines dependencies and registers the producer handle with the ToolOutputBarrier.

  • protected override void OnCreateForCompiler()
    Called by generated/compiled code path to assign queries and prepare type handles for the compiler-time environment. Calls __AssignQueries and __TypeHandle.__AssignHandles.

  • private void __AssignQueries(ref SystemState state)
    Internal helper used for compiler integration (no runtime query population beyond the temp EntityQuery created in OnCreate).

  • private void __AssignHandles(ref SystemState state) (on TypeHandle)
    Assigns and caches all required Entity/Component/Buffer type handles and lookups from the provided SystemState.

  • private void PatchTempReferencesJob.Execute(...) (IJobChunk)
    For each Waypoint in the chunk, if the Temp references an original entity, compares the Connected group of the waypoint entity vs the original. If they differ, removes the ConnectedRoute entry from the old connected group's buffer and attempts to add it to the new connected group's buffer (using CollectionUtils helpers).

  • private void HandleTempEntitiesJob.Execute(...) (IJobChunk)
    Handles chunk-specific processing:

  • If chunk contains Waypoint entries: update or create original waypoint entities, handle position changes and Connected updates, emit PathTargetMoved events where necessary, remove Hidden and mark originals as Updated.
  • If chunk contains Segment entries: copy PathTargets, PathInformation and PathElement buffers back to the original when present, update the original Segment component.
  • If chunk contains RouteWaypoint/RouteSegment buffers: update/copy buffers back to original, remap waypoint/segment references from temp to original (or set Owner for new standalone waypoint/segment), and delete stale child waypoint/segment entities no longer present.
  • For generic temp-containing chunks: either mark deleted or update original and remove Temp, adding Applied/Created/Updated as appropriate.
  • Uses helper methods: Delete, Update, UpdateComponent, CopyToOriginal, UpdatePathInfo, CopyToOriginal (for buffers), Create (commits a temp to permanent), etc.

Notes / important behaviors: - When copying buffers that reference other entities, the job checks the Temp mapping so it can remap buffer elements from temporary entity references to their original entity references. If a referenced child element has no original (i.e., a new child), it sets an Owner component on that child pointing to the committed original parent. - Deleted/Updated/Created/Applied markers are used to coordinate downstream systems and to clean up temporary entities. - All structural/component changes inside jobs are done via the parallel EntityCommandBuffer produced by ToolOutputBarrier to be safe with multithreading/Burst.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // The system sets up its Temp query, path target event archetype, and required applied types.
    // No additional setup is normally required for modders; the system will run automatically
    // when Temp entities are present (RequireForUpdate(m_TempQuery)).
}

If you are creating temp edits in your mod/tool: - Create entities with the Temp component and the edited components (Waypoint/Segment/Route/Position/etc). - The ApplyRoutesSystem will detect these Temp entities and, on update, commit them to their originals (or create new originals), copy buffers/components back, emit PathTargetMoved events when positions change, and mark/cleanup Deleted/Updated/Applied as appropriate. Use the same component types (Owner, Hidden, Deleted, Updated, Created, Applied, PathTargetMoved) to interact consistently with this pipeline.