Skip to content

Game.Vehicles.VehicleUtils

Assembly: Assembly-CSharp
Namespace: Game.Vehicles

Type: static class

Base: System.Object

Summary:
Utility helper collection used by the game's vehicle systems (cars, trains, watercraft and aircraft). VehicleUtils centralizes constants (speed/length/priority thresholds), pathfinding and parking helpers, speed/braking math, lane/parking validation, train layout/rotation helpers, geometry helpers and a number of convenience methods for working with ECS components (ComponentLookup / BufferLookup / EntityCommandBuffer). Many methods are designed to be used inside Unity ECS Jobs and rely on ECS ComponentLookup/BufferLookup and Native containers. This file is essential for modders that need to interact with vehicle pathfinding, parking placement, braking/speed calculations or to implement custom vehicle behaviours.

Fields

  • public const float MAX_VEHICLE_SPEED
    Global hard limit for vehicle speeds. (277.77777f)

  • public const float MAX_CAR_SPEED
    Max car speed (111.111115f)

  • public const float MAX_TRAIN_SPEED
    Max train speed (138.88889f)

  • public const float MAX_WATERCRAFT_SPEED
    Max watercraft speed (55.555557f)

  • public const float MAX_HELICOPTER_SPEED
    Max helicopter speed (83.333336f)

  • public const float MAX_AIRPLANE_SPEED
    Max airplane speed (277.77777f)

  • public const float MAX_CAR_LENGTH
    Typical maximum car length used by logic (20f)

  • public const float PARALLEL_PARKING_OFFSET
    Offset used when parallel parking (1f)

  • public const float CAR_CRAWL_SPEED
    Crawling speed used in specific conditions (3f)

  • public const float CAR_AREA_SPEED
    Default car speed inside areas (11.111112f)

  • public const float MIN_HIGHWAY_SPEED
    Minimum speed considered for highways (22.222223f)

  • public const float MAX_WATERCRAFT_LENGTH
    Max watercraft length used for navigation (150f)

  • public const float WATERCRAFT_AREA_SPEED
    Default watercraft area speed (11.111112f)

  • public const float MAX_FIRE_ENGINE_EXTINGUISH_DISTANCE
    Max distance that fire engines will extinguish from (30f)

  • public const float MAX_POLICE_ACCIDENT_TARGET_DISTANCE
    Police accident target distance (30f)

  • public const float MAX_MAINTENANCE_TARGET_DISTANCE
    Maintenance vehicle target distance (30f)

  • public const uint MAINTENANCE_DESTROYED_CLEAR_AMOUNT
    Amount threshold used by maintenance logic (500u)

  • public const float MAX_TRAIN_LENGTH
    Max train length (200f)

  • public const float TRAIN_CRAWL_SPEED
    Train crawl speed (3f)

  • public const float MAX_TRAIN_CARRIAGE_LENGTH
    Max carriage length (20f)

  • public const float MAX_TRAM_CARRIAGE_LENGTH
    Max tram carriage length (16f)

  • public const float MAX_SUBWAY_LENGTH
    Max subway length (200f)

  • public const float MAX_SUBWAY_CARRIAGE_LENGTH
    Max subway carriage length (18f)

  • public const int CAR_NAVIGATION_LANE_CAPACITY
    Car nav lane capacity (8)

  • public const float MIN_HELICOPTER_NAVIGATION_DISTANCE
    Min distance for helicopter pathfinding (750f)

  • public const float MIN_AIRPLANE_NAVIGATION_DISTANCE
    Min distance for airplane pathfinding (1500f)

  • public const float AIRPLANE_FLY_HEIGHT
    Default airplane fly height (1000f)

  • public const float HELICOPTER_FLY_HEIGHT
    Default helicopter fly height (100f)

  • public const uint BOTTLENECK_LIMIT
    Bottleneck limit (50u)

  • public const uint STUCK_MAX_COUNT
    Max stuck count (100u)

  • public const int STUCK_MAX_SPEED
    Stuck max speed (6)

  • public const float TEMP_WAIT_TIME
    Temporary wait time used by some behaviours (5f)

  • public const float DELIVERY_PATHFIND_RANDOM_COST
    Random cost used by delivery pathfinding (30f)

  • public const float SERVICE_PATHFIND_RANDOM_COST
    Random cost used by service pathfinding (30f)

  • public const int PRIORITY_OFFSET
    Priority offset constant (2)

  • A set of priority constants (NORMAL_CAR_PRIORITY, EMERGENCY_CAR_PRIORITY, NORMAL_TRAIN_PRIORITY, PRIMARY_TRAIN_PRIORITY, SMALL_WATERCRAFT_PRIORITY, etc.)
    Used by vehicle routing/priority systems.

