Skip to content

Game.Simulation.CarLaneSpeedIterator

Assembly:
Namespace: Game.Simulation

Type: struct

Base: System.ValueType

Summary:
CarLaneSpeedIterator is a helper/utility struct used by vehicle simulation to iterate along road/track lanes and compute the safe/drivable speed for a vehicle given lane geometry, other lane objects, signals, reservations and overlapping lanes. It inspects curve geometry, lane flags, lane signals, lane object buffers (cars, trains, pedestrians, parked vehicles), reservations and conditions to determine m_MaxSpeed, the nearest blocker (m_Blocker) and the blocker type (m_BlockerType). The iterator supports single-lane, lane-blend (between two lanes) and multi-next-lane navigation, checks parking lanes and overlapping lanes, and exposes helper methods to update speed when encountering other objects or targets.

Fields

  • public ComponentLookup<Transform> m_TransformData
    Lookup to get Transform (position/rotation) components for entities encountered during iteration.

  • public ComponentLookup<Moving> m_MovingData
    Lookup for Moving component (velocity etc.) used to compute object speeds and movement state.

  • public ComponentLookup<Car> m_CarData
    Lookup for Car component used to identify/inspect car-specific data.

  • public ComponentLookup<Train> m_TrainData
    Lookup for Train component used to identify/inspect train-specific data.

  • public ComponentLookup<Controller> m_ControllerData
    Lookup for Controller component (used to resolve controllers of lane objects).

  • public ComponentLookup<LaneReservation> m_LaneReservationData
    Lookup for lane reservation data (gives lane priority/offset reserved by vehicles).

  • public ComponentLookup<LaneCondition> m_LaneConditionData
    Lookup for dynamic lane conditions (construction, wetness, modifiers).

  • public ComponentLookup<LaneSignal> m_LaneSignalData
    Lookup for lane-level signals (stop/yield/traffic light state).

  • public ComponentLookup<Curve> m_CurveData
    Lookup for Curve components (Bezier geometry + length) of lanes.

  • public ComponentLookup<Game.Net.CarLane> m_CarLaneData
    Lookup for CarLane data (flags, speed limits, caution zones).

  • public ComponentLookup<Game.Net.ParkingLane> m_ParkingLaneData
    Lookup for ParkingLane data (parking slot layout, intervals).

  • public ComponentLookup<Unspawned> m_UnspawnedData
    Lookup to detect unspawned objects (e.g., not fully created entities).

  • public ComponentLookup<Creature> m_CreatureData
    Lookup to detect pedestrian/creature entities.

  • public ComponentLookup<PrefabRef> m_PrefabRefData
    Lookup mapping an entity to its prefab reference.

  • public ComponentLookup<ObjectGeometryData> m_PrefabObjectGeometryData
    Lookup for object geometry per prefab (bounds/size used for spacing).

  • public ComponentLookup<CarData> m_PrefabCarData
    Lookup for car prefab data (braking, physics).

  • public ComponentLookup<TrainData> m_PrefabTrainData
    Lookup for train prefab data (braking, bogie offsets).

  • public ComponentLookup<ParkingLaneData> m_PrefabParkingLaneData
    Lookup for parking-lane prefab parameters.

  • public BufferLookup<LaneOverlap> m_LaneOverlapData
    Buffer lookup containing lane overlap entries for a lane (parallel/merge/cross overlaps).

  • public BufferLookup<LaneObject> m_LaneObjectData
    Buffer lookup containing lane objects (vehicles, parked objects, pedestrians) for a lane.

  • public Entity m_Entity
    The vehicle entity for which speed is being calculated (controller or "self").

  • public Entity m_Ignore
    An entity to preferentially ignore in some checks (e.g., the vehicle's own trailer or attached object).

  • public NativeList<Entity> m_TempBuffer
    Temporary NativeList used during overlapping checks (e.g., roundabout traversal). Allocated when needed.

  • public int m_Priority
    Priority level of the vehicle (used against other vehicles' priorities and reservations).

  • public float m_TimeStep
    Simulation timestep used for dynamic computations.

  • public float m_SafeTimeStep
    Safer timestep used for conservative braking/safe distances.

  • public float m_DistanceOffset
    Extra distance offset added to braking distance calculations.

  • public float m_SpeedLimitFactor
    Factor applied to lane speed limits (global multipliers).

  • public float m_CurrentSpeed
    Current forward speed of the vehicle being simulated.

  • public CarData m_PrefabCar
    Prefab data for the vehicle that is navigating (braking, drive properties).

  • public ObjectGeometryData m_PrefabObjectGeometry
    Object geometry for the navigating vehicle (size/bounds for spacing).

  • public Bounds1 m_SpeedRange
    Allowed speed range (min/max) clamp for computed speeds.

  • public bool m_PushBlockers
    Flag indicating whether to treat slow/stopped objects as pushable/temporary blocking.

  • public float m_MaxSpeed
    Result: the computed maximum safe speed up to this point of iteration (initialized externally).

  • public float m_CanChangeLane
    Value used to indicate lane change availability; may be modified during checks.

  • public float3 m_CurrentPosition
    Current world position on the lane curve for the iterator.

  • public float m_Oncoming
    Value used to communicate oncoming danger factor (used for widening safety margins).

  • public Entity m_Blocker
    Result: the nearest blocking entity detected (if any).

  • public BlockerType m_BlockerType
    Result: type of the blocker (Limit, Continuing, Signal, Oncoming, Caution, Temporary, None, etc.).

  • private Entity m_Lane
    Internal: lane currently being inspected.

  • private Entity m_NextLane
    Internal: next lane in navigation chain.

  • private Curve m_Curve
    Internal: curve data for current lane.

  • private float2 m_CurveOffset
    Internal: current curve offsets (start/end) used for overlap checks.

  • private float2 m_NextOffset
    Internal: offset for next lane (used when checking merges/overlaps).

  • private float3 m_PrevPosition
    Internal: previous position sampled (used to compute distances and bounding times).

  • private float m_PrevDistance
    Internal: previous accumulated distance, used in delta calculations.

  • private float m_Distance
    Internal: accumulated travel distance used for braking computations.

Properties

  • None (this struct exposes only public fields and methods; state must be initialized directly).

Constructors

  • public CarLaneSpeedIterator()
    Default struct constructor. Important: CarLaneSpeedIterator is a value type — all ComponentLookup/BufferLookup references and mutable fields must be assigned/initialized before use. Typical initialization is done in a System's OnUpdate prior to calling any Iterate* methods (copy lookups, set m_Entity, m_PrefabCar, m_PrefabObjectGeometry, m_SpeedRange, m_MaxSpeed, m_Priority, m_TimeStep, m_SafeTimeStep, etc.).

Methods

  • public bool IterateFirstLane(Entity lane, float3 curveOffset, Entity nextLane, float2 nextOffset, float laneOffset, bool requestSpace, out Game.Net.CarLaneFlags laneFlags)
    Iterate along a single lane segment between curveOffset.x and curveOffset.z for a single source lane. Computes speed limits, checks lane caution ranges, updates m_MaxSpeed and blockers by inspecting the current lane and overlapping lanes. Returns whether the iterator has accumulated enough distance to begin braking or has reached the minimum speed. Outputs the lane's flags (masked to relevant bits).

  • public bool IterateFirstLane(Entity lane1, Entity lane2, float3 curveOffset, Entity nextLane, float2 nextOffset, float laneDelta, float laneOffset1, float laneOffset2, bool requestSpace, out Game.Net.CarLaneFlags laneFlags)
    Overload for lanes that blend between two lane curves (lane1/lane2). Interpolates positions and lane offsets by laneDelta (0..1), performs similar checks as the single-lane overload, including caution zones and overlaps on both lanes as appropriate. Updates m_MaxSpeed, blockers, and returns braking condition like above.

  • public bool IterateNextLane(Entity lane, float2 curveOffset, float minOffset, NativeArray<CarNavigationLane> nextLanes, bool requestSpace, ref Game.Net.CarLaneFlags laneFlags, out bool needSignal)
    Called when moving to the next lane region (curveOffset.x -> curveOffset.y). Handles lane signals, level crossings, stop/yield logic, parking lanes, reservations and checks space on next lanes (via CheckSpace). Updates m_NextLane/m_NextOffset from nextLanes, updates m_MaxSpeed and blocking entity/type. Returns braking condition. Outputs whether a signal check is required (needSignal) and can modify laneFlags passed in.

  • public void IterateTarget(float3 targetPosition)
    Convenience: iterate toward an arbitrary target position. Uses a default max lane speed computed from prefab data and passes to IterateTarget(targetPosition, maxLaneSpeed).

  • public void IterateTarget(float3 targetPosition, float maxLaneSpeed)
    Adds distance to m_Distance from current position to targetPosition and clamps m_MaxSpeed considering braking distance for the provided maxLaneSpeed and the safe stopping distance. Useful when the vehicle has a target point (end of navigation / obstacle) rather than a lane.

  • private bool CheckSpace(Entity currentLane, float2 curveOffset, NativeArray<CarNavigationLane> nextLanes, out Entity blocker)
    Checks if there is sufficient space in the requested next lane(s) for the vehicle to move into. Considers lane objects on the next lanes and the current lane, reservations, priorities and braking distances of other moving objects. Returns true if space is available (blocker = Entity.Null), otherwise sets blocker to the entity preventing entry and returns false.

  • private bool CheckOverlapSpace(Entity currentLane, float2 curCurvePos, Entity nextLane, float2 nextCurvePos, float2 overlapPos, out Entity blocker)
    Checks space in overlap regions where two lanes share geometry (merges/parallel). Evaluates lane objects in current and next lanes at overlap position, handles trains specially for attachment offsets, and uses braking distances to evaluate whether the overlap position is clear. Returns true if overlap is safe/clear; if not, returns false and sets blocker.

  • private void CheckParkingLane(float distance)
    Checks lane objects in a parking lane (stalls) and reduces m_MaxSpeed if a car is close to a parking vehicle/slot such that the navigating vehicle must slow/stop. Takes into account slot spacing, object sizes and special-case ignore behavior (m_Ignore entity). Sets m_Blocker and m_BlockerType accordingly.

  • private void CheckCurrentLane(float distance, float2 minOffset, bool inverse)
    Iterates current lane's lane-object buffer and updates speeds for objects ahead/behind depending on inverse/curve positions. Calls UpdateMaxSpeed for moving objects. Skips the entity itself and any attached controller children.

  • private void CheckCurrentLane(float distance, float2 minOffset, bool inverse, ref float canUseLane)
    Variant that also writes into canUseLane based on detected static lane objects and geometry — used to decide if a lane can be used for changing.

  • private void CheckOverlappingLanes(float origDistance, float origMinOffset, int yieldOverride, float speedLimit, bool isRoundabout, bool inverse, bool requestSpace)
    Core routine that checks all overlapping lanes (from m_LaneOverlapData) and their lane objects. Evaluates priorities, reservation offsets, yield/stop overrides (including lane signals), braking distances, and may call CheckOverlapSpace for complex merges. Updates m_MaxSpeed, m_Blocker and m_BlockerType accordingly. Handles special roundabout logic and builds a temporary buffer for multi-step roundabout sequences.

  • private float GetObjectSpeed(Entity obj, float curveOffset)
    Helper returning the component of a moving object's velocity along the tangent direction of the current curve at given curveOffset. Zero if the object has no Moving component.

  • private void CheckPedestrian(Line3.Segment overlapLine, Entity obj, float targetOffset, float distanceOffset, bool giveSpace, bool inverse)
    Special pedestrian (creature) checks for overlap collisions: evaluates lateral distance, facing direction and adjusts required braking speed. Sets m_MaxSpeed/m_Blocker/m_BlockerType (Temporary) if a pedestrian requires slowing/stopping.

  • private void UpdateMaxSpeed(Entity obj, BlockerType blockerType, float objectSpeed, float laneOffset, float distanceFactor, float distanceOffset, bool ignore, bool inverse1, bool inverse2, float3 currentPos)
    Generic routine used by many checks to compute braking distance and maximum safe speed when encountering another object. Handles trains (attach offsets) and prefabs, applies distance factoring for parallelism and overlap geometry, computes braking behavior based on both prefab braking values and vehicle braking, accounts for oncoming traffic (increasing oncoming metric), and updates m_MaxSpeed and blocker fields accordingly.

Usage Example

// Example (in a ComponentSystem/ISystem OnUpdate):
CarLaneSpeedIterator iter = new CarLaneSpeedIterator
{
    m_TransformData = GetComponentLookup<Transform>(true),
    m_MovingData = GetComponentLookup<Moving>(true),
    m_CarData = GetComponentLookup<Car>(true),
    m_TrainData = GetComponentLookup<Train>(true),
    m_ControllerData = GetComponentLookup<Controller>(true),
    m_LaneReservationData = GetComponentLookup<LaneReservation>(true),
    m_LaneConditionData = GetComponentLookup<LaneCondition>(true),
    m_LaneSignalData = GetComponentLookup<LaneSignal>(true),
    m_CurveData = GetComponentLookup<Curve>(true),
    m_CarLaneData = GetComponentLookup<Game.Net.CarLane>(true),
    m_ParkingLaneData = GetComponentLookup<Game.Net.ParkingLane>(true),
    m_UnspawnedData = GetComponentLookup<Unspawned>(true),
    m_CreatureData = GetComponentLookup<Creature>(true),
    m_PrefabRefData = GetComponentLookup<PrefabRef>(true),
    m_PrefabObjectGeometryData = GetComponentLookup<ObjectGeometryData>(true),
    m_PrefabCarData = GetComponentLookup<CarData>(true),
    m_PrefabTrainData = GetComponentLookup<TrainData>(true),
    m_PrefabParkingLaneData = GetComponentLookup<ParkingLaneData>(true),
    m_LaneOverlapData = GetBufferLookup<LaneOverlap>(true),
    m_LaneObjectData = GetBufferLookup<LaneObject>(true),

    m_Entity = vehicleEntity,
    m_Ignore = attachedEntity,
    m_Priority = vehiclePriority,
    m_TimeStep = Time.DeltaTime,
    m_SafeTimeStep = Time.DeltaTime * 0.75f,
    m_DistanceOffset = 0f,
    m_SpeedLimitFactor = 1f,
    m_CurrentSpeed = currentSpeed,
    m_PrefabCar = prefabCarData,
    m_PrefabObjectGeometry = prefabGeometry,
    m_SpeedRange = new Bounds1(minSpeed, maxSpeed),
    m_PushBlockers = false,
    m_MaxSpeed = float.MaxValue
};

// Iterate a lane segment (example)
Game.Net.CarLaneFlags laneFlags;
bool done = iter.IterateFirstLane(laneEntity, new float3(curveStart, curveEnd, 0), nextLaneEntity, new float2(0,0), laneOffset, requestSpace: true, out laneFlags);

// After iteration you can read iter.m_MaxSpeed, iter.m_Blocker, iter.m_BlockerType, iter.m_Oncoming etc.

Notes: - Proper initialization of all lookup fields is required before calling iteration methods. - The iterator mutates a number of its own public fields; treat it as a per-vehicle temporary struct used inside a single update tick.