Skip to content

Game.Simulation.TransportVehicleDispatchSystem

Assembly:
Namespace: Game.Simulation

Type: class

Base: GameSystemBase

Summary:
System responsible for handling transport vehicle requests (TransportVehicleRequest) for transport lines. It validates requests and targets/sources, schedules pathfinding for matching vehicles or routes, marks requests as dispatched, and queues actual vehicle dispatches to be applied at the end of the frame. Internally it uses two Burst-compiled jobs: - TransportVehicleDispatchJob (IJobChunk) — processes TransportVehicleRequest entities, validates targets/sources, enqueues pathfinding setup items and vehicle dispatch intents, and updates ServiceRequest state. - DispatchVehiclesJob (IJob) — dequeues vehicle dispatch intents and writes ServiceDispatch buffers or marks service requests to skip cooldown.

The system depends on EndFrameBarrier to emit commands at end of frame, PathfindSetupSystem to schedule pathfinding work, and SimulationSystem/frameIndex to decide processing windows. It runs on an interval of 16 simulation frames (GetUpdateInterval returns 16).

Fields

  • private EndFrameBarrier m_EndFrameBarrier
    Holds the EndFrameBarrier system instance used to create a parallel EntityCommandBuffer for late-frame structural changes (adding/removing components, destroying entities, etc.). Commands produced by the jobs are played back by the barrier.

  • private SimulationSystem m_SimulationSystem
    Reference to the SimulationSystem to read the current frameIndex and derive the update window (which requests to process this pass).

  • private PathfindSetupSystem m_PathfindSetupSystem
    Reference to PathfindSetupSystem used to obtain a pathfind setup queue writer to enqueue pathfinding requests (SetupQueueItem) created by this system.

  • private EntityQuery m_RequestQuery
    EntityQuery used to select all entities that contain TransportVehicleRequest and UpdateFrame components; used to schedule the TransportVehicleDispatchJob in parallel.

  • private TypeHandle __TypeHandle
    Compiled container of EntityTypeHandle / ComponentTypeHandle / ComponentLookup / BufferLookup used by the generated job code to access components efficiently. Assigned in OnCreateForCompiler.

  • private struct VehicleDispatch (nested)
    Small POD struct used to enqueue (requestEntity, sourceEntity) pairs into a NativeQueue carried to DispatchVehiclesJob.

  • private struct TransportVehicleDispatchJob (nested)
    Burst-compiled IJobChunk job that does the bulk of request processing: validation, scheduling pathfinds, setting/removing components, and enqueueing VehicleDispatch intents.

  • private struct DispatchVehiclesJob (nested)
    Burst-compiled IJob that consumes the VehicleDispatch queue and applies ServiceDispatch buffers or updates ServiceRequest components to trigger immediate dispatch behavior.

Properties

  • None

Constructors

  • public TransportVehicleDispatchSystem()
    Default constructor. The system initializes its internal references and queries in OnCreate/OnCreateForCompiler rather than the ctor.

