Skip to content

Game.Simulation.CreatureTargetIterator

Assembly:
Game (simulation/game assembly; type lives in the game's codebase — commonly Assembly-CSharp in most modding setups)
Namespace:
Game.Simulation

Type:
struct CreatureTargetIterator

Base:
Value type (System.ValueType)

Summary:
CreatureTargetIterator is a utility value-type used by creature/pathing simulation to iterate lane overlap segments and determine a target stopping delta when a creature approaches overlapping lanes (e.g. road/track crossings). It inspects lane overlap buffers, lane reservations and lane objects to detect blocking reservations or moving objects and computes a queue area and queue entity for creatures to form a queue before the blocker. The iterator updates internal state fields (m_TargetDelta, m_Blocker, m_BlockerType, m_QueueEntity, m_QueueArea) to represent the result of the iteration.

Fields

  • public ComponentLookup<Moving> m_MovingData
    Lookup to test whether lane objects represent moving entities (used to detect dynamic blockers).

  • public ComponentLookup<Curve> m_CurveData
    Lookup that provides curve geometry for lanes; used to compute world positions on a lane curve.

  • public ComponentLookup<LaneReservation> m_LaneReservationData
    Lookup for lane reservation components. Lane reservations are examined to detect reserved offsets/priorities that make an overlap act as a blocker.

  • public BufferLookup<LaneOverlap> m_LaneOverlaps
    BufferLookup for lane overlap buffers. These contain overlap entries describing overlapping ranges between lanes; IterateLane consumes this buffer to find relevant overlaps.

  • public BufferLookup<LaneObject> m_LaneObjects
    BufferLookup for lane-placed objects (signals, props, dynamic objects attached to lanes). Used to detect moving lane objects inside overlap ranges.

  • public ObjectGeometryData m_PrefabObjectGeometry
    Prefab/object geometry used to compute a queue area (passed to CreatureUtils.GetQueueArea).

  • public Entity m_Blocker
    Entity reference to the detected blocker (either an object/entity or Entity.Null). Set by CheckOverlapLane when a blocking lane object is found.

  • public BlockerType m_BlockerType
    Type of blocker detected (e.g., Crossing). Set when an overlap is considered blocking.

  • public Entity m_QueueEntity
    Entity of the lane where creatures should queue. When an overlap causes queuing, this is set to the current lane.

  • public Sphere3 m_QueueArea
    A sphere (Sphere3) describing the queue area for creatures computed from the lane curve and object geometry.

  • private float m_TargetDelta
    Internal working value representing the computed target curve delta (0..1) where creatures should stop/queue. Updated during iteration. Not directly accessible externally.

Properties

  • (No public properties)
    This struct exposes no properties. It operates via public fields and methods. Before calling IterateLane, callers should set the lookup/buffer fields to valid ComponentLookup/BufferLookup instances for the current world/system context.

Constructors

  • public CreatureTargetIterator()
    (The default parameterless struct constructor) Initializes an instance with default/null values. Callers must populate the public lookup/buffer fields and m_PrefabObjectGeometry before use.

Methods

  • public bool IterateLane(Entity currentLane, ref float curveDelta, float targetDelta)
    Iterates the lane overlap buffer for currentLane to determine whether movement from the start curveDelta toward targetDelta crosses any overlapping lane entries that should cause queuing or stop. It:
  • Stores targetDelta internally.
  • Scans m_LaneOverlaps buffer for non-merge overlaps and only those tagged as Road or Track.
  • For each relevant overlap, computes normalized overlap positions and checks whether the creature's movement crosses into an overlap interval (comparing curveDelta and m_TargetDelta).
  • When a crossing is detected, calls CheckOverlapLane to determine whether the overlap is blocked by a lane reservation or a moving lane object. If blocked, the iterator sets m_TargetDelta to the limiting delta and records blocker info and queue area.
  • After scanning, updates curveDelta to the resolved m_TargetDelta.
  • Returns true if no blocking change occurred and m_TargetDelta equals the original targetDelta (i.e., the full move to targetDelta is allowed), otherwise false.

Parameters: - currentLane: lane Entity whose overlap buffer is inspected. - curveDelta: ref float holding the current position on the lane curve; it will be updated to the computed stopping delta. - targetDelta: the desired target curve delta the creature wishes to reach.

Returns: - bool: true if movement to targetDelta is allowed (no blocking overlap), false if movement was truncated/blocked (curveDelta updated accordingly).

Notes: - This method relies on m_CurveData, m_LaneOverlaps, m_LaneReservationData and m_LaneObjects being valid and populated. - It compares overlap flags and uses normalized 0..1 curve deltas (lane overlap stores positions as bytes scaled by ~1/255).

  • private void CheckOverlapLane(Entity currentLane, Entity overlapLane, float limitDelta, float targetDelta, float2 overlapRange)
    Checks a single overlapping lane to determine if it should block movement at limitDelta. Behavior:
  • Looks up a LaneReservation component on overlapLane. If present, retrieves reservation offset and priority. If the reservation offset exceeds overlap minimum or priority is high (>= 108), it treats the overlap as blocking:
    • Sets m_TargetDelta to limitDelta.
    • Clears m_Blocker (Entity.Null).
    • Sets m_BlockerType to BlockerType.Crossing.
    • Computes two positions along the current lane curve (at limitDelta and at one endpoint depending on targetDelta) and uses CreatureUtils.GetQueueArea with m_PrefabObjectGeometry to compute m_QueueArea.
    • Sets m_QueueEntity to currentLane and returns.
  • If no blocking reservation forced a stop, enumerates the LaneObject buffer on overlapLane. For each LaneObject overlapping the overlapRange and which is currently associated with a Moving component (m_MovingData.HasComponent), treats that lane object as a blocking moving object:
    • Sets m_TargetDelta to limitDelta.
    • Sets m_Blocker to the lane object's entity and m_BlockerType to BlockerType.Crossing.
    • Computes queue positions and m_QueueArea and sets m_QueueEntity.
    • Breaks out (first matching lane object wins).

Notes: - overlapRange is the other lane's overlap start/end expressed in normalized curve delta coordinates (float2). - The method uses m_CurveData[currentLane] to compute world positions for the queue area using MathUtils.Position and CreatureUtils.GetQueueArea.

Usage Example

// Example usage inside a simulation system where lookups/buffers are available:
CreatureTargetIterator iter = new CreatureTargetIterator
{
    m_MovingData = GetComponentLookup<Moving>(false),
    m_CurveData = GetComponentLookup<Curve>(true),
    m_LaneReservationData = GetComponentLookup<LaneReservation>(true),
    m_LaneOverlaps = GetBufferLookup<LaneOverlap>(true),
    m_LaneObjects = GetBufferLookup<LaneObject>(true),
    m_PrefabObjectGeometry = myPrefabGeometry // supply relevant prefab geometry
};

float currentDelta = 0.25f;
float desiredDelta = 0.9f;
Entity laneEntity = someLaneEntity;

bool canReach = iter.IterateLane(laneEntity, ref currentDelta, desiredDelta);
if (!canReach)
{
    // iter.m_TargetDelta (internal) was applied to currentDelta; a blocker was recorded:
    Entity blocker = iter.m_Blocker;
    BlockerType type = iter.m_BlockerType;
    Entity queueLane = iter.m_QueueEntity;
    Sphere3 queueArea = iter.m_QueueArea;

    // Handle queuing behavior for the creature using queueArea/queueLane.
}

Remarks / Implementation notes: - This struct is intended to be used in the simulation update path where ComponentLookup and BufferLookup are set up with correct read/write access (and possibly with Job safety/Burst considerations). - The algorithm treats certain overlap flags (merge segments) as non-relevant and focuses on Road/Track overlaps. - Reservation priority threshold (>= 108) and offset checks are game-specific heuristics; these values come from the game's lane reservation semantics. - Callers must ensure lookups are up-to-date for the current world version before calling IterateLane (use SystemBase.GetComponentLookup / GetBufferLookup or their equivalents).