Skip to content

Game.AnimalNavigationHelpers

Assembly: Assembly-CSharp
Namespace: Game.Simulation

Type: public static class AnimalNavigationHelpers

Base: System.Object

Summary:
Helper utilities used by the creature/animal navigation logic. Contains two nested structs: - CurrentLaneCache — a small cache and helper for tracking an animal's current lane and updating lane-related quad-tree / buffer indices when the animal moves or its lane assignment changes. - FindLaneIterator — a quad-tree / area iterator used to search for the nearest lane or connection lane to a given position, including special handling for area triangles (e.g., hangaround areas). These helpers are used by animal navigation systems to efficiently locate lanes, maintain spatial indices and calculate bounding boxes for lane-object quadtrees.

Fields

  • CurrentLaneCache.m_SearchTree : NativeQuadTree<Entity, QuadTreeBoundsXZ>
    Native search tree reference used to query existing quad-tree bounds for the entity when deciding whether to update spatial entries.

  • CurrentLaneCache.m_WasCurrentLane : Entity
    Cached value of the lane that was previously recorded for the entity. Used to detect lane changes so the quad-tree/buffer can be updated or moved.

  • CurrentLaneCache.m_WasCurvePosition : float
    Cached curve position (x component of the stored curve position) from the previous frame. Used to detect when the entity's position along the lane curve has changed enough to update lane buffers.

  • CurrentLaneCache.m_WasEndReached : bool
    Cached flag indicating whether the previous recorded lane had its "end reached" flag set. Used to detect transitions that require updating spatial entries.

  • FindLaneIterator.m_Bounds : Bounds3
    Search bounds used by the iterator to test intersection with quad-tree nodes or area triangles. Updated by the iterator as it narrows down the closest result.

  • FindLaneIterator.m_Position : float3
    Position from which distances to lanes / triangles are computed.

  • FindLaneIterator.m_MinDistance : float
    Current best (minimum) distance found so far. The iterator uses this to prune searches and refine results.

  • FindLaneIterator.m_UnspawnedEmerge : bool
    Flag used to restrict results for certain searches (e.g., skip non-connection lanes when trying to find places where unspawned animals can emerge).

  • FindLaneIterator.m_Result : AnimalCurrentLane
    Structure filled with the lane result (lane entity, curve position, flags) when the iterator finds a closer candidate.

  • FindLaneIterator.m_SubLanes : BufferLookup<Game.Net.SubLane>
    Buffer lookup used to enumerate sub-lanes belonging to an owner entity (lane collection). Required to examine each sub-lane within a quad-tree node or area.

  • FindLaneIterator.m_AreaNodes : BufferLookup<Game.Areas.Node>
    Buffer lookup for area node lists used when iterating area triangles.

  • FindLaneIterator.m_AreaTriangles : BufferLookup<Triangle>
    Buffer lookup for area triangles (triangles composing an area) used for area-to-lane proximity tests.

  • FindLaneIterator.m_PedestrianLaneData : ComponentLookup<Game.Net.PedestrianLane>
    Component lookup used to determine if a sub-lane is a pedestrian lane.

  • FindLaneIterator.m_ConnectionLaneData : ComponentLookup<Game.Net.ConnectionLane>
    Component lookup used to determine if a sub-lane is a connection lane and to check its connection flags (e.g., pedestrian).

  • FindLaneIterator.m_CurveData : ComponentLookup<Curve>
    Component lookup providing the bezier curve data for each sub-lane. Used to compute distances from a position to a lane curve.

  • FindLaneIterator.m_HangaroundLocationData : ComponentLookup<HangaroundLocation>
    Component lookup used to detect hangaround area metadata on an area entity; presence affects flags assigned to a found lane.

Properties

  • None (AnimalNavigationHelpers is a static container type; nested structs expose fields rather than properties).

Constructors

  • public CurrentLaneCache(ref AnimalCurrentLane currentLane, ComponentLookup<PrefabRef> prefabRefData, NativeQuadTree<Entity, QuadTreeBoundsXZ> searchTree)
    Initializes a CurrentLaneCache for an entity's current lane data. This constructor:
  • Validates that currentLane.m_Lane and currentLane.m_NextLane reference existing prefabs (clears them to Entity.Null if the referenced prefab no longer exists).
  • Stores the provided search tree.

  • Caches the lane, the curve position x component, and the end-reached flag so later changes can be detected.

  • AnimalNavigationHelpers (static class) has no instance constructors.

