Game.Simulation.VehicleCollisionIterator

Assembly: Game (assembly containing the game's simulation types — typically the main game assembly)
Namespace: Game.Simulation

Type: struct

Base: System.ValueType; implements INativeQuadTreeIterator, IUnsafeQuadTreeIterator

Summary:
VehicleCollisionIterator is a simulation-time iterator used to query static and moving object quadtrees to detect potential collisions or blockers for a moving vehicle/creature along a proposed lane movement. It computes a target lane segment, expands a search bounding box, iterates relevant spatial trees, and evaluates collisions against both moving and stationary objects to (a) adjust the desired target position to avoid intersections and (b) determine blocking entities and a reduced maximum speed. This struct is intended to be initialized with the appropriate ComponentLookup/BufferLookup and other contextual fields, then executed via IterateFirstLane to perform collision checking for a single lane/pass.

Fields

public ComponentLookup<Owner> m_OwnerData
Lookup for Owner component (maps lane/entity -> owner entity). Used when reading owner information for lanes/area lookup.
public ComponentLookup<Transform> m_TransformData
Lookup for Transform component (position/rotation). Required to read positional data of other entities when checking collisions.
public ComponentLookup<Moving> m_MovingData
Lookup for Moving component (velocity). Used to handle dynamic (moving) objects — compute relative motion and sweep tests.
public ComponentLookup<Controller> m_ControllerData
Lookup for Controller component. Used to ignore entities that are controlled by the same controller as the iterating entity.
public ComponentLookup<Creature> m_CreatureData
Lookup for Creature component. If other entity is a creature this iterator may treat it differently (e.g. skip certain checks).
public ComponentLookup<Curve> m_CurveData
Lookup for Curve component. (Present for completeness — potentially used elsewhere when dealing with lanes/paths.)
public ComponentLookup<AreaLane> m_AreaLaneData
Lookup for AreaLane component. Used to fetch area-lane node indices to compute intersections between candidate lane and area polygon when calculating the target line.
public ComponentLookup<PrefabRef> m_PrefabRefData
Lookup for PrefabRef component. Used to map an entity to the prefab index so object geometry can be queried.
public ComponentLookup<ObjectGeometryData> m_PrefabObjectGeometryData
Lookup for ObjectGeometryData for prefabs. Used to check bounds, flags (e.g., WalkThrough, Standing), leg size, etc.
public ComponentLookup<NetLaneData> m_PrefabLaneData
Lookup for NetLaneData. Included for completeness related to lane/prefab info.
public BufferLookup<Game.Areas.Node> m_AreaNodes
Buffer lookup for area nodes (polygon vertices). Used to test intersections between a short line across the target position and the area polygon to compute limits.
public NativeQuadTree<Entity, QuadTreeBoundsXZ> m_StaticObjectSearchTree
Quad-tree containing static objects. Iterated to find potential static collisions.
public NativeQuadTree<Entity, QuadTreeBoundsXZ> m_MovingObjectSearchTree
Quad-tree containing moving objects. Iterated to find potential dynamic collisions.
public TerrainHeightData m_TerrainHeightData
Optional terrain height query data. Used to sample vertical heights when adjusting the target position after 2D collision adjustments.
public Entity m_Entity
The entity performing the movement / being tested (the "self" entity). Used to ignore self in collision checks and for controller comparisons.
public Entity m_CurrentLane
Lane entity currently being evaluated / iterated first (passed into IterateFirstLane).
public float m_CurvePosition
Current curve position along the lane (used for lane positioning logic / alignment).
public float m_TimeStep
Simulation timestep used when projecting velocities for dynamic collision checks.
public ObjectGeometryData m_PrefabObjectGeometry
Geometry data for the iterating entity's prefab. Used to determine its size and collision footprint.
public Bounds1 m_SpeedRange
Allowed speed range for the entity; used when computing a reduced max speed due to collisions.
public float3 m_CurrentPosition
Current world position of the entity.
public float3 m_CurrentVelocity
Current world velocity of the entity.
public float m_MinDistance
Minimum distance to keep from the target position when computing target line and limits.
public float3 m_TargetPosition
Desired target world position. May be adjusted by CheckCollision to avoid overlaps.
public float m_MaxSpeed
Current maximum allowed speed for the entity; CheckCollision may lower this when blockers are found.
public float m_LanePosition
Lane-relative position (result of projecting a rebound target onto the target line). Updated by collision handling.
public Entity m_Blocker
The entity determined as the current blocking object (if any) after iteration.
public BlockerType m_BlockerType
Type of blocking detected (e.g., Crossing, Continuing). Set when a blocker that reduces speed is found.
private Line3.Segment m_TargetLine
Internal: the computed short 3D segment across the lane/area used as the permissible target line to project to and to compute lane limits.
private Bounds1 m_TargetLimits
Internal: 1D parameter range of permissible positions along m_TargetLine (used to convert normalized lane position to lane offset).
private float m_PushFactor
Internal ephemeral factor used to apply incremental push-out from collisions. It is halved each time a push is applied.
private Bounds3 m_Bounds
Internal: expanded 3D bounds used to cull quad-tree nodes before per-item checks.
private float m_Size
Internal: half-size derived from the iterating entity's geometry used for distance checks.

Properties

None. This struct uses public fields rather than C# properties for data access.

Constructors

public VehicleCollisionIterator()
Default value-type constructor. All fields must be populated/initialized by the caller before use. Typical initialization includes assigning ComponentLookup/BufferLookup values, setting m_Entity, m_CurrentPosition, m_TargetPosition, m_PrefabObjectGeometry, m_MinDistance, m_TimeStep, m_SpeedRange, and the two quadtrees for static/moving objects.

Methods

public bool IterateFirstLane(Entity currentLane)
Initializes per-iteration state for the supplied lane, computes m_Size and m_PushFactor, computes the target line/limits by calling CalculateTargetLine for the provided lane, then iterates both the moving-object and static-object quadtrees (m_MovingObjectSearchTree and m_StaticObjectSearchTree) using this struct as the quad-tree iterator. Returns false (this implementation always returns false); the primary effect is side-effects on m_TargetPosition, m_MaxSpeed, m_Blocker, and m_BlockerType.
public bool Intersect(QuadTreeBoundsXZ bounds)
Quad-tree intersection test used during iteration. Returns true if the provided quad-tree node bounds match the expected mask (NotOverridden | NotWalkThrough) and their 2D bounds intersect the iterator's m_Bounds. Used to cull quad-tree nodes before calling Iterate for items.
public void Iterate(QuadTreeBoundsXZ bounds, Entity item)
Called for each entity found in an intersecting quad-tree node. If the bounds satisfy the mask and bounding-box intersection, calls CheckCollision(item) to evaluate per-entity collision logic.
private void CalculateTargetLine(Entity targetLane, float3 targetPosition)
Computes the lane target segment (m_TargetLine) and the normalized parameter limits (m_TargetLimits) that define safe along-lane movement, by intersecting a short lateral line around the targetPosition with the area polygon represented by the lane's AreaLane nodes. This method also clamps the limits with m_MinDistance and computes m_Bounds by expanding the target line and current position by m_Size. The result is used as the region to search for collisions and to project adjusted positions back onto the lane.
private void CheckCollision(Entity other)
Core collision logic executed for each candidate entity 'other'. Behavior:
Ignores the iterating entity itself and any entity lacking a Transform.
Skips objects whose prefab geometry flag includes WalkThrough.
If 'other' has a Moving component:
- Skips creatures and entities controlled by the same controller.
- Performs a swept segment-segment distance test between this entity's movement segment and the other's predicted movement segment (using other's velocity and m_TimeStep).
- If distance < combined radii threshold, computes a push offset to the target position and reduces m_PushFactor; projects the offset back to m_TargetLine and adjusts m_LanePosition.
- Computes a reduced candidate max speed (num4) based on relative heading, relative velocity, distance, and configured m_SpeedRange; clamps and if less than current m_MaxSpeed sets m_MaxSpeed, m_Blocker, and m_BlockerType.
If 'other' is stationary:
- Computes distance from stationary entity to this entity's movement line; if within threshold, computes a push offset as above and projects back to lane and updates m_TargetPosition and m_LanePosition.
Optionally samples terrain height for adjusted target positions if m_TerrainHeightData is created.

Notes: CheckCollision mutates m_TargetPosition, m_MaxSpeed, m_Blocker, m_BlockerType and uses a variety of geometric helpers in MathUtils/Line2/Line3. The algorithm balances lateral pushing with speed-lowering to produce smooth avoidance behavior.

Usage Example

// Example: prepare and run a collision check for an entity moving along a lane.
// (This is a simplified usage sketch — real initialization happens in the simulation system.)

var iter = new VehicleCollisionIterator
{
    m_OwnerData = system.GetComponentLookup<Owner>(true),
    m_TransformData = system.GetComponentLookup<Transform>(true),
    m_MovingData = system.GetComponentLookup<Moving>(true),
    m_ControllerData = system.GetComponentLookup<Controller>(true),
    m_CreatureData = system.GetComponentLookup<Creature>(true),
    m_AreaLaneData = system.GetComponentLookup<AreaLane>(true),
    m_PrefabRefData = system.GetComponentLookup<PrefabRef>(true),
    m_PrefabObjectGeometryData = system.GetComponentLookup<ObjectGeometryData>(true),
    m_AreaNodes = system.GetBufferLookup<Game.Areas.Node>(true),

    m_StaticObjectSearchTree = staticTree,
    m_MovingObjectSearchTree = movingTree,
    m_TerrainHeightData = terrainHeightData,

    m_Entity = myEntity,
    m_CurrentPosition = currentPos,
    m_CurrentVelocity = currentVel,
    m_TargetPosition = desiredTargetPos,
    m_MinDistance = 1.0f,
    m_TimeStep = deltaTime,
    m_PrefabObjectGeometry = myPrefabGeometry,
    m_SpeedRange = new Bounds1(0f, maxAllowedSpeed),
    m_MaxSpeed = maxAllowedSpeed
};

// Run collision checks for a candidate lane:
iter.IterateFirstLane(candidateLane);

// After running, inspect iter.m_TargetPosition (may be adjusted),
// iter.m_MaxSpeed (may be reduced), and iter.m_Blocker (if set).

Additional notes: - The struct is performance-sensitive and intended for use inside the simulation update where native quadtrees and component lookups are valid. - All lookups and trees must be assigned with the correct read/write permissions appropriate to how the system executes (main thread vs job).