Skip to content

Game.Simulation.HumanNavigationHelpers

Assembly: Assembly-CSharp
Namespace: Game.Simulation

Type: static class

Base: System.Object

Summary:
Utility helpers for human (pedestrian/creature) navigation. Provides lightweight data structures and algorithms used by the simulation to find and track navigation lanes, update spatial search structures when a human's lane or motion changes, and iterate/search quadtrees/areas for the best lane/connection for a human. The class contains nested types: LaneSignal (simple signal packet), CurrentLaneCache (keeps a cached representation of a human's current lane and updates spatial indexes when things change), and FindLaneIterator (quad-tree / area iterator that finds closest/potential pedestrian lanes or connections).
{{ HumanNavigationHelpers groups together utilities used by human navigation systems: lane selection, bounds calculations to update lane-object spatial indices, and quad-tree/area iterators used by lane search. }}

Fields

  • None (static class has no instance fields)
    {{ HumanNavigationHelpers itself contains no top-level fields. All data and behavior are provided by its nested types: LaneSignal, CurrentLaneCache and FindLaneIterator. }}

Properties

  • None
    {{ There are no top-level properties on this static helper class. See nested types for data members and lookups. }}

Constructors

  • None
    {{ Being a static helper container, the class has no public constructors. All functionality is available through nested types and static usage patterns. }}

Methods

  • None (no top-level methods)
    {{ The actionable methods are located on the nested types (CurrentLaneCache.CheckChanges, FindLaneIterator.Iterate, etc.). See the Nested Types section below for details and descriptions of those methods. }}

Nested Types

Below are the nested types declared inside HumanNavigationHelpers. Each is documented with its fields, constructors and methods.

LaneSignal

  • Type: struct

Fields: - public Entity m_Petitioner
{{ Entity that is requesting or associated with the lane signal (usually the human/creature). }}

  • public Entity m_Lane
    {{ Lane entity referenced by this signal. }}

  • public sbyte m_Priority
    {{ Priority of the signal (small integer cast to sbyte). }}

Constructors: - public LaneSignal(Entity petitioner, Entity lane, int priority)
{{ Initializes the signal with the petitioner, lane entity and integer priority which is cast to sbyte. Used as a small POD packet to register lane requests or signals. }}

CurrentLaneCache

  • Type: struct

Fields: - private NativeQuadTree<Entity, QuadTreeBoundsXZ> m_SearchTree
{{ Quad-tree used to keep track of the entity-based bounding boxes for lane objects when a lane does not have a dedicated lane buffer. Used to query/update the stored bounds. }}

  • private Entity m_WasCurrentLane
    {{ Previously cached current lane entity at construction time. }}

  • private float m_WasCurvePosition
    {{ Previously cached curve position (x component) along the lane. }}

  • private bool m_WasEndReached
    {{ Previously cached state whether the end of the lane was reached by the human. }}

Constructors: - public CurrentLaneCache(ref HumanCurrentLane currentLane, EntityStorageInfoLookup entityLookup, NativeQuadTree<Entity, QuadTreeBoundsXZ> searchTree)
{{ Constructs a cache snapshot from an existing HumanCurrentLane. If the lane entity no longer exists (checked via entityLookup), the current lane is set to Entity.Null. Captures m_WasCurrentLane, m_WasCurvePosition and whether the EndReached flag was set. Stores a reference to the search quad-tree for later updates. }}

