Skip to content

Game.WatercraftNavigationHelpers

Assembly: Game
Namespace: Game.Simulation

Type: static class

Base: System.Object

Summary:
Helper types and utilities used by the watercraft navigation system. This file contains small value types and iterators used to find suitable water/connection lanes, reserve or signal lanes, compute side effects/speeds for lanes, and cache / maintain current-lane tracking for watercraft objects. Key components: - LaneSignal, LaneReservation, LaneEffects — lightweight structs used to represent lane requests, reservations and per-lane effects. - CurrentLaneCache — maintains a small cache to keep lane search/add/remove operations efficient and to update quad-tree or lane object buffers when a vessel's current lane/position changes. - FindLaneIterator — a quad-tree iterator used to search both edge-sub-lanes and area-triangles to find the nearest compatible lane for a given position.

Fields

  • public Entity m_Petitioner
    Used in LaneSignal. The entity requesting access or signaling for a lane (typically a vehicle/watercraft entity).

  • public Entity m_Lane
    Used in LaneSignal, LaneReservation, LaneEffects. References the lane (sub-lane or connection lane) entity.

  • public sbyte m_Priority
    Used in LaneSignal. Priority of the petitioner when signaling.

  • public byte m_Offset
    Used in LaneReservation. Encoded lateral offset (0–255) representing offset along the lane.

  • public byte m_Priority
    Used in LaneReservation. Encoded priority for reservation.

  • public float3 m_SideEffects
    Used in LaneEffects. Side-effect vector (e.g., lateral offset or steering influence) applied by the lane.

  • public float m_RelativeSpeed
    Used in LaneEffects. Relative speed multiplier/penalty for this lane.

  • private NativeQuadTree<Entity, QuadTreeBoundsXZ> m_SearchTree
    Used inside CurrentLaneCache. The search quad-tree used to track/lookup entities' bounds.

  • private Entity m_WasCurrentLane
    Used inside CurrentLaneCache. Cached previous current lane entity for change detection.

  • private Entity m_WasChangeLane
    Used inside CurrentLaneCache. Cached previous change lane entity for change detection.

  • private float2 m_WasCurvePosition
    Used inside CurrentLaneCache. Cached previous curve position (xy) to detect when to update per-lane buffers.

  • public Bounds3 m_Bounds
    Used in FindLaneIterator. The search bounds used for intersection checks.

  • public float3 m_Position
    Used in FindLaneIterator. The position for which we are searching a lane.

  • public float m_MinDistance
    Used in FindLaneIterator. Current minimum found distance (used as threshold to find closer lanes).

  • public WatercraftCurrentLane m_Result
    Used in FindLaneIterator. Holds the resulting lane/candidate found by the iterator.

  • public RoadTypes m_CarType
    Used in FindLaneIterator. Road type mask (used to filter lanes compatible with the vehicle type).

  • public BufferLookup<Game.Net.SubLane> m_SubLanes
    Used in FindLaneIterator. Access to sub-lane buffers on edges/areas.

  • public BufferLookup<Game.Areas.Node> m_AreaNodes
    Used in FindLaneIterator. Access to area nodes for area-triangle search.

  • public BufferLookup<Triangle> m_AreaTriangles
    Used in FindLaneIterator. Access to area triangles for area search.

  • public ComponentLookup<Game.Net.CarLane> m_CarLaneData
    Used in FindLaneIterator. Component lookup to determine car-lane components and their properties.

  • public ComponentLookup<Game.Net.ConnectionLane> m_ConnectionLaneData
    Used in FindLaneIterator. Component lookup for connection lanes.

  • public ComponentLookup<MasterLane> m_MasterLaneData
    Used in FindLaneIterator. Component lookup for master-lane marker (used to filter master lanes).

  • public ComponentLookup<Curve> m_CurveData
    Used in FindLaneIterator. Curve data (Bezier) for lanes — used for distance calculations.

  • public ComponentLookup<PrefabRef> m_PrefabRefData
    Used in FindLaneIterator. Prefab reference lookup for lane-to-prefab mapping.

  • public ComponentLookup<CarLaneData> m_PrefabCarLaneData
    Used in FindLaneIterator. Prefab car-lane metadata (contains road types etc.) used to filter lanes by road type.

Properties

  • (No public properties defined on the static helper type itself; the nested structs expose public fields instead of properties.)