Methods

  • public override int GetUpdateInterval(SystemUpdatePhase phase)
    Returns 16. The system is scheduled to run every 16 simulation frames (it uses the simulation frameIndex to compute which UpdateFrame index to process).

  • protected override void OnCreate()
    Initializes references to required systems (EndFrameBarrier, SimulationSystem, PathfindSetupSystem), sets up the EntityQuery for TransportVehicleRequest + UpdateFrame, and registers the query with RequireForUpdate so the system only updates if there are requests.

  • protected override void OnUpdate()
    Main scheduling method:

  • Computes two frame indices (current 3-bit index and "next" index) from SimulationSystem.frameIndex to split processing across frames.
  • Allocates a NativeQueue for cross-job communication.
  • Populates and schedules a TransportVehicleDispatchJob (IJobChunk) to run in parallel over the request query. That job:
    • Validates reversed or forward requests.
    • Schedules pathfinding (enqueues SetupQueueItem) when needed and adds PathInformation / PathElement buffers.
    • Marks requests as Dispatched and enqueues VehicleDispatch items when origin/destination are resolved.
    • Resets or destroys requests on failure.
  • Schedules DispatchVehiclesJob (IJob) after the chunk job to consume VehicleDispatch queue and apply ServiceDispatch or modify ServiceRequest on source entities.

  • Disposes the NativeQueue once jobs are completed, adds the queue writer to PathfindSetupSystem, and registers job handle with EndFrameBarrier (producer) so the command buffer plays back safely.

  • protected override void OnCreateForCompiler()
    Internal setup used by generated/compiled code: calls __AssignQueries and assigns component/type handles in __TypeHandle.

  • [MethodImpl(MethodImplOptions.AggressiveInlining)] private void __AssignQueries(ref SystemState state)
    Small helper used by the compiler-generated code path to ensure queries are prepared. Not intended for direct use in mods.

  • TransportVehicleDispatchJob.Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask, in v128 chunkEnabledMask)
    Core chunk-processing routine. Behavior summary:

  • Uses UpdateFrame shared component on chunks to decide early processing (one pass checks requests for the "next" update-frame index, other pass handles the current index).
  • Validates reversed requests by checking transport depots/public/cargo transport states and possibly assigns target request on the source.
  • Validates transport line targets and assigns vehicleRequest on the transport line component.
  • For valid forward requests, enqueues pathfinding to find a vehicle source (FindVehicleSource) or, for reversed requests, finds a vehicle target (FindVehicleTarget).
  • When PathInformation is present (path search complete), dispatches vehicles (DispatchVehicle) or resets failed/reverse requests accordingly.

  • Adds/Removes components (PathInformation, PathElement, Dispatched) via the parallel command buffer where appropriate.

  • TransportVehicleDispatchJob.ValidateReversed(Entity entity, Entity source) : bool
    Checks if a reversed request can be served by the source (transport depot, public transport, cargo transport), ensuring vehicle availability, maintenance state, parked state, and ensures no competing TransportVehicleRequest is already registered.

  • TransportVehicleDispatchJob.ValidateHandler(Entity entity, Entity handler) : bool
    Checks whether a given handler entity contains a ServiceDispatch buffer entry that corresponds to this request (used to verify that a dispatched handler actually took the request).

  • TransportVehicleDispatchJob.ValidateTarget(Entity entity, Entity target, bool dispatched) : bool
    Validates that the target Route/TransportLine requires vehicles and that it is not already linked to another TransportVehicleRequest. If free, it writes the association into TransportLine.m_VehicleRequest.

  • TransportVehicleDispatchJob.FindVehicleSource / FindVehicleTarget
    Builds PathfindParameters and SetupQueueTarget (origin/destination) pairs appropriate to the route/type/prefab of the vehicle or route, and enqueues a SetupQueueItem to the PathfindSetupSystem queue so pathfinding can run and produce a PathInformation component on the request entity.

  • TransportVehicleDispatchJob.DispatchVehicle / ResetReverseRequest / ResetFailedRequest
    Helpers that enqueue VehicleDispatch entries into the NativeQueue, add Dispatched components to requests, and reset or clear path/path-element/dispatched components on failed requests.

  • void DispatchVehiclesJob.Execute()
    Consumes the VehicleDispatch native queue and for each item:

  • If the source entity has a ServiceDispatch buffer, appends a ServiceDispatch entry referencing the request.
  • Otherwise, if the source entity is a ServiceRequest, sets its SkipCooldown flag to indicate it should be dispatched immediately (by setting m_Flags |= ServiceRequestFlags.SkipCooldown).

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // Typical initialization the original system performs:
    m_EndFrameBarrier = base.World.GetOrCreateSystemManaged<EndFrameBarrier>();
    m_SimulationSystem = base.World.GetOrCreateSystemManaged<SimulationSystem>();
    m_PathfindSetupSystem = base.World.GetOrCreateSystemManaged<PathfindSetupSystem>();
    m_RequestQuery = GetEntityQuery(ComponentType.ReadOnly<TransportVehicleRequest>(), ComponentType.ReadOnly<UpdateFrame>());
    RequireForUpdate(m_RequestQuery);
}

Notes for modders: - This system is tightly integrated with the game's ECS types (TransportVehicleRequest, TransportLine, TransportDepotData, PublicTransport/CargoTransport components, ServiceRequest/ServiceDispatch buffers, PathInformation/PathElement components, and Pathfind setup). When creating mods that add or modify transport behavior, ensure compatibility with these components and with PathfindSetupSystem expectations. - The system enqueues structural changes via an EndFrameBarrier command buffer — mutations (Add/Remove component, DestroyEntity) happen on play-back; do not expect immediate synchronous component changes inside jobs. - Pathfinding setup uses SetupQueueItem with carefully selected PathfindParameters and ignored rules; when adding new transport types or route types, align those parameters accordingly.