Skip to content

Game.Routes.RouteUtils

Assembly:
Namespace: Game.Routes

Type: public static class

Base:

Summary:
Utility helper class containing constants and static functions used by the routing and public-transport subsystems. Provides helpers for waypoint distances and bounds, path adjustments around transport stops (including offsetting path targets into area lanes or edge lanes), boarding/exit decision logic, travel time averaging, departure scheduling, path method selection (taxi/public/road/track), option/mask helpers, and small helpers for vehicle/layout checks. Most methods operate on ECS data (ComponentLookup<...>, BufferLookup<...>, DynamicBuffer<...>) and are intended to be used from game systems (SystemBase/ISystem) or other mod code that runs during simulation.

Fields

  • public interface ITransportEstimateBuffer
    An interface for collecting wait-time estimates produced by StripTransportSegments. Implement this in a buffer or collector supplied to StripTransportSegments so it can call AddWaitEstimate(waypoint, seconds).

  • public const float WAYPOINT_CONNECTION_DISTANCE = 10f
    Typical max distance used when connecting waypoints.

  • public const float ROUTE_VISIBLE_THROUGH_DISTANCE = 100f
    Distance used for visibility-through checks for routes.

  • public const float TRANSPORT_DAY_START_TIME = 0.25f
    Normalized time-of-day fraction marking the start of transport "day" (0.25 -> 6:00 if 0..1 maps to 24h).

  • public const float TRANSPORT_DAY_END_TIME = 11f / 12f
    Normalized time-of-day fraction marking the end of transport day (11/12 -> 22:00).

  • public const float DEFAULT_TRAVEL_TIME = 1f / 48f
    Default travel time used when no other estimate exists.

  • public const float TAXI_DISTANCE_FEE = 0.03f
    Taxi fee per distance (game-specific scale).

Properties

  • None (static utility class).

Constructors

  • None (static class — no public constructors).

