Skip to content

Game.Simulation.MailTransferDispatchSystem

Assembly:
Namespace: Game.Simulation

Type: class

Base: GameSystemBase

Summary:
{{ Handles mail transfer service requests in the simulation. Scans MailTransferRequest entities on a staggered update schedule, validates targets (post facilities), schedules pathfinding to find vehicle sources, enqueues dispatch actions, and applies the resulting dispatches to PostFacility, ServiceDispatch and TripNeeded buffers. Uses Unity DOTS jobs (IJobChunk + IJob) and an EndFrameBarrier command buffer to perform entity/component changes safely at the end of the frame. }}

Fields

  • private EndFrameBarrier m_EndFrameBarrier
    {{ Barrier used to create an EntityCommandBuffer for applying structural changes produced by the jobs at end of frame. }}

  • private SimulationSystem m_SimulationSystem
    {{ Reference to the SimulationSystem used to read the current simulation frame index and compute the staggered update window. }}

  • private PathfindSetupSystem m_PathfindSetupSystem
    {{ Reference to the PathfindSetupSystem — used to obtain a pathfinding setup queue writer to enqueue pathfind work (SetupQueueItem). }}

  • private EntityQuery m_RequestQuery
    {{ Query that selects MailTransferRequest entities (and their UpdateFrame shared component). This is required for the system to run. }}

  • private TypeHandle __TypeHandle
    {{ Internal container of component/lookup type handles used to build job parameter handles. Populated in OnCreateForCompiler. }}

Properties

  • (none)
    {{ This system does not expose any public properties. All state is maintained via private fields and ECS component data. }}

Constructors

  • public MailTransferDispatchSystem()
    {{ Default constructor (preserved for DOTS/IL2CPP). No custom construction logic — initialization occurs in OnCreate. }}