Methods: - public void CheckChanges(Entity entity, ref HumanCurrentLane currentLane, LaneObjectCommandBuffer buffer, BufferLookup<LaneObject> laneObjects, Transform transform, Moving moving, HumanNavigation navigation, ObjectGeometryData objectGeometryData)
{{ Core method to detect changes in the current lane/curve position/flags and update the appropriate spatial index or lane-object buffers: - If the lane entity changed, remove the previous entry (either using the lane's buffer or the entity-based buffer) and add the new entry (either to the lane buffer or insert newly computed max bounds into the search quad-tree via buffer.Add). - If the lane stayed the same and the lane has a lane buffer, update the curve position when it changed. - If the lane stayed the same but uses the entity-based quad-tree, fetch existing bounds from the quad-tree and compare to a newly computed minimal bounds (CalculateMinBounds); if the min bounds fall outside the stored bounds or the EndReached flag changed to set, replace with newly computed max bounds. This keeps spatial indices correct while avoiding overly frequent large updates. }}

  • private Bounds3 CalculateMinBounds(Transform transform, Moving moving, HumanNavigation navigation, ObjectGeometryData objectGeometryData)
    {{ Computes a conservative "minimum" bounding box for the human given current transform, velocity, navigation target direction and object geometry. Used to check if the currently stored quad-tree bounds still fully contain where the human might be. Uses a short-time motion envelope (scale factor 4/15) combining current velocity and direction-to-target. }}

  • private Bounds3 CalculateMaxBounds(Transform transform, Moving moving, HumanNavigation navigation, ObjectGeometryData objectGeometryData)
    {{ Computes an expanded "maximum" bounding box intended for insertion into the quad-tree when a larger bound is required. This uses a heuristic combination of past/future velocity vectors, an envelope multiplier, and the object's half-size to produce a safe bounding box that covers possible movement and geometry extents. }}

Notes: {{ CurrentLaneCache is designed to minimize expensive quad-tree updates by only updating the search tree when the human's bounds truly change in a way that could affect spatial queries (lane-object overlap). It supports lane entities that either hold a lane-specific buffer (sub-lane lists) or use the global entity-based quad-tree. }}

FindLaneIterator

  • Type: struct
    Implements:
  • INativeQuadTreeIterator<Entity, QuadTreeBoundsXZ>
  • IUnsafeQuadTreeIterator<Entity, QuadTreeBoundsXZ>
  • INativeQuadTreeIterator<AreaSearchItem, QuadTreeBoundsXZ>
  • IUnsafeQuadTreeIterator<AreaSearchItem, QuadTreeBoundsXZ>

Fields: - public Bounds3 m_Bounds
{{ Current search bounds used for intersection tests and updated during iteration to tighten the search. }}

  • public float3 m_Position
    {{ Query position (point) for which the closest lane/connection is being found. }}

  • public float m_MinDistance
    {{ Current best distance threshold. Iteration looks for lanes closer than this. Typically initialized to some maximum or current best distance. }}

  • public bool m_UnspawnedEmerge
    {{ Flag indicating whether lanes in unspawned 'emerge' state should be considered. }}

  • public HumanCurrentLane m_Result
    {{ Output/result structure: when a closer lane is found, this field is filled with the lane entity, curve position and flags describing lane type (connection, hangaround, etc.). }}

  • public BufferLookup<Game.Net.SubLane> m_SubLanes
    {{ Buffer lookup to read sub-lane lists from entities (roads/areas) when iterating an owner entity. }}

  • public BufferLookup<Game.Areas.Node> m_AreaNodes
    {{ Buffer lookup for area node data used when iterating AreaSearchItem entries. }}

  • public BufferLookup<Triangle> m_AreaTriangles
    {{ Triangle buffers for area geometry; used to compute distances when iterating area items. }}

  • public ComponentLookup<Game.Net.PedestrianLane> m_PedestrianLaneData
    {{ Component lookup for pedestrian lane data to verify and mark lanes as pedestrian if present. }}

  • public ComponentLookup<Game.Net.ConnectionLane> m_ConnectionLaneData
    {{ Component lookup for connection lanes (used to identify connections that can be used by pedestrians). }}

  • public ComponentLookup<Curve> m_CurveData
    {{ Component lookup for curve data (Bezier curves) for lanes. Needed to compute distances and curve param t. }}

  • public ComponentLookup<HangaroundLocation> m_HangaroundLocationData
    {{ Optional component marking hangaround locations inside areas (used to set flags on results found via area iteration). }}

Methods: - public bool Intersect(QuadTreeBoundsXZ bounds)
{{ Returns whether the provided quad-tree cell bounds intersect the iterator's search bounds (m_Bounds). Used by the quad-tree to decide if the iterator should be called for that cell. }}

  • public void Iterate(QuadTreeBoundsXZ bounds, Entity ownerEntity)
    {{ Iterates over a quad-tree cell owned by an entity (e.g., roadway or lane-owner). Behavior:

    • If the cell bounds don't intersect m_Bounds or the owner entity doesn't have a SubLane buffer, return.
    • For each SubLane in the owner's buffer:
    • Determine whether the sub-lane is a pedestrian lane or a connection lane; set flags accordingly.
    • If m_UnspawnedEmerge is true, skip non-connection lanes unless allowed.
    • Compute a fast bounds-to-point distance between the lane's bezier bounding box and the query position; if less than m_MinDistance, compute the exact bezier distance (and param t).
    • If the exact distance is less than m_MinDistance, update m_Result with lane entity, curve position (t), flags, tighten m_Bounds to the distance and update m_MinDistance. This evaluates discrete lanes associated with an owner entity and picks a closer lane if found. }}

  • public void Iterate(QuadTreeBoundsXZ bounds, AreaSearchItem item)
    {{ Iterates over an area tile/triangle:

    • Checks the area cell intersects the iterator bounds and that the area has sub-lanes.
    • Reconstructs a Triangle3 for the area triangle and computes the closest point on that triangle to m_Position (and a distance).
    • If triangle-to-position distance is better than m_MinDistance, sample the area's sub-lanes (only connection lanes with pedestrian flag) and check whether the lane curve intersects the triangle's XZ projection; if so compute exact distance to the curve and candidate t.
    • For candidate lanes, selects the best lane (minimum distance), clamps the parameter t inside a chosen interval depending on intersection locations to avoid boundary issues, and if a valid lane is found updates m_Result, m_Bounds and m_MinDistance accordingly. This path allows finding lanes that are associated with area geometry (e.g., hangaround areas, area-based pedestrian connections). }}

Notes: {{ FindLaneIterator is a general-purpose iterator used by the simulation's quad-tree and area search to locate the closest suitable pedestrian or connection lane for a human at a given position. It combines bounding-box pre-checks with exact curve distance checks and populates a HumanCurrentLane result with lane entity, curve position (t) and lane flags (Connection, Hangaround, etc.). }}

Usage Example

// Example: find the nearest lane for a pedestrian position using FindLaneIterator with a pre-initialized quadtree/area search.
// (This is a simplified pseudo-usage sketch — real usage requires proper entity queries and a prepared search tree/context.)

FindLaneIterator iter = default;
iter.m_Position = queryPosition;
iter.m_Bounds = new Bounds3(queryPosition - 10f, queryPosition + 10f); // initial search radius
iter.m_MinDistance = 10f;
iter.m_UnspawnedEmerge = false;

// supply ComponentLookup/BufferLookup references from current System or SystemAPI:
iter.m_SubLanes = system.GetBufferLookup<Game.Net.SubLane>(true);
iter.m_CurveData = system.GetComponentLookup<Curve>(true);
iter.m_PedestrianLaneData = system.GetComponentLookup<Game.Net.PedestrianLane>(true);
iter.m_ConnectionLaneData = system.GetComponentLookup<Game.Net.ConnectionLane>(true);
iter.m_AreaNodes = system.GetBufferLookup<Game.Areas.Node>(true);
iter.m_AreaTriangles = system.GetBufferLookup<Triangle>(true);
iter.m_HangaroundLocationData = system.GetComponentLookup<HangaroundLocation>(true);

// Now pass `iter` into your NativeQuadTree/Area search iterator to populate iter.m_Result
// After search, check iter.m_Result for a chosen lane and curve position.

{{ Example demonstrates how to construct a FindLaneIterator, initialize search parameters and provide lookups. In the real simulation, iterators are driven by the quad-tree/area search systems and executed on the appropriate thread/context. }}