Methods

  • public static float GetMinWaypointDistance(RouteData routeData)
    Returns half of the configured snap distance for a route. Use when enforcing minimum spacing between waypoints.

  • public static Bounds3 CalculateBounds(Position waypointPosition, RouteData routeData)
    Calculate a Bounds3 around a waypoint position expanded by the route's snap distance.

  • public static Bounds3 CalculateBounds(CurveElement curveElement, RouteData routeData)
    Calculate bounds for a curve element expanded by the route's snap distance.

  • public static void StripTransportSegments<TTransportEstimateBuffer>(ref Unity.Mathematics.Random random, int length, DynamicBuffer<PathElement> path, ComponentLookup<Connected> connectedData, ComponentLookup<BoardingVehicle> boardingVehicleData, ComponentLookup<Owner> ownerData, ComponentLookup<Lane> laneData, ComponentLookup<Game.Net.ConnectionLane> connectionLaneData, ComponentLookup<Curve> curveData, ComponentLookup<PrefabRef> prefabRefData, ComponentLookup<TransportStopData> prefabTransportStopData, BufferLookup<Game.Net.SubLane> subLanes, BufferLookup<Game.Areas.Node> areaNodes, BufferLookup<Triangle> areaTriangles, TTransportEstimateBuffer transportEstimateBuffer) where TTransportEstimateBuffer : unmanaged, ITransportEstimateBuffer
    Walks a path buffer and strips or adjusts transport stop-related segments. It:

  • Removes intermediate connected waypoints contained inside a Connected block,
  • Offsets path targets into area lanes or edge lanes if a transport stop has an access distance,
  • Adds boarding-time estimates via the provided ITransportEstimateBuffer implementation,

  • Mutates the path (DynamicBuffer) in place and updates its length. This is the main helper to normalize paths around transport stops and to report expected waiting times.

  • private static void OffsetPathTarget_AreaLane(ref Unity.Mathematics.Random random, float distance, int elementIndex, DynamicBuffer<PathElement> path, ComponentLookup<Owner> ownerData, ComponentLookup<Curve> curveData, ComponentLookup<Lane> laneData, ComponentLookup<Game.Net.ConnectionLane> connectionLaneData, BufferLookup<Game.Net.SubLane> subLanes, BufferLookup<Game.Areas.Node> areaNodes, BufferLookup<Triangle> areaTriangles)
    Internal helper used by StripTransportSegments to find a target position inside an area (polygonal area made of triangles), pick a pedestrian sub-lane that intersects that sampled triangle, and replace/insert path elements so the path leads to that sub-lane. Uses random sampling biased by triangle area. Useful to see how area-type connections are resolved.

  • private static void OffsetPathTarget_EdgeLane(ref Unity.Mathematics.Random random, float distance, int elementIndex, DynamicBuffer<PathElement> path, ComponentLookup<Owner> ownerData, ComponentLookup<Lane> laneData, ComponentLookup<Curve> curveData, BufferLookup<Game.Net.SubLane> subLanes)
    Internal helper used by StripTransportSegments to offset a path target along the bezier curve (edge lane). Handles forward/backward offsets from a curve position, may traverse to previous/next lane if offset crosses the curve end, and updates/inserts path elements accordingly.

  • public static bool GetBoardingVehicle(Entity currentLane, Entity currentWaypoint, Entity targetWaypoint, uint minDeparture, ref ComponentLookup<Owner> ownerData, ref ComponentLookup<Connected> connectedData, ref ComponentLookup<BoardingVehicle> boardingVehicleData, ref ComponentLookup<CurrentRoute> currentRouteData, ref ComponentLookup<AccessLane> accessLaneData, ref ComponentLookup<Game.Vehicles.PublicTransport> publicTransportData, ref ComponentLookup<Game.Vehicles.Taxi> taxiData, ref BufferLookup<ConnectedRoute> connectedRoutes, out Entity vehicle, out bool testing, out bool obsolete)
    Determines whether there is a vehicle available to board at the given currentWaypoint for the passenger route toward targetWaypoint. Returns:

  • true and vehicle Entity if a (non-testing) vehicle is ready to board,
  • sets testing = true if only a testing vehicle matched,

  • sets obsolete = true when the waypoint/connection is no longer valid. Checks boarding vehicle components, connected lanes, route ownerships, public transport states (including departure frame constraints), and taxis. Intended to be called from passenger/route logic in systems.

  • public static bool ShouldExitVehicle(Entity nextLane, Entity targetWaypoint, Entity currentVehicle, ref ComponentLookup<Owner> ownerData, ref ComponentLookup<Connected> connectedData, ref ComponentLookup<BoardingVehicle> boardingVehicleData, ref ComponentLookup<CurrentRoute> currentRouteData, ref ComponentLookup<AccessLane> accessLaneData, ref ComponentLookup<Game.Vehicles.PublicTransport> publicTransportData, ref BufferLookup<ConnectedRoute> connectedRoutes, bool testing, out bool obsolete)
    Determines if a passenger currently on currentVehicle should exit for targetWaypoint. Uses boarding vehicle buffers to check whether the vehicle is the one expected for the route; checks public-transport state (en route), route ownership and connected routes. Returns true when the passenger should leave; sets obsolete when data indicates a mismatch/stale.

  • public static float UpdateAverageTravelTime(float oldTravelTime, uint departureFrame, uint arrivalFrame)
    Update a smoothed (exponential-like) average travel time for a route using a 0.5 lerp with the most recent measured trip time (arrival - departure). Frames are converted to minutes (/60f). If departureFrame==0 returns oldTravelTime unchanged.

  • public static float GetStopDuration(TransportLineData prefabLineData, TransportStop transportStop)
    Returns effective stop duration for a stop considering prefab default stop duration and the stop's loading factor (with a minimum loading factor of 0.25 to avoid division by small values).

  • public static uint CalculateDepartureFrame(TransportLine transportLine, TransportLineData prefabLineData, DynamicBuffer<RouteModifier> routeModifiers, float targetStopTime, uint lastDepartureFrame, uint simulationFrame)
    Calculates the next departure frame for a transport line. Factors used:

  • default vehicle interval (prefab),
  • route modifiers applied to vehicle interval,
  • vehicleInterval and unbunchingFactor from the current transportLine,

  • a targetStopTime is added and a minimum of 1 second is enforced. Returns simulationFrame + computedSeconds*60, or simulationFrame if lastDepartureFrame is in the future.

  • public static PathMethod GetPathMethods(RouteConnectionType routeConnectionType, RouteType routeType, TrackTypes trackTypes, RoadTypes roadTypes, SizeClass sizeClass)
    Maps route/connection types and other classification flags to a PathMethod bitmask used by the pathfinder (e.g., Road, Track, Pedestrian, Flying, Offroad, MediumRoad). Example: Air/road routes may include Flying when roadTypes include helicopter/airplane.

  • public static bool CheckOption(Route route, RouteOption option)
    Checks whether a given option bit is set in a Route's m_OptionMask.

  • public static bool HasOption(RouteOptionData optionData, RouteOption option)
    Checks whether an option is set in RouteOptionData's m_OptionMask.

  • public static void ApplyModifier(ref float value, DynamicBuffer<RouteModifier> modifiers, RouteModifierType type)
    Applies a route modifier (delta.x additive, delta.y multiplicative) to a value if modifiers has an entry for that type index. Used by departure calculation and other modifier-aware computations.

  • public static PathMethod GetTaxiMethods(Game.Creatures.Resident resident)
    Returns PathMethod.Taxi unless the resident has IgnoreTaxi flag set. Used to include/exclude taxi routing.

  • public static PathMethod GetPublicTransportMethods(float timeOfDay, float predictionOffset = 1f / 48f)
    Return PublicTransportDay or PublicTransportNight methods depending on normalized time-of-day (with optional prediction offset).

  • public static PathMethod GetPublicTransportMethods(Game.Creatures.Resident resident, float timeOfDay, float predictionOffset = 1f / 48f)
    Same as above but returns 0 (no transport) if resident has IgnoreTransport flag.

  • public static bool CheckVehicleModel(VehicleModel vehicleModel, PrefabRef prefabRef, DynamicBuffer<LayoutElement> layout, ref ComponentLookup<PrefabRef> prefabRefData)
    Checks whether a vehicle/prefab combination fits a VehicleModel constraint: primary prefab must match; if a secondary prefab is required, checks the vehicle layout buffer to see if the secondary is present. Returns true when model requirements are satisfied.

  • public static int GetMaxTaxiCount(WaitingPassengers waitingPassengers)
    Returns maximum number of taxis that should respond to waitingPassengers: formula 3 + (count + 3 >> 2). Useful for taxi dispatch logic.