Methods

  • public void CurrentLaneCache.CheckChanges(Entity entity, ref AnimalCurrentLane currentLane, LaneObjectCommandBuffer buffer, BufferLookup<LaneObject> laneObjects, Transform transform, Moving moving, AnimalNavigation navigation, ObjectGeometryData objectGeometryData)
    Checks whether the current lane, curve position, or bounding requirements changed since the cache was created. Behavior overview:
  • If the lane entity changed since the cache was created, it removes the previous entry from the appropriate lane buffer or quad-tree and adds the entity to the new lane's buffer (or the quad-tree) using either the curve position or computed max bounds.
  • If the lane didn't change but the curve position changed and the lane uses a lane buffer, it updates the buffer entry with the new curve position.
  • If the previous lane used the quad-tree and the cached quad-tree bounds exist, it recalculates a minimum bound and compares to the stored quad-tree bounds; if the new min bounds are outside the stored quad-tree bounds (or the end-reached flag changed), it updates the quad-tree entry with newly computed max bounds.

  • This method uses CalculateMinBounds and CalculateMaxBounds to compute bounds.

  • private Bounds3 CurrentLaneCache.CalculateMinBounds(Transform transform, Moving moving, AnimalNavigation navigation, ObjectGeometryData objectGeometryData)
    Computes a conservative minimal bounding box around the entity based on current position, velocity and intended movement toward the navigation target. This is intended to detect small movements that do not require a full spatial-entry expansion.

  • private Bounds3 CurrentLaneCache.CalculateMaxBounds(Transform transform, Moving moving, AnimalNavigation navigation, ObjectGeometryData objectGeometryData)
    Computes a larger bounding box that accounts for potential movement, object size and velocities (used to add or update entries in the quad-tree when the entity's spatial extent must be expanded).

  • public bool FindLaneIterator.Intersect(QuadTreeBoundsXZ bounds)
    Quad-tree node intersection test that returns true when the node's bounds intersect the iterator's search bounds (m_Bounds). Used by quad-tree traversal.

  • public void FindLaneIterator.Iterate(QuadTreeBoundsXZ bounds, Entity ownerEntity)
    Called for each quad-tree node owned by a lane owner entity. If the node intersects the search bounds and the ownerEntity has a sublane buffer, the method iterates each sub-lane:

  • Filters non-pedestrian lanes unless connection lanes marked as pedestrian are present.
  • Optionally skips non-connection lanes when m_UnspawnedEmerge is set.

  • Measures distance from the search position to each lane bezier; if a candidate is closer than m_MinDistance, updates m_Result with the lane entity, curve position and flags.

  • public void FindLaneIterator.Iterate(QuadTreeBoundsXZ bounds, AreaSearchItem item)
    Called when iterating area items (AreaSearchItem) during an area-based search. Key behaviors:

  • Skips non-intersecting area nodes.
  • Computes the distance from the search position to the specific area triangle, and if closer than current m_MinDistance, samples the triangle position.
  • Iterates sub-lanes stored on the area to find connection lanes whose bezier intersects the triangle footprint; picks the nearest such lane and updates m_Result with lane, curve position and flags (including Hangaround flag when the area has HangaroundLocation).
  • This allows the search to discover lanes inside area-polygons (e.g., pedestrian plaza lanes or hangaround points).

Notes about interfaces: - FindLaneIterator implements INativeQuadTreeIterator, IUnsafeQuadTreeIterator, INativeQuadTreeIterator, and IUnsafeQuadTreeIterator. These are used by the engine's quad-tree traversal to call Intersect and Iterate methods for both lane-owner entities and area items.

Usage Example

// Example use within a system or component update
// (Assumes you have the required lookups, buffers and structures available)

ComponentLookup<PrefabRef> prefabRefData = GetComponentLookup<PrefabRef>(true);
NativeQuadTree<Entity, QuadTreeBoundsXZ> searchTree = /* obtain the native quad-tree used for lane objects */;
AnimalCurrentLane currentLane = /* read from entity */;
Entity entity = /* creature entity */;

var cache = new AnimalNavigationHelpers.CurrentLaneCache(ref currentLane, prefabRefData, searchTree);

// Later, inside an update loop, use CheckChanges to update lane buffers / quad-tree entries:
LaneObjectCommandBuffer laneBuffer = /* lane object command buffer */;
var laneObjects = GetBufferLookup<LaneObject>(false);
Transform transform = /* current transform */;
Moving moving = /* current moving component */;
AnimalNavigation navigation = /* current navigation component */;
ObjectGeometryData objectGeometryData = /* geometry data for the creature */;

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

This helper is intended to be used by animal navigation systems to keep lane membership and spatial indices consistent as creatures move and as lanes/areas change or are removed.