Skip to content

Game.Simulation.TransportBoardingHelpers

Assembly: Game
Namespace: Game.Simulation

Type: static class

Base: System.Object

Summary:
TransportBoardingHelpers contains utilities and data structures used to coordinate boarding/unboarding, loading and unloading of cargo and passengers for transport vehicles (trains, ships, airplanes, buses/delivery trucks) in the simulation. It defines lookup wrappers to access ECS component and buffer data, a thread-safe queue-based BoardingData for enqueueing boarding events from other systems/jobs, and a Burst-compiled IJob (TransportBoardingJob) that processes queued boarding items to update vehicle and station state, move resources between entities, track statistics/achievements, and schedule departures.

Fields

  • BoardingLookupData
    A nested struct that wraps numerous ComponentLookup and BufferLookup instances used by the boarding job to read/write ECS data (transport lines, transport stops, prefab refs and data, vehicle/building components, layout elements, route modifiers, economy buffers, storage transfer requests, etc.). This wrapper provides initialization and Update(system) to refresh the lookups each frame.

  • BoardingData
    A nested struct that encapsulates a NativeQueue used to enqueue boarding-related events from the simulation. It offers Dispose methods, scheduling support for the boarding job, and a Concurrent helper for thread-safe enqueue operations.

  • BoardingData.Concurrent
    A nested struct (inside BoardingData) exposing thread-safe methods to enqueue boarding events (BeginBoarding, EndBoarding, BeginTesting, EndTesting) by writing BoardingItem values into the underlying NativeQueue's ParallelWriter.

  • TransportBoardingJob (private)
    The Burst-compiled IJob that dequeues BoardingItem entries and executes the core logic: set vehicle/station boarding/testing flags, compute departure frames, move/transfer resources, accumulate station work amounts, and emit statistics/transported-resource events.

  • BoardingItem (private)
    A small POD struct used as queue entries describing a boarding/test begin or end event (vehicle, route, stop, waypoint, current/next stations, flags for begin/refuel/testing).

Properties

  • This static helper type does not expose public properties. Its nested types provide the API surface for enqueueing boarding events and scheduling the boarding job.