Usage Example

// Example: determine path methods for a route and compute next departure time
PathMethod methods = RouteUtils.GetPathMethods(RouteConnectionType.Road, RouteType.Passenger, TrackTypes.None, RoadTypes.None, SizeClass.Medium);

// Compute averaged travel time after a trip
float newAvg = RouteUtils.UpdateAverageTravelTime(oldAvg, departureFrame, arrivalFrame);

// Calculate next departure frame (must be called from a simulation/system context)
uint nextDeparture = RouteUtils.CalculateDepartureFrame(
    transportLine,
    prefabLineData,
    routeModifiersBuffer,
    targetStopTime,
    lastDepartureFrame,
    simulationFrame
);

// NOTE: StripTransportSegments and other methods that take ComponentLookup/BufferLookup must be called
// from a system where those lookups are valid (e.g., SystemBase/ISystem Execute), and you must pass
// properly-initialized ComponentLookup<T> / BufferLookup<T> & DynamicBuffer<PathElement>.

Notes for modders: - Many functions operate directly on ECS types (ComponentLookup, BufferLookup, DynamicBuffer). Call them only from systems that have created/updated those lookups. - StripTransportSegments mutates path buffers in place and expects path elements and component lookups consistent with the game's ECS state. - Time-of-day methods use a normalized 0..1 range; typical game prediction offset is 1/48 (half an hour if 24h mapped to 48 ticks). - When using GetBoardingVehicle / ShouldExitVehicle, be prepared to handle the "obsolete" out param — it signals that cached route/waypoint data may be stale and the caller should recompute route decisions.