Skip to content

Game.Simulation.TrainNavigationHelpers

Assembly: Assembly-CSharp (Game)
Namespace: Game.Simulation

Type: static class

Base: None (static helper class)

Summary:
TrainNavigationHelpers is a collection of helper types and static methods used by the train simulation to locate and manage train lanes, compute curve positions and maintain lane occupancy information. It defines small data structs used for signaling, reservations and lane effects, a cache helper (CurrentLaneCache) that updates lane occupancy command buffers when a train's current lanes change, and a quad-tree iterator (FindLaneIterator) that searches sub-lanes (Bezier curves) to find the closest lane positions for a train's front and rear bogies. The two GetCurvePositions overloads normalize/assemble curve-position ranges for train bogies and parked trains so other systems can compare or update lane occupancy ranges consistently.

Fields

  • None
    This is a static utility class and does not declare top-level instance fields. All relevant data types are exposed as nested structs and static methods.

Properties

  • None
    No properties are declared on the static helper class.

Constructors

  • None
    As a static class there are no public constructors or instance construction.

Methods

  • public static void GetCurvePositions(ref TrainCurrentLane currentLane, out float2 pos1, out float2 pos2)
    Returns curve-position ranges for the front and rear bogies (pos1 and pos2) extracted from a TrainCurrentLane. If both bogies are on the same sub-lane, the method produces a single consolidated [min,max] range and returns it in both outputs. Use this to compare previous vs current bogie curve ranges or to update lane occupancy buffers.

  • public static void GetCurvePositions(ref ParkedTrain parkedTrain, out float2 pos1, out float2 pos2)
    Similar to the TrainCurrentLane overload but works with ParkedTrain data where the parkedTrain stores its curve positions in a pair. If front and rear lanes are the same, the method consolidates them into an inclusive [min,max] range and returns identical values in pos1 and pos2.

  • public struct LaneSignal

  • Fields:
    • Entity m_Petitioner — the entity requesting the signal.
    • Entity m_Lane — the lane entity being signaled.
    • sbyte m_Priority — priority (small signed integer).
  • Constructor:
    • LaneSignal(Entity petitioner, Entity lane, int priority) — initializes a lane signal with petitioner, lane and priority (stored as sbyte).

  • Summary:

    • Small POD type used to express that some entity is requesting access/signaling for a particular lane with a priority.

  • public struct LaneReservation : IComparable<LaneReservation>

  • Fields:
    • Entity m_Lane — the lane entity reserved.
    • byte m_Priority — reservation priority.
  • Constructor:
    • LaneReservation(Entity lane, int priority) — initializes a reservation; priority stored as byte.
  • Methods:
    • public int CompareTo(LaneReservation other) — orders reservations by lane entity index (m_Lane.Index). Useful for sorting or deduplicating reservations.

  • Summary:

    • Represents a reservation on a lane with an associated priority; comparison is by lane entity index.

  • public struct LaneEffects

  • Fields:
    • Entity m_Lane — the lane entity the effects apply to.
    • float3 m_SideEffects — side-effect vector (for lateral influences).
    • float2 m_Flow — flow vector (for direction/throughput).
  • Constructor:
    • LaneEffects(Entity lane, float3 sideEffects, float2 flow)

  • Summary:

    • Holds per-lane influence data used for flow/effects calculations.

  • public struct CurrentLaneCache

  • Private fields:
    • Entity m_WasCurrentLane1, Entity m_WasCurrentLane2 — previously recorded lane entities for front/rear.
    • float2 m_WasCurvePosition1, float2 m_WasCurvePosition2 — previously recorded curve-position ranges.
  • Constructor:
    • public CurrentLaneCache(ref TrainCurrentLane currentLane, ComponentLookup<Lane> laneData)
      Initializes the cache from an existing TrainCurrentLane, sanitizing lane entity references (sets to Entity.Null if laneData does not contain the component) and captures the current curve positions for later change detection.
  • Methods:
    • public void CheckChanges(Entity entity, TrainCurrentLane currentLane, LaneObjectCommandBuffer buffer)
      Compares the current TrainCurrentLane to the cached previous state and issues add/update/remove commands to the provided LaneObjectCommandBuffer so lane occupancy records are kept in sync. The method handles multiple cases (swapped lanes, same lane for both bogies, moved positions on the same lane, etc.) and optimizes updates by only adding/removing/updating lanes that changed.

  • Summary:

    • Useful helper for efficiently detecting changes to which lanes a train currently occupies and updating lane object buffers accordingly.

  • public struct FindLaneIterator : INativeQuadTreeIterator<Entity, QuadTreeBoundsXZ>, IUnsafeQuadTreeIterator<Entity, QuadTreeBoundsXZ>

  • Fields (key ones):
    • Bounds3 m_Bounds — search bounds in world space.
    • float3 m_FrontPivot, m_RearPivot — pivot points (positions) for front and rear bogies to test distances.
    • float2 m_MinDistance — current best distances for front (x) and rear (y) bogies (search thresholds).
    • TrainCurrentLane m_Result — result structure populated with found lanes and curve positions for front/rear.
    • TrackTypes m_TrackType — allowed track types for the search.
    • BufferLookup<Game.Net.SubLane> m_SubLanes — sub-lane buffer lookup to enumerate sub-lanes on edge entities.
    • Several ComponentLookup fields used to validate and read sub-lane data: TrackLane, Curve, ConnectionLane, PrefabRef, TrackLaneData.
  • Methods:
    • public bool Intersect(QuadTreeBoundsXZ bounds) — returns whether provided quad-tree node intersects the search bounds.
    • public void Iterate(QuadTreeBoundsXZ bounds, Entity edgeEntity) — called for each quad-tree node that intersects; enumerates sub-lanes on the edge entity and:
    • Filters by presence of TrackLane component and matching TrackTypes from prefab track lane data.
    • Computes bounding-box distance to the search pivots, and if promising computes exact Bezier distance and curve parameter t.
    • Updates m_Result.m_Front / m_Result.m_Rear with the best found sub-lane and curve parameter t, including flags (Connection if applicable).
    • If only one bogie found, duplicates that sub-lane for the other bogie so both are populated.
  • Summary:
    • A quad-tree iterator specialized for searching train sub-lanes (Bezier curves) and finding the closest sub-lane positions for a train front and rear bogie given search pivots and allowed track types. This is used by navigation logic to pick candidate lanes when determining current lane occupancy.

Usage Example

// Example: retrieving consolidated curve positions for a moving train.
TrainCurrentLane currentLane = /* obtained from train entity */;
float2 frontRange, rearRange;
Game.Simulation.TrainNavigationHelpers.GetCurvePositions(ref currentLane, out frontRange, out rearRange);

// frontRange and rearRange now contain normalized curve position ranges.
// If both bogies are on the same lane they will be equal and represent a [min,max] range.

{{ Additional notes: - The FindLaneIterator relies on quad-tree traversal and several ComponentLookup and BufferLookup inputs — when using it in jobs or systems ensure you provide the correct lookups and that they are up-to-date. - CurrentLaneCache.CheckChanges expects a LaneObjectCommandBuffer (an abstraction used by the lane occupancy system) and efficiently issues Add/Update/Remove operations for lane occupancy. Use this rather than issuing lane buffer ops unconditionally to minimize churn. - GetCurvePositions normalizes ranges so comparisons are straightforward; callers should treat returned float2 as [min,max] pairs when lanes are identical or use them directly (y,z extraction for TrainCurrentLane) as appropriate. }}