Skip to content

Game.Simulation.TrainNavigationSystem

Assembly: Assembly-CSharp
Namespace: Game.Simulation

Type: class

Base: GameSystemBase

Summary:
TrainNavigationSystem is the ECS system responsible for updating train navigation each simulation tick slice. It computes per-train navigation lanes, updates boogie/vehicle positions, applies lane reservations and lane-side effects (wear, flow, pollution), and updates lane signals. The system uses Unity's Jobs/Burst (several internal IJob/IJobChunk jobs) and Native collections (queues/lists) to parallelize most work. It queries train entities (layouts) and schedules the following work each update: navigation update (UpdateNavigationJob), lane reservation update (UpdateLaneReservationsJob), application of lane effects (ApplyLaneEffectsJob) and lane signal updates (UpdateLaneSignalsJob). It also coordinates with a LaneObjectUpdater for lane-object changes.

Notes for modders: - The system runs on an interval of 16 (GetUpdateInterval) with an offset of 3 (GetUpdateOffset). - Most fields are private and internal jobs operate on component data directly (TrainCurrentLane, TrainNavigation, TrainNavigationLane, LaneReservation, LaneSignal, LaneFlow, LaneCondition, Game.Net.TrackLane, Curve, etc.). To affect behavior, modify those components or intercept lower-level systems/components rather than extending this class. - The system uses Game.Net.SearchSystem's net-search tree for lane lookup; heavy changes to that structure will affect this system. - Be careful with threading/parallel writes: the system uses parallel-safe patterns and NativeQueues. Modifications from external code should be performed from the main thread or via properly synchronized jobs.

Fields

  • private Game.Net.SearchSystem m_NetSearchSystem
    Used to obtain the read-only net search tree for spatial lane lookups. UpdateNavigationJob uses this tree to discover candidate lanes for a train's pivots.

  • private EntityQuery m_VehicleQuery
    EntityQuery used to select train controller entities/layouts for processing. Built in OnCreate and required for update; includes Train, Transform, Moving, Target, PrefabRef, PathElement, PathOwner, TrainCurrentLane, TrainNavigation, TrainNavigationLane, LayoutElement, etc.

  • private LaneObjectUpdater m_LaneObjectUpdater
    Helper/updater used to batch and apply lane-object changes discovered while updating navigation lanes. The updater provides a command buffer used by UpdateNavigationJob and is applied at the end of OnUpdate.

  • private TypeHandle __TypeHandle
    Internal struct storing component type handles, buffer handles and ComponentLookup references used to populate job-data with correct handles for scheduling. Assigned in OnCreateForCompiler.

Properties

  • None (no public properties exposed by this system).

Constructors

  • public TrainNavigationSystem()
    Default public constructor. The system initialization is performed in OnCreate.