Methods

  • public override int GetUpdateInterval(SystemUpdatePhase phase)
    {{ Returns the update interval in ticks for this system. Implementation returns 16, which is used together with the simulation frame index to stagger processing across frames. }}

  • protected override void OnCreate()
    {{ Initializes system references (EndFrameBarrier, SimulationSystem, PathfindSetupSystem) and creates the EntityQuery (MailTransferRequest + UpdateFrame). Calls RequireForUpdate to ensure the system runs only when there are mail requests. }}

  • protected override void OnUpdate()
    {{ Core scheduling logic:

  • Computes a pair of frame indices (m_UpdateFrameIndex and m_NextUpdateFrameIndex) based on the SimulationSystem.frameIndex, used to stagger processing.
  • Allocates a NativeQueue for cross-job communication.
  • Constructs and schedules MailTransferDispatchJob (IJobChunk) which:
    • Validates MailTransferRequest targets (PostFacility).
    • If appropriate, enqueues pathfinding (SetupQueueItem) via PathfindSetupSystem queue writer.
    • Adds PathInformation/PathElement components when pathfinding is requested.
    • Handles entities that already have Dispatched or PathInformation components: resets failed requests, sets cooldowns, or marks entities dispatched (adds Dispatched component and enqueues dispatch action).
  • Constructs and schedules DispatchActionJob (IJob) which:
    • Dequeues DispatchAction items and applies them: either adds ServiceDispatch or TripNeeded entries, consumes/adjusts resources on dispatch sources, and sets PostFacility.m_MailDeliverRequest / m_MailReceiveRequest for delivery/receive facilities.

  • Disposes the dispatch queue after jobs complete, registers the pathfind queue writer, and adds job handles to the EndFrameBarrier for correct ordering of the command buffer. }}

  • private void __AssignQueries(ref SystemState state)
    {{ Compiler helper used in generated code path — constructs and assigns queries; here it currently creates and disposes an EntityQueryBuilder (likely a no-op placeholder used by the codegen). }}

  • protected override void OnCreateForCompiler()
    {{ Called during compile-time/on generated code path to assign type handles and queries via __AssignQueries and __TypeHandle.__AssignHandles. }}

  • Internal nested job: MailTransferDispatchJob : IJobChunk
    {{ Burst-compiled IJobChunk that iterates over chunks of MailTransferRequest entities. Responsibilities:

  • Uses shared UpdateFrame to pick which requests to process this frame (staggered).
  • Validates target PostFacility (accept/deliver priorities).
  • If no path info/dispatched and request is ready, calls FindVehicleSource to enqueue pathfind work (SetupQueueItem) and adds PathInformation + PathElement buffer components.
  • If a PathInformation with origin exists, enqueues a DispatchAction for the found origin and marks the request as Dispatched (adds Dispatched component).
  • If a Dispatched component is present, checks whether a service handler still references the request (ValidateHandler). If not, handles cooldowns and resets failed requests if necessary.
  • Uses EntityCommandBuffer.ParallelWriter to perform structural changes from the job safely.

  • Enqueues DispatchAction items to a NativeQueue for the follow-up job. }}

  • Internal nested job: DispatchActionJob : IJob
    {{ Burst-compiled IJob that consumes DispatchAction items produced by MailTransferDispatchJob:

  • For each dispatch action, if m_DispatchSource is a PostFacility with a ServiceDispatch buffer, adds a ServiceDispatch entry.
  • If m_DispatchSource is an entity providing TripNeeded buffer (citizen/vehicle agents), creates and adds a TripNeeded entry, mapping MailTransferRequest flags -> Resource and Purpose, and consumes resources from the source via EconomyUtils when exporting.
  • Updates PostFacility components to record active mail deliver/receive request entity references.

  • Uses a non-parallel EntityCommandBuffer for immediate application (but scheduled as a job so structural changes are applied via EndFrameBarrier). }}

  • Internal helpers inside the job(s):

  • ValidateHandler(Entity entity, Entity handler)
    {{ Checks whether a handler currently references the request via ServiceDispatch or TripNeeded buffers. Used to determine whether a dispatched request is still being handled. }}
  • ValidateTarget(Entity entity, MailTransferRequest requestData)
    {{ Validates that the referenced PostFacility exists, checks accept/deliver priorities, enqueues a DispatchAction for the facility if needed, and prevents duplicate requests on the same PostFacility. }}
  • ResetFailedRequest(int jobIndex, Entity entity, bool dispatched, ref ServiceRequest serviceRequest)
    {{ Resets the ServiceRequest cooldown, removes PathInformation and PathElement components, and optionally removes Dispatched component when a request has failed to be handled. }}
  • DispatchVehicle(int jobIndex, Entity entity, PathInformation pathInformation)
    {{ Enqueues a DispatchAction for the path origin and adds a Dispatched component referencing the origin. }}
  • FindVehicleSource(int jobIndex, Entity requestEntity, MailTransferRequest requestData)
    {{ Builds PathfindParameters and SetupQueueTarget(s) from the MailTransferRequest flags and amount, wraps them into a SetupQueueItem, enqueues it on the PathfindSetupSystem queue, and adds PathInformation and PathElement buffer to the request entity so the pathfind result can be written back later. }}

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    m_EndFrameBarrier = World.GetOrCreateSystemManaged<EndFrameBarrier>();
    m_SimulationSystem = World.GetOrCreateSystemManaged<SimulationSystem>();
    m_PathfindSetupSystem = World.GetOrCreateSystemManaged<PathfindSetupSystem>();
    m_RequestQuery = GetEntityQuery(ComponentType.ReadOnly<MailTransferRequest>(), ComponentType.ReadOnly<UpdateFrame>());
    RequireForUpdate(m_RequestQuery);
}

{{ Example shows how the system initializes required system references and its entity query in OnCreate. The system's main behavior is driven by its OnUpdate scheduling of MailTransferDispatchJob and DispatchActionJob. }}