Constructors

  • public LaneSignal(Entity petitioner, Entity lane, int priority)
    Construct a LaneSignal with petitioner entity, target lane, and numeric priority. The priority is stored as an sbyte.

  • public LaneReservation(Entity lane, float offset, int priority)
    Construct a LaneReservation. offset is converted/clamped to a 0–255 byte by rounding offset * 255. Priority is stored as a byte.

  • public LaneEffects(Entity lane, float3 sideEffects, float relativeSpeed)
    Construct lane effects that apply lateral side effects and relative speed for the lane.

  • public CurrentLaneCache(ref WatercraftCurrentLane currentLane, EntityStorageInfoLookup entityLookup, NativeQuadTree<Entity, QuadTreeBoundsXZ> searchTree)
    Initialize a CurrentLaneCache: it normalizes the currentLane's lane/change-lane to Entity.Null when those entities do not exist and captures the current cached values and search tree for later change detection and updates.

Methods

  • public int CompareTo(LaneReservation other)
    (LaneReservation) Implements IComparable. Comparison is based on m_Lane.Index — used to order reservations by lane entity index.

  • public void CheckChanges(Entity entity, ref WatercraftCurrentLane currentLane, LaneObjectCommandBuffer buffer, BufferLookup<LaneObject> laneObjects, Transform transform, Moving moving, WatercraftNavigation navigation, ObjectGeometryData objectGeometryData)
    (CurrentLaneCache) Examines the stored previous lane/change-lane/curve position and updates lane-object buffers or the quad-tree accordingly. The method:

  • Removes the entity from old buffers when lane changed.
  • Adds/updates the entity in new lane buffers with curve position or, when not lane-buffered, updates quad-tree bounds using calculated min/max bounds.
  • Handles both current lane and change-lane entries.

  • This is the core routine that keeps per-lane lists and spatial indices consistent when a vessel moves or changes lanes.

  • private Bounds3 CalculateMinBounds(Transform transform, Moving moving, WatercraftNavigation navigation, ObjectGeometryData objectGeometryData)
    (CurrentLaneCache) Compute a tighter bounding box around the object accounting for a short look-ahead using current velocity and directional target. Used to check whether the stored quad-tree bounds still cover the object's minimal extents.

  • private Bounds3 CalculateMaxBounds(Transform transform, Moving moving, WatercraftNavigation navigation, ObjectGeometryData objectGeometryData)
    (CurrentLaneCache) Compute a larger bounding box that covers a more conservative movement envelope. Uses object size, velocity multipliers, and navigation target to produce bounds suitable for quad-tree entries.

  • public bool Intersect(QuadTreeBoundsXZ bounds)
    (FindLaneIterator) Implementation of quad-tree iterator intersection test. Returns whether the provided quad-tree cell bounds intersect the iterator's search Bounds3.

  • public void Iterate(QuadTreeBoundsXZ bounds, Entity edgeEntity)
    (FindLaneIterator) Iterate over an edge's sub-lanes (edgeEntity) when that edge intersects the search bounds. For each sub-lane it:

  • Filters out lanes that are master lanes or incompatible by component/prefab/car-type.

  • Computes the shortest distance between lane curve and search position and updates m_Result when a closer candidate is found (also stores curve t position and lane flags).

  • public void Iterate(QuadTreeBoundsXZ bounds, AreaSearchItem item)
    (FindLaneIterator) Iterate over an area triangle when the area intersects the search bounds. For area searches it:

  • Finds the closest triangle point to m_Position.
  • Iterates area sub-lanes (connection lanes) to find curves intersecting the triangle (or triangle corners), computes distances, and if a suitable connection lane is found closer than current threshold, updates m_Result (marks lane as Area + FixedLane appropriately).

Usage Example

// Example: maintain a per-vehicle CurrentLaneCache and update per-lane buffers when current lane changes.
// Called from a system/update that has access to the required lookups and command buffers.

public void ExampleUsage(Entity vehicleEntity,
                         ref WatercraftCurrentLane currentLane,
                         EntityStorageInfoLookup entityLookup,
                         NativeQuadTree<Entity, QuadTreeBoundsXZ> searchTree,
                         LaneObjectCommandBuffer laneBuffer,
                         BufferLookup<LaneObject> laneObjects,
                         Transform transform,
                         Moving moving,
                         WatercraftNavigation navigation,
                         ObjectGeometryData objectGeometryData)
{
    // Construct the cache (captures current lane state)
    var cache = new WatercraftNavigationHelpers.CurrentLaneCache(ref currentLane, entityLookup, searchTree);

    // ... some simulation code may change currentLane.m_Lane or m_ChangeLane or m_CurvePosition ...

    // Check for changes and update lane buffers / quad-tree entries accordingly
    cache.CheckChanges(vehicleEntity, ref currentLane, laneBuffer, laneObjects,
                       transform, moving, navigation, objectGeometryData);
}

If you want, I can also produce a short example showing how to use FindLaneIterator to search for the nearest compatible lane for a given position.