Skip to content

Game.CarNavigationHelpers

Assembly:
(Part of the game's Simulation assemblies — included with the game runtime)

Namespace: Game.Simulation

Type: static class

Base: System.Object

Summary:
Utilities and helper types for resolving and tracking car lane navigation in the simulation. This static class contains several nested structs used by vehicle systems to: - find the nearest lane or connection for cars (FindLaneIterator), - detect and manage blocked lanes in a search region (FindBlockedLanesIterator), - keep track of an individual car's current lane and notify lane-object buffers when the car moves (CurrentLaneCache), - similar trailer/tractor lane tracking for vehicles with trailers (TrailerLaneCache), - simple value-types for lane signals, reservations and aggregate lane effects.

These helpers are intended to be used by simulation systems that operate on Entities, quad-trees, and lane buffers (e.g., per-frame lane selection, lane-object registration/unregistration and blocked-lane detection). They rely on various game types (Curve, CarNavigation, CarCurrentLane, CarTrailerLane, BlockedLane, ObjectGeometryData, etc.) and use Native collections and math utilities.

Fields

  • None (static class contains nested helper structs and iterators)
    This static class does not declare top-level fields. All relevant stateful behavior is implemented in the nested structs (CurrentLaneCache, TrailerLaneCache, iterators, and small POD structs).

Properties

  • None
    There are no properties on the static CarNavigationHelpers type itself. See nested structs for fields and behaviour.

Constructors

  • CarNavigationHelpers()
    Not applicable — the type is static and has no public constructor. All functionality is exposed via nested structs.

Methods

The static class hosts only nested types (structs) that encapsulate the important methods you will use from simulation systems. Key nested types and their most relevant methods:

  • LaneSignal (struct)
  • Purpose: small POD used to convey a lane request from a petitioner entity to a lane entity with a priority.

  • Constructor: LaneSignal(Entity petitioner, Entity lane, int priority)

  • LaneReservation (struct, IComparable)

  • Purpose: compact representation of a reserved lane with an offset and priority.
  • Constructor: LaneReservation(Entity lane, float offset, int priority) — offset stored as byte (0..255).

  • Method: int CompareTo(LaneReservation other) — compares by lane entity index (for sorting).

  • LaneEffects (struct)

  • Purpose: contains aggregated side-effects and flow vectors for a lane.

  • CurrentLaneCache (struct)

  • Purpose: tracks the previously-known lane state for a vehicle, and updates lane-object buffers / quad-tree entries when lane or curve position changes or when blocked lanes change.
  • Constructor: CurrentLaneCache(ref CarCurrentLane currentLane, DynamicBuffer<BlockedLane> blockedLanes, EntityStorageInfoLookup entityLookup, NativeQuadTree<Entity, QuadTreeBoundsXZ> searchTree)
    • Validates the referenced lane/change-lane entities against entityLookup; initializes internal "was" state and search tree reference.

  • Methods:

    • void CheckChanges(Entity entity, ref CarCurrentLane currentLane, NativeList<BlockedLane> newBlockedLanes, LaneObjectCommandBuffer buffer, BufferLookup<LaneObject> laneObjects, Transform transform, Moving moving, CarNavigation navigation, ObjectGeometryData objectGeometryData)
    • Main routine that determines whether to Add/Remove/Update lane-object registrations or the quad-tree bounds for this vehicle. Handles:
      • Newly detected blocked lanes: adds/updates/removes lane-object entries as needed.
      • Changes between current lane and change-lane (lane-change transitions).
      • When the vehicle moved enough to require expanding quad-tree bounds.
    • Important for maintaining lane-object buffers used by things such as stop/priority logic, obstruction tracking, or visual lane markers.
    • private Bounds3 CalculateMinBounds(Transform transform, Moving moving, CarNavigation navigation, ObjectGeometryData objectGeometryData)
    • Computes a conservative minimal bounds of the object considering short-term motion.
    • private Bounds3 CalculateMaxBounds(Transform transform, Moving moving, CarNavigation navigation, ObjectGeometryData objectGeometryData)
    • Computes a larger bounds to ensure the entity remains discoverable by queries while moving or changing lanes.

  • TrailerLaneCache (struct)

  • Purpose: analogous to CurrentLaneCache but used for trailer/tractor combinations; tracks both current and next lanes for the trailer and updates buffers/quad-tree similarly.
  • Constructor: TrailerLaneCache(ref CarTrailerLane trailerLane, DynamicBuffer<BlockedLane> blockedLanes, ComponentLookup<PrefabRef> prefabRefData, NativeQuadTree<Entity, QuadTreeBoundsXZ> searchTree)

  • Methods:

    • void CheckChanges(Entity entity, ref CarTrailerLane trailerLane, NativeList<BlockedLane> newBlockedLanes, LaneObjectCommandBuffer buffer, BufferLookup<LaneObject> laneObjects, Transform transform, Moving moving, CarNavigation tractorNavigation, ObjectGeometryData objectGeometryData)
    • Same responsibilities as CurrentLaneCache.CheckChanges but works with trailer lane fields (m_Lane, m_NextLane, m_CurvePosition, m_NextPosition).
    • private Bounds3 CalculateMinBounds(...) and private Bounds3 CalculateMaxBounds(...) — same intent as for CurrentLaneCache.

  • FindLaneIterator (struct implementing quad-tree iterator interfaces)

  • Purpose: used to search the native quad-tree for the closest valid car lane (or connection) to a given position inside a search bounds. Also supports area->lane connections by iterating area triangles.
  • Fields of interest:
    • search parameters: Bounds3 m_Bounds, float3 m_Position, float m_MinDistance, RoadTypes m_CarType
    • result: CarCurrentLane m_Result (contains chosen lane, curve position, lane flags)
    • lookups: BufferLookup, ComponentLookup, ConnectionLane, Curve, PrefabRef, CarLaneData, MasterLane, Area buffers...

  • Methods:

    • bool Intersect(QuadTreeBoundsXZ bounds) — used by quad-tree to cull nodes intersecting m_Bounds.
    • void Iterate(QuadTreeBoundsXZ bounds, Entity ownerEntity) — examines sub-lanes under an edge entity; filters by road type, lane flags, master-lane, prefab carlane data; computes distance from the lane bezier to m_Position; updates m_Result if nearer.
    • void Iterate(QuadTreeBoundsXZ bounds, AreaSearchItem item) — When searching over area triangles, finds a matching connection-lane whose curve intersects the triangle and picks the nearest point.

  • FindBlockedLanesIterator (struct)

  • Purpose: finds lanes whose beziers intersect/approach a given segment (Line3.Segment) within a radius — used to mark lanes blocked by a large vehicle footprint or moving obstruction.
  • Fields of interest:
    • search params: Bounds3 m_Bounds, Line3.Segment m_Line, float m_Radius
    • output: NativeList<BlockedLane> m_BlockedLanes
    • lookups: BufferLookup, ComponentLookup, MasterLane, PrefabRef, NetLaneData
  • Methods:
    • bool Intersect(QuadTreeBoundsXZ bounds) — quad-tree culling.
    • void Iterate(QuadTreeBoundsXZ bounds, Entity edgeEntity) — for each sublane attached to the edge, checks intersection/closest distance; computes lane-local t-range occupied by the blocking object and adds BlockedLane entries to m_BlockedLanes.

Notes about usage: - These helpers operate with low-level game types (Entity, BufferLookup, ComponentLookup, DynamicBuffer, NativeQuadTree). They are intended for use inside ECS systems or other simulation systems that run on the main or worker threads, respecting the Native container safety rules. - Many of the methods mutate lane-object registration buffers (via LaneObjectCommandBuffer) — make sure to call them in a context where it is safe to modify those buffers (often a command-buffer pattern). - Distance computations use math utilities and curve geometry (Bezier4x3) — they assume that Curve data and PrefabRef/NetLaneData lookups are set up and accessible.

Usage Example

// Example: initialize a CurrentLaneCache for a car and check for changes in a system update.
// (This is simplified pseudo-code sketch showing the intended pattern.)

// Suppose inside a system:
CarCurrentLane currentLane = ...; // fetched from component
DynamicBuffer<BlockedLane> blockedLanesBuffer = ...; // vehicle's blocked lanes buffer
EntityStorageInfoLookup entityLookup = ...;
NativeQuadTree<Entity, QuadTreeBoundsXZ> searchTree = ...;

var cache = new CarNavigationHelpers.CurrentLaneCache(
    ref currentLane,
    blockedLanesBuffer,
    entityLookup,
    searchTree);

// Later, during the frame when you want to update lane-object registrations:
NativeList<BlockedLane> newlyFoundBlockedLanes = ...; // filled by FindBlockedLanesIterator
LaneObjectCommandBuffer laneObjCmdBuffer = ...; // wrapper to add/remove/update lane objects
BufferLookup<LaneObject> laneObjects = ...;
Transform transform = ...;
Moving moving = ...;
CarNavigation navigation = ...;
ObjectGeometryData objectGeometryData = ...;

cache.CheckChanges(entity, ref currentLane, newlyFoundBlockedLanes, laneObjCmdBuffer, laneObjects, transform, moving, navigation, objectGeometryData);

Additional tips: - Use FindLaneIterator with the native quad-tree query API (provide an iterator instance with bounds and position) to discover the nearest valid lane for a vehicle spawn or a lane switch operation. - Use FindBlockedLanesIterator to compute blocked-lane ranges from a vehicle's footprint (Line3.Segment + radius) and feed its results to CurrentLaneCache or TrailerLaneCache so lane-object buffers remain accurate. - Carefully manage NativeList / DynamicBuffer lifetimes and scheduling when running queries on worker threads.