Constructors

  • BoardingLookupData(SystemBase system)
    Initializes all ComponentLookup and BufferLookup members from the provided SystemBase (use this in a System's OnCreate or OnUpdate to capture lookups). Call Update(system) each frame before scheduling the job to refresh handles.

  • BoardingData(Allocator allocator)
    Creates the internal NativeQueue. Use an appropriate Allocator (usually Allocator.Persistent if stored between frames).

  • BoardingData.Concurrent(BoardingData data)
    Creates a thread-safe ParallelWriter wrapper around the BoardingData queue for use from jobs or parallel contexts.

Notes: The nested job and internal structs have default no-arg constructors or are constructed by the methods above.

Methods

  • BoardingLookupData.Update(SystemBase system)
    Refreshes all ComponentLookup and BufferLookup instances for the current frame. Must be called before scheduling TransportBoardingJob so lookups reflect up-to-date ECS state.

  • BoardingData.Dispose() / BoardingData.Dispose(JobHandle inputDeps)
    Dispose the NativeQueue. Use the JobHandle overload when disposing after scheduling jobs that still reference the queue.

  • BoardingData.ScheduleBoarding(SystemBase system, CityStatisticsSystem statsSystem, AchievementTriggerSystem achievementTriggerSystem, BoardingLookupData lookupData, uint simulationFrameIndex, JobHandle inputDeps) : JobHandle
    Schedules the Burst-compiled TransportBoardingJob to process all queued BoardingItem entries. The method wires up statistics and achievement queues and returns a JobHandle for dependencies. It also registers the job as a writer with stats and achievement systems.

  • BoardingData.ToConcurrent() : BoardingData.Concurrent
    Returns a Concurrent wrapper to enqueue boarding events from jobs or parallel code.

  • BoardingData.Concurrent.BeginBoarding(Entity vehicle, Entity route, Entity stop, Entity waypoint, Entity currentStation, Entity nextStation, bool refuel)
    Enqueue a "begin boarding" event. Use this from systems/jobs when a vehicle starts boarding at a stop.

  • BoardingData.Concurrent.EndBoarding(Entity vehicle, Entity route, Entity stop, Entity waypoint, Entity currentStation, Entity nextStation)
    Enqueue an "end boarding" event (boarding finished).

  • BoardingData.Concurrent.BeginTesting(Entity vehicle, Entity route, Entity stop, Entity waypoint) / EndTesting(...)
    Enqueue testing begin/end events (used for test-running vehicles that shouldn't affect normal boarding state).

  • TransportBoardingJob.Execute() (private)
    Dequeues BoardingItem entries and dispatches to BeginTesting, EndTesting, BeginBoarding, or EndBoarding handlers.

  • TransportBoardingJob.BeginTesting / EndTesting (private)
    Mark/unmark a vehicle as testing for a specific stop and set the corresponding vehicle flags (CargoTransportFlags.Testing or PublicTransportFlags.Testing) and clear RequireStop where appropriate.

  • TransportBoardingJob.BeginBoarding / EndBoarding (private)
    Core logic that reserves a stop for the vehicle (m_BoardingVehicleData), computes departure frames using vehicle timing, route and prefab transport line data, sets vehicle state flags (Boarding, Refueling), clears/initializes loading buffers (LoadingResources), and orchestrates resource UnloadResources and LoadResources calls. EndBoarding clears boarding state and adds any remaining work.

  • TransportBoardingJob.UnloadResources / UnloadResources(DynamicBuffer) (private)
    Move resources from vehicle (or vehicles in a multi-layout vehicle) into the target building/entity's resource buffer, accumulate work amount, and optionally enqueue transported-resource events for achievement tracking.

  • TransportBoardingJob.LoadResources / LoadResources(Resource, ref int, ...) (private)
    Fulfill storage transfer requests at the source entity by loading resources into the vehicle's cargo buffers (respecting vehicle cargo capacity, resource compatibility and max resource count). Maintains LoadingResources buffer for UI/logic and emits statistics events per transport type (train/ship/airplane) and transported-resource entries for achievements.

  • TransportBoardingJob.AddWork(Entity target, int workAmount) (private)
    Walks owner chain to find a CargoTransportStation component and adds accumulated workAmount to its m_WorkAmount.

  • TransportBoardingJob.GetVehicleType(Entity vehicle) (private)
    Helper to determine TransportType (Train, Ship, Airplane, Bus, None) by checking component presence (Train, Watercraft, Aircraft, DeliveryTruck).

Notes on behavior:
- The job is Burst compiled and intended to run on worker threads. All ECS lookups are provided by BoardingLookupData and must be updated prior to scheduling.
- LoadingResources buffer is sorted (small-to-large) when present to prioritize smaller loads (the job uses an internal LoadingResourceComparer).
- If achievements are enabled (ShipIt), transported resources are enqueued to the achievement trigger queue for tracking.
- Statistics events are enqueued for cargo counts per transport type.

Usage Example

// Example usage inside a SystemBase-derived system:

private TransportBoardingHelpers.BoardingData m_BoardingData;
private TransportBoardingHelpers.BoardingLookupData m_LookupData;

public override void OnCreate()
{
    m_BoardingData = new TransportBoardingHelpers.BoardingData(Allocator.Persistent);
    m_LookupData = new TransportBoardingHelpers.BoardingLookupData(this);
}

public override void OnDestroy()
{
    m_BoardingData.Dispose();
}

public override void OnUpdate()
{
    // Refresh lookups each frame
    m_LookupData.Update(this);

    // Enqueue boarding events from main thread:
    var concurrent = m_BoardingData.ToConcurrent();
    Entity vehicle = /* some vehicle entity */;
    Entity route = /* route entity */;
    Entity stop = /* stop entity */;
    Entity waypoint = /* waypoint entity */;
    Entity currentStation = /* station entity or Entity.Null */;
    Entity nextStation = /* station entity or Entity.Null */;
    concurrent.BeginBoarding(vehicle, route, stop, waypoint, currentStation, nextStation, refuel: true);

    // Schedule the boarding job
    uint simFrame = /* current simulation frame index */;
    JobHandle deps = m_BoardingData.ScheduleBoarding(this, GetSingleton<CityStatisticsSystem>(), GetSingleton<AchievementTriggerSystem>(), m_LookupData, simFrame, Dependency);
    Dependency = deps;
}

Notes:
- Create BoardingLookupData from the SystemBase where you schedule the job and call Update each frame to refresh component lookups.
- Use BoardingData.Concurrent to push queue entries from other jobs in a thread-safe manner.
- Always dispose BoardingData when the owning system is destroyed (use the JobHandle overload if there are outstanding jobs).