Methods

  • public override int GetUpdateInterval(SystemUpdatePhase phase)
    Returns the update interval for this system. For TrainNavigationSystem this returns 16 (system executes every 16 simulation ticks).

  • public override int GetUpdateOffset(SystemUpdatePhase phase)
    Returns the update offset for this system. For TrainNavigationSystem this returns 3.

  • [Preserve] protected override void OnCreate()
    Initializes the system: gets/creates Game.Net.SearchSystem, constructs m_VehicleQuery (targeting train-related components and buffers), creates the LaneObjectUpdater and calls RequireForUpdate(m_VehicleQuery). This prepares the system for updates.

  • [Preserve] protected override void OnUpdate()
    Main scheduling method. Creates NativeQueues for lane effects and lane signals, retrieves archetype chunks for m_VehicleQuery asynchronously, constructs job data structs for UpdateNavigationJob, UpdateLaneReservationsJob, ApplyLaneEffectsJob and UpdateLaneSignalsJob, schedules them (UpdateNavigationJob as a parallel JobChunk), disposes of temporary native collections via job dependencies, registers the net-search-tree reader, applies lane-object updates, and combines dependencies into base.Dependency. This method orchestrates all work performed by the system each tick slice.

  • protected override void OnCreateForCompiler()
    Internal method used for compiler-time setup. Calls __AssignQueries and assigns the internal type handles by invoking __TypeHandle.__AssignHandles.

  • private void __AssignQueries(ref SystemState state)
    Internal helper used during compilation/setup (empty in the compiled code but called to satisfy compiler flow).

  • Inner Job types (important work split across multiple jobs):

  • UpdateNavigationJob : IJobChunk
    The largest job: iterates vehicle chunks, updates per-layout TrainCurrentLane caches, fills navigation lanes from PathElements, computes train speed & blockers, moves navigation targets along curves, updates bogie followers for all cars in the layout, enqueues lane-side effects and lane signals, and writes back TrainNavigation and TrainCurrentLane components. Uses many ComponentLookup/BufferLookup handles (Curve, TrackLane, ConnectionLane, LaneReservation, LaneSignal, Prefab data, etc.).
  • UpdateLaneReservationsJob : IJob
    Iterates the collected archetype chunks and reserves lanes for current bogies and for navigation lanes (translates TryReserve flags into LaneReservation updates). Ensures current lanes are always reserved at high priority.
  • ApplyLaneEffectsJob : IJob
    Consumes the lane-effects queue produced by UpdateNavigationJob and applies wear (LaneCondition), flow (LaneFlow), and pollution (Game.Net.Pollution on owner) updates.

  • UpdateLaneSignalsJob : IJob
    Consumes the lane-signal queue and updates LaneSignal component values (petitioner & priority) when a higher priority requester was found.

  • Other important private helper methods inside UpdateNavigationJob (summarized here because they are central to behavior):

  • UpdateNavigationLanes / TryFindCurrentLane / FillNavigationPaths: Locate or re-fill navigation lanes for a layout, using the net-search tree and PathElement buffer.
  • UpdateTrainLimits: Adjust effective train limits (speed/accel/braking) based on consist cars.
  • UpdateNavigationTarget: Core speed/blocker calculation and movement of navigation target bogie along curves; enqueues lane signals/effects and updates bogie follower positions for attendant cars.
  • TryReserveNavigationLanes: Marks navigation lanes with TryReserve/FullReserve flags for reservation pass to claim space ahead.
  • MoveTarget / MoveFollowerTarget / ClampPosition: Numerical routines that move leader and follower bogie targets along Bezier curves while respecting min/max distances.
  • ApplySideEffects: Enqueue lane-side effects (wear/flow/pollution) for lanes traversed by trains.

Usage Example

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

    // Example: how the system initializes its query and dependencies.
    m_NetSearchSystem = World.GetOrCreateSystemManaged<Game.Net.SearchSystem>();
    m_VehicleQuery = GetEntityQuery(
        ComponentType.ReadOnly<Train>(),
        ComponentType.ReadOnly<Game.Objects.Transform>(),
        ComponentType.ReadOnly<Moving>(),
        ComponentType.ReadOnly<Target>(),
        ComponentType.ReadOnly<PrefabRef>(),
        ComponentType.ReadOnly<PathElement>(),
        ComponentType.ReadWrite<PathOwner>(),
        ComponentType.ReadWrite<TrainCurrentLane>(),
        ComponentType.ReadWrite<TrainNavigation>(),
        ComponentType.ReadWrite<TrainNavigationLane>(),
        ComponentType.ReadWrite<LayoutElement>(),
        ComponentType.Exclude<Deleted>(),
        ComponentType.Exclude<Temp>(),
        ComponentType.Exclude<TripSource>());

    m_LaneObjectUpdater = new LaneObjectUpdater(this);
    RequireForUpdate(m_VehicleQuery);
}

Further tips: - To influence train routing, modify PathOwner / PathElement buffers or supply different PathElements for a controller. - To affect reservation behavior, modify LaneReservation components or LaneSignal components (these are used by the system). - For debugging, watch TrainCurrentLane and TrainNavigation components on train vehicles to inspect bogie positions/speeds.