(Notes: the class contains many additional public const values. These are used by pathfinding, lane selection, parking and priority logic. Use them rather than hardcoding numbers in mod code.)

Properties

This static class does not expose properties.

Constructors

  • No public constructors (static class).
    Use directly: VehicleUtils.Method(...)

Methods

Below are the most relevant public static methods provided by VehicleUtils. Each method is documented with a short description and important usage notes where applicable.

  • public static bool PathfindFailed(PathOwner pathOwner)
    Returns true if the path owner has Failed or Stuck flags.

  • public static bool PathEndReached(CarCurrentLane currentLane)
    PathEndReached(TrainCurrentLane), PathEndReached(WatercraftCurrentLane), PathEndReached(AircraftCurrentLane)
    Helpers to test whether the end of path was reached for different vehicle types.

  • public static bool ReturnEndReached(TrainCurrentLane currentLane)
    Test for return flag on train lanes.

  • public static bool ParkingSpaceReached(CarCurrentLane currentLane, PathOwner pathOwner)
    ParkingSpaceReached(AircraftCurrentLane, PathOwner)
    Tests whether a parking space has been reached and the PathOwner is not pending.

  • public static bool WaypointReached(CarCurrentLane currentLane)
    Returns true if a waypoint was reached for car lanes.

  • public static bool QueueReached(CarCurrentLane currentLane)
    Returns true if a queue/queue reached flag is set.

  • public static bool RequireNewPath(PathOwner pathOwner)
    Returns true if a new path should be requested (Obsolete/Divert and not Pending/Failed/Stuck).

  • public static bool IsStuck(PathOwner pathOwner)
    Convenience check for Stuck flag.

  • public static void SetTarget(ref PathOwner pathOwner, ref Target targetData, Entity newTarget)
    Sets path target and marks path obsolete (clears Failed flag).

  • public static void SetupPathfind(...) (overloads for Car/Train/Watercraft/Aircraft)
    Prepares PathOwner and current lane for a pathfinding request and enqueue a SetupQueueItem into a NativeQueue. Typical usage inside pathfinding setup jobs.

  • public static bool ResetUpdatedPath(ref PathOwner pathOwner)
    Clears Updated flag and returns whether it was set.

  • public static Transform CalculateParkingSpaceTarget(Game.Net.ParkingLane parkingLane, ParkingLaneData parkingLaneData, ObjectGeometryData prefabGeometryData, Curve curve, Transform ownerTransform, float curvePos)
    CalculateParkingSpaceTarget(... out float3 position, out float3 forward, out float3 up)
    Compute world transform for parking slot given curve and slot parameters. Useful for spawning/positioning parked vehicles.

  • public static Transform CalculateTransform(Curve curve, float curvePos)
    Returns position and rotation (quaternion.LookRotationSafe) for a point on a curve.

  • public static int SetParkingCurvePos(Entity entity, ref Unity.Mathematics.Random random, CarCurrentLane currentLane, PathOwner pathOwner, DynamicBuffer<PathElement> path, ...)
    Traverses remaining path elements and sets curve position for the first parking lane found. Returns index or path.Length. Uses many component lookups and parking helpers.

  • public static void SetParkingCurvePos(DynamicBuffer<PathElement> path, PathOwner pathOwner, int index, Entity currentLane, float curvePos, ref ComponentLookup<Curve> curveData)
    Updates path buffer entries neighboring the changed curve position to keep distances consistent.

  • public static void ResetParkingLaneStatus(Entity entity, ref CarCurrentLane currentLane, ref PathOwner pathOwner, DynamicBuffer<PathElement> path, ...)
    Reapplies parking lane flags on current lane and updates path element parking curve positions. Intended to be used when car enters parking lane logic.

  • public static bool IsParkingLane(Entity lane, ref ComponentLookup<Game.Net.ParkingLane> parkingLaneData, ref ComponentLookup<Game.Net.ConnectionLane> connectionLaneData)
    Helper that checks both direct ParkingLane component or ConnectionLane flags.

  • public static bool IsCarLane(Entity lane, ref ComponentLookup<Game.Net.CarLane> carLaneData, ref ComponentLookup<Game.Net.ConnectionLane> connectionLaneData, ref ComponentLookup<Game.Objects.SpawnLocation> spawnLocationData, ref ComponentLookup<PrefabRef> prefabRefData, ref ComponentLookup<SpawnLocationData> prefabSpawnLocationData)
    Checks whether a lane is usable by cars (includes spawn locations and connection lanes with Road flag). Useful for custom lane selection.

  • public static void SetParkingCurvePos(DynamicBuffer<PathElement> path, PathOwner pathOwner, ref CarCurrentLane currentLaneData, DynamicBuffer<CarNavigationLane> navLanes, int navIndex, float curvePos, ref ComponentLookup<Curve> curveData)
    Overload for navigation lanes.

  • public static void CalculateTrainNavigationPivots(Transform transform, TrainData prefabTrainData, out float3 pivot1, out float3 pivot2)
    Returns front/back bogie pivot positions for trains (based on prefab offsets).

  • public static void CalculateShipNavigationPivots(Transform transform, ObjectGeometryData prefabGeometryData, out float3 pivot1, out float3 pivot2)
    Returns forward/back pivot points for ships.

  • public static bool CalculateTransformPosition(ref float3 position, Entity entity, ComponentLookup<Transform> transforms, ComponentLookup<Position> positions, ComponentLookup<PrefabRef> prefabRefs, ComponentLookup<BuildingData> prefabBuildingDatas)
    Fills a world position from either Transform or Position and handles special-case building front position.

  • public static float GetNavigationSize(ObjectGeometryData prefabObjectGeometryData)
    Returns lateral navigation size used to keep vehicles clear of obstacles.

  • Speed and braking helpers:

  • GetMaxDriveSpeed(CarData prefabCarData, Game.Net.CarLane carLaneData) and overload GetMaxDriveSpeed(CarData, float speedLimit, float curviness)
    Computes the max drivable speed for a vehicle on a lane given turning and curviness constraints.
  • ModifyDriveSpeed(ref float driveSpeed, LaneCondition condition)
    Reduce drive speed depending on lane wear.
  • GetMaxBrakingSpeed(...) overloads for Car, Train, Watercraft, Aircraft/Helicopter/Airplane variants (various signatures)
    Compute maximum speed that can be achieved while still being able to brake within a distance given braking/rate and timestep.
  • GetBrakingDistance(...) overloads for Car/Train/Watercraft/Aircraft/Helicopter/Airplane
    Returns braking distance for a given speed and timestep.

  • CalculateSpeedRange(...) overloads for Car/Train/Watercraft/Aircraft/Helicopter/Airplane
    Returns a Bounds1 (min/max) of speeds reachable next timestep considering acceleration and braking.

  • public static int GetPriority(Car carData) / GetPriority(TrainData) / GetPriority(WatercraftData) / GetPriority(AircraftData)
    Returns routing priority based on vehicle type/track type/size class.

  • Lane flags helpers:

  • public static Game.Net.CarLaneFlags GetForbiddenLaneFlags(Car carData)
  • public static Game.Net.CarLaneFlags GetPreferredLaneFlags(Car carData)
  • public static float GetSpeedLimitFactor(Car carData)

  • public static void GetDrivingStyle(uint simulationFrame, PseudoRandomSeed randomSeed, out float safetyTime)
    Returns a per-vehicle driving "safety time" (used to diversify behaviour).

  • Delivery/Buying trucks helpers:

  • public static int GetAllBuyingResourcesTrucks(Entity destination, Resource resource, ref ComponentLookup<DeliveryTruck> trucks, ref BufferLookup<GuestVehicle> guestVehiclesBufs, ref BufferLookup<LayoutElement> layoutsBufs)

  • public static int GetBuyingTrucksLoad(Entity vehicle, Resource resource, ref ComponentLookup<DeliveryTruck> trucks, ref BufferLookup<LayoutElement> layouts)

  • Transform/train helpers:

  • public static bool IsReversedPath(...)
    Checks if a train path is reversed and may need train reversal.
  • public static void ReverseTrain(Entity vehicle, DynamicBuffer<LayoutElement> layout, ref ComponentLookup<Train> trainData, ref ComponentLookup<TrainCurrentLane> currentLaneData, ref ComponentLookup<TrainNavigation> navigationData)
    Reverse a train layout and adjust all related current lane/navigation components.

  • public static void ReverseCarriage(...)
    Reverse single carriage.

  • public static float CalculateLength(Entity vehicle, DynamicBuffer<LayoutElement> layout, ref ComponentLookup<PrefabRef> prefabRefData, ref ComponentLookup<TrainData> prefabTrainData)
    Calculate total length of a train (sum of attach offsets).

  • public static void UpdateCarriageLocations(DynamicBuffer<LayoutElement> layout, NativeList<PathElement> laneBuffer, ref ComponentLookup<Train> trainData, ref ComponentLookup<ParkedTrain> parkedTrainData, ref ComponentLookup<TrainCurrentLane> currentLaneData, ref ComponentLookup<TrainNavigation> navigationData, ref ComponentLookup<Transform> transformData, ref ComponentLookup<Curve> curveData, ref ComponentLookup<Game.Net.ConnectionLane> connectionLaneData, ref ComponentLookup<PrefabRef> prefabRefData, ref ComponentLookup<TrainData> prefabTrainData)
    Recomputes transforms/positions for each carriage in a layout along the path described by laneBuffer. This is relatively complex but essential for train movement visuals and parked trains.

  • public static void ClearEndOfPath(ref CarCurrentLane currentLane, DynamicBuffer<CarNavigationLane> navigationLanes) and equivalents for Watercraft/Aircraft/Train
    Clear EndOfPath flags from the current lane or navigation lanes.

  • public static Entity ValidateParkingSpace(Entity entity, ref Unity.Mathematics.Random random, ref CarCurrentLane currentLane, ref PathOwner pathOwner, DynamicBuffer<CarNavigationLane> navigationLanes, DynamicBuffer<PathElement> path, ...)
    Validate available parking slots on the navigation lanes, updates validated flags and may mark the path obsolete or set end-of-path. Returns the lane used or Entity.Null if none found.

  • public static bool FindFreeParkingSpace(ref Unity.Mathematics.Random random, Entity lane, float minT, float parkingLength, float parkingOffset, ref float curvePos, ref ComponentLookup<ParkedCar> parkedCarData, ...)
    Core algorithm that scans a parking lane and its LaneObject buffer to find a free parking slot. Supports two modes:

  • PrefabParkingLane.m_SlotInterval != 0 (discrete slots)

  • continuous parking logic if SlotInterval == 0
    Returns whether at least one valid free slot was found and writes curvePos with selected position (randomized if many).

  • Geometry helpers:

  • public static float GetLaneOffset(ObjectGeometryData prefabObjectGeometryData, NetLaneData prefabLaneData, float lanePosition)
  • public static float3 GetLanePosition(Bezier4x3 curve, float curvePosition, float laneOffset)
  • public static float3 GetConnectionParkingPosition(Game.Net.ConnectionLane connectionLane, Bezier4x3 curve, float curvePosition)

  • public static Bounds3 GetConnectionParkingBounds(Game.Net.ConnectionLane connectionLane, Bezier4x3 curve)

  • Unspawned state helpers:

  • public static void CheckUnspawned(int jobIndex, Entity entity, CarCurrentLane currentLane, bool isUnspawned, EntityCommandBuffer.ParallelWriter commandBuffer) and overloads for Train/Aircraft/Watercraft
    Adds or removes Unspawned component depending on lane flags (Connection/ResetSpeed/TransformTarget/ParkingSpace). Useful when toggling visual spawning for vehicles in ECS jobs.

  • Path element helpers:

  • public static bool GetPathElement(int elementIndex, DynamicBuffer<CarNavigationLane> navigationLanes, NativeArray<PathElement> pathElements, out PathElement pathElement) and overload for WatercraftNavigationLane
    Read path element either from navigation lanes (first) or path elements array (afterwards).

  • Triangle/area navigation target calculations:

  • public static bool SetTriangleTarget(...) (several overloads)
    Compute a target point inside a navigation triangle used for navmesh-like movement for cars/watercraft. Returns whether the resulting target is farther than a minDistance from a compare position.

  • public static bool SetAreaTarget(...) (several overloads)
    Compute target inside an "area" lane (areas are used for plazas/parking lots etc) and checks distance.

  • public static void ClearNavigationForPathfind(Moving moving, CarData prefabCarData, ref CarCurrentLane currentLane, DynamicBuffer<CarNavigationLane> navigationLanes, ref ComponentLookup<Game.Net.CarLane> carLaneLookup, ref ComponentLookup<Curve> curveLookup)
    Clears/adjusts navigation segments to allow pathfinding to run given current speed/braking distance (used to prevent requesting new paths that would send vehicle through itself).

  • Lane/path method helpers:

  • public static bool CanUseLane(PathMethod methods, RoadTypes roadTypes, CarLaneData carLaneData)
    Checks if a lane is compatible with the path methods & road types.
  • public static PathMethod GetPathMethods(CarLaneData carLaneData)
  • public static PathMethod GetPathMethods(CarData carData)
  • public static PathMethod GetPathMethods(WatercraftData watercraftData)
  • public static PathMethod GetPathMethods(AircraftData aircraftData)
    Return allowed PathMethod enum flags based on vehicle/prefab size class.

(Notes: many methods accept and operate with ComponentLookup, BufferLookup, DynamicBuffer and Native containers. They were written to be used inside ECS job contexts and with Burst/Jobs in mind. Always ensure you respect the ECS access patterns and safety when calling from the main thread vs jobs.)

Usage Example

Example showing how to compute a parking target transform and calculate a maximum drive speed for a car:

// Example: compute a parking transform and speed limit inside a System or Job
// (assumes necessary ComponentLookup/BufferLookup/Curve/parking lane components are available)

float curvePos = 0.5f;
Transform parkingTarget = VehicleUtils.CalculateParkingSpaceTarget(
    parkingLane: parkingLaneComponent,
    parkingLaneData: prefabParkingLaneData,
    prefabGeometryData: prefabObjectGeometry,
    curve: curveComponent,
    ownerTransform: ownerTransform,
    curvePos: curvePos);

// Use a prefab car data + lane data to get the allowed max drive speed:
float maxDrive = VehicleUtils.GetMaxDriveSpeed(prefabCarData, laneData.m_SpeedLimit, laneData.m_Curviness);

// Example: inside a Job using ComponentLookup and Entity references, you might call:
if (VehicleUtils.FindFreeParkingSpace(ref rand, laneEntity, minT, parkingLength, parkingOffset, ref curvePos,
    ref parkedCarLookup, ref curveLookup, ref unspawnedLookup, ref parkingLaneLookup,
    ref prefabRefLookup, ref prefabParkingLaneLookup, ref prefabObjectGeometryLookup,
    ref laneObjects, ref laneOverlapLookup, ignoreDriveways: false, ignoreDisabled: false))
{
    // curvePos now contains a valid parking position on the lane
}

Additional notes for modders: - Many methods are intended for use in ECS Jobs and rely on ComponentLookup/BufferLookup/EntityCommandBuffer.ParallelWriter patterns. Attempting to call these helpers from outside the intended context may require wrapping or different lookups. - The parking and pathfinding helpers are sensitive to prefab data (ParkingLaneData, ObjectGeometryData, PrefabRef) and lane buffers (LaneObject, LaneOverlap). When creating custom lanes/prefabs, ensure these lookups are populated correctly. - Math uses Unity.Mathematics types (float3, quaternion, math.); pay attention to coordinate spaces (XZ vs full 3D) when integrating into rendering or physics. - Use existing constants (MAX_, PRIORITY_* etc.) instead of magic numbers to maintain compatibility with game logic.

If you want, I can generate a condensed quick-reference of the most frequently used methods and constants or produce a focus-specific doc (e.g., Parking API, Train helpers, Speed/Braking helpers) for easier consumption.