Skip to content

Game.Creatures.CreatureUtils

Assembly: Assembly-CSharp
Namespace: Game.Creatures

Type: static class

Base: System.Object

Summary:
Utility helpers used by creature (human and animal) systems for Cities: Skylines 2. Contains pathfinding checks and helpers, activity/location calculations, triangle/area target calculations, navigation/lane helpers, queue area helpers, path start/enter fixes for edge/area lanes, and other small math/geometry helpers used by creature movement and AI. Many helpers operate on ECS components, low-level path elements, curves and area geometry; intended for internal use by the creature systems but useful for modders implementing or diagnosing creature pathing and activity behaviour.

Fields

  • private struct ActivityLocationIterator
    Utility iterator (INativeQuadTreeIterator / IUnsafeQuadTreeIterator) used to search moving object quadtrees for collisions/intersections when evaluating activity start locations. Fields:
  • public Entity m_Ignore — entity to ignore during iteration (usually the creature itself).
  • public Line3.Segment m_Line — line segment used for intersection checks.
  • public ComponentLookup<Game.Objects.Transform> m_TransformData — transform lookup to test object positions.

  • public bool m_Found — set to true when an interfering object is found.

  • public const float MAX_HUMAN_WALK_SPEED
    Maximum walking speed constant for humans (5.555556f).

  • public const float AVG_HUMAN_WALK_SPEED
    Average human walking speed constant (1.6666667f).

  • public const float MIN_MOVE_SPEED
    Minimum allowed movement speed (0.1f).

  • public const float RESIDENT_PATHFIND_RANDOM_COST
    Random cost added to resident pathfinding (30f).

  • public const int MAX_TRANSPORT_WAIT_TICKS
    Maximum ticks a creature will wait for transport (5000).

  • public const int MAX_ENTER_VEHICLE_TICKS
    Maximum ticks allowed to enter a vehicle (250).

  • public const float QUEUE_TICKS_TO_SECONDS
    Conversion factor from queue ticks to seconds (2f / 15f).

Properties

  • None (static utility class; no public properties).

Constructors

  • N/A — static utility class (no instances).

Methods

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

  • public static bool EndReached(HumanCurrentLane currentLane)
    Checks whether the EndReached flag is set on the given human lane.

  • public static bool PathEndReached(HumanCurrentLane currentLane)
    Returns true if both EndOfPath and EndReached flags are set on a human current lane.

  • public static bool PathEndReached(AnimalCurrentLane currentLane)
    Returns true if both EndOfPath and EndReached flags are set on an animal current lane.

  • public static bool ParkingSpaceReached(HumanCurrentLane currentLane)
    True if the current lane indicates both EndReached and ParkingSpace.

  • public static bool ActionLocationReached(HumanCurrentLane currentLane)
    True if the current lane indicates both EndReached and Action.

  • public static bool TransportStopReached(HumanCurrentLane currentLane)
    True if the current lane indicates both EndReached and Transport.

  • public static bool RequireNewPath(PathOwner pathOwner)
    Checks whether the path is obsolete/divert obsolete and not pending/failed/stuck — indicates a new path should be requested.

  • public static bool IsStuck(PathOwner pathOwner)
    Checks PathFlags.Stuck on the path owner.

  • public static bool IsStuck(AnimalCurrentLane currentLane)
    Checks CreatureLaneFlags.Stuck on the animal lane.

  • public static bool ResetUncheckedLane(ref HumanCurrentLane currentLane)
    Sets the Checked flag on the lane if it was not set; returns true if the lane was previously unchecked.

  • public static void SetupPathfind(ref HumanCurrentLane currentLane, ref PathOwner pathOwner, NativeQueue<SetupQueueItem>.ParallelWriter queue, SetupQueueItem item)
    Prepares a PathOwner and current lane for pathfinding (cleans old flags, marks pending, enqueues setup item).

  • public static bool DivertDestination(ref SetupQueueTarget destination, ref PathOwner pathOwner, Divert divert)
    Handles divert logic for special purposes (mail, safety, escape, disappear, etc.) and updates destination/pathOwner flags. Returns whether divert was handled.

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

  • public static Game.Objects.Transform GetVehicleDoorPosition(ref Unity.Mathematics.Random random, ActivityType activityType, ActivityCondition conditions, Game.Objects.Transform vehicleTransform, float3 targetPosition, bool isDriver, bool lefthandTraffic, Entity creaturePrefab, Entity vehicle, DynamicBuffer<MeshGroup> meshGroups, ref ComponentLookup<Game.Vehicles.PublicTransport> publicTransports, ref ComponentLookup<Train> trains, ref ComponentLookup<Controller> controllers, ref ComponentLookup<PrefabRef> prefabRefs, ref ComponentLookup<CarData> prefabCarDatas, ref BufferLookup<ActivityLocationElement> prefabActivityLocations, ref BufferLookup<SubMeshGroup> subMeshGroupBuffers, ref BufferLookup<CharacterElement> characterElementBuffers, ref BufferLookup<SubMesh> subMeshBuffers, ref BufferLookup<Game.Prefabs.AnimationClip> animationClipBuffers, ref BufferLookup<AnimationMotion> animationMotionBuffers, out ActivityMask activityMask, out AnimatedPropID propID)
    Finds the most appropriate activity location on a vehicle (door enter/exit positions), considering public transport stops, car data, lefthand/right-hand traffic and activity masks. Returns a transform and outputs activity mask and prop id.

  • public static ActivityCondition GetConditions(Human human)
    Builds an ActivityCondition bitmask from the given Human flags (Homeless, Angry, Waiting, Sad, Happy).

  • public static bool CalculateTransformPosition(Entity creature, Entity creaturePrefab, DynamicBuffer<MeshGroup> meshGroups, ref Unity.Mathematics.Random random, ref Game.Objects.Transform result, ref ActivityType activity, CurrentVehicle currentVehicle, Entity entity, bool leftHandTraffic, ActivityMask activityMask, ActivityCondition conditions, NativeQuadTree<Entity, QuadTreeBoundsXZ> movingObjectSearchTree, ref ComponentLookup<Game.Objects.Transform> transforms, ref ComponentLookup<Position> positions, ref ComponentLookup<Game.Vehicles.PublicTransport> publicTransports, ref ComponentLookup<Train> trains, ref ComponentLookup<Controller> controllers, ref ComponentLookup<PrefabRef> prefabRefs, ref ComponentLookup<BuildingData> prefabBuildingDatas, ref ComponentLookup<CarData> prefabCarDatas, ref BufferLookup<ActivityLocationElement> prefabActivityLocations, ref BufferLookup<SubMeshGroup> subMeshGroupBuffers, ref BufferLookup<CharacterElement> characterElementBuffers, ref BufferLookup<SubMesh> subMeshBuffers, ref BufferLookup<Game.Prefabs.AnimationClip> animationClipBuffers, ref BufferLookup<AnimationMotion> animationMotionBuffers)
    Determines an appropriate world transform for a target entity for a creature (vehicle door, building front, activity location on a prefab, or raw transform/position). Returns true on success and may modify activity.

  • public static void GetAreaActivity(ref Unity.Mathematics.Random random, ref ActivityType activity, Entity laneEntity, ActivityMask activityMask, ComponentLookup<Owner> owners, ComponentLookup<PrefabRef> prefabRefs, ComponentLookup<SpawnLocationData> prefabSpawnLocationDatas)
    Chooses an activity for an area spawn location constrained by activityMask and the area's spawn location data.

  • public static bool SetTriangleTarget(float3 left, float3 right, float3 next, float3 comparePosition, PathElement nextElement, int elementIndex, DynamicBuffer<PathElement> pathElements, ref float3 targetPosition, float minDistance, float lanePosition, float curveDelta, float navigationSize, bool isSingle, ComponentLookup<Game.Objects.Transform> transforms, ComponentLookup<TaxiStand> taxiStands, ComponentLookup<AreaLane> areaLanes, ComponentLookup<Curve> curves)
    Calculates a target inside a triangle (used for net/area navigation) and sets targetPosition if the new target is at least minDistance away from comparePosition. Returns whether distance condition met.

  • private static float3 CalculateTriangleTarget(... ) (multiple overloads)
    Internal helper overloads that calculate a triangle-based target position given various inputs (by element, by lane offsets, or by min/max parameters). Used by SetTriangleTarget and area path logic.

  • public static bool SetAreaTarget(float3 prev2, float3 prev, float3 left, float3 right, float3 next, Entity areaEntity, DynamicBuffer<Game.Areas.Node> nodes, float3 comparePosition, PathElement nextElement, int elementIndex, DynamicBuffer<PathElement> pathElements, ref float3 targetPosition, float minDistance, float lanePosition, float curveDelta, float navigationSize, bool isBackward, ComponentLookup<Game.Objects.Transform> transforms, ComponentLookup<TaxiStand> taxiStands, ComponentLookup<AreaLane> areaLanes, ComponentLookup<Curve> curves, ComponentLookup<Owner> owners)
    Detailed area-aware target calculation combining triangle target logic with path element inspection and bounds. Returns whether target is sufficiently far, or true/false according to area rules.

  • private static float3 CalculateAreaTarget(float3 prev2, float3 prev, float3 left, float3 right, float3 comparePosition, float minDistance, float lanePosition, float navigationSize, out bool farEnough)
    Internal calculation for area target; sets farEnough to indicate if the produced target is at least minDistance away.

  • public static float GetNavigationSize(ObjectGeometryData prefabObjectGeometryData)
    Returns navigation size derived from object bounds (width along x axis).

  • public static float GetLaneOffset(ObjectGeometryData prefabObjectGeometryData, NetLaneData prefabLaneData, float lanePosition)
    Computes lane offset based on lane width and navigation size.

  • public static float3 GetLanePosition(Bezier4x3 curve, float curvePosition, float laneOffset)
    Gets a world position on a curve at curvePosition, offset laterally by laneOffset.

  • public static float GetMaxBrakingSpeed(HumanData prefabHumanData, float distance, float timeStep)
    Compute maximum speed that can be reduced to zero (given acceleration) over distance in one time step (and variants with maxResultSpeed).

  • public static float GetMaxBrakingSpeed(HumanData prefabHumanData, float distance, float maxResultSpeed, float timeStep)
    Variant that ensures result speed doesn't exceed given max.

  • public static float GetBrakingDistance(HumanData prefabHumanData, float speed, float timeStep)
    Braking distance formula for a human type.

  • public static float GetMaxBrakingSpeed(AnimalData prefabAnimalData, float distance, float timeStep)
    Same as Human overloads but for animals.

  • public static float GetMaxBrakingSpeed(AnimalData prefabAnimalData, float distance, float maxResultSpeed, float timeStep)
    Animal variant with max result speed.

  • public static float GetBrakingDistance(AnimalData prefabAnimalData, float speed, float timeStep)
    Braking distance for animals.

  • public static Sphere3 GetQueueArea(ObjectGeometryData prefabObjectGeometryData, float3 position)
    Returns a sphere area around an object position suitable for creature queuing.

  • public static Sphere3 GetQueueArea(ObjectGeometryData prefabObjectGeometryData, float3 position1, float3 position2)
    Returns a sphere that encloses two positions (useful for object queues spanning two points).

  • public static void SetQueue(ref Entity queueEntity, ref Sphere3 queueArea, Entity setEntity, Sphere3 setArea)
    Sets or merges queue areas; if entity matches, merges spheres, otherwise sets new entity and area.

  • public static void FixPathStart(ref Unity.Mathematics.Random random, float3 position, int elementIndex, DynamicBuffer<PathElement> path, ref ComponentLookup<Owner> ownerData, ref ComponentLookup<Lane> laneData, ref ComponentLookup<EdgeLane> edgeLaneData, ref ComponentLookup<Game.Net.ConnectionLane> connectionLaneData, ref ComponentLookup<Curve> curveData, ref BufferLookup<Game.Net.SubLane> subLanes, ref BufferLookup<Game.Areas.Node> areaNodes, ref BufferLookup<Triangle> areaTriangles)
    Fixes the starting element of a path to ensure creature starts on a valid lane/curve, delegating to area or edge lane helpers.

  • Private helpers: FixPathStart_AreaLane, FixPathStart_EdgeLane
    Internal routines used by FixPathStart to find best start lane/curve in area or edge scenarios and rewrite the path elements accordingly.

  • public static void FixEnterPath(ref Unity.Mathematics.Random random, float3 position, int elementIndex, DynamicBuffer<PathElement> path, ref ComponentLookup<Owner> ownerData, ref ComponentLookup<Lane> laneData, ref ComponentLookup<EdgeLane> edgeLaneData, ref ComponentLookup<Game.Net.ConnectionLane> connectionLaneData, ref ComponentLookup<Curve> curveData, ref BufferLookup<Game.Net.SubLane> subLanes, ref BufferLookup<Game.Areas.Node> areaNodes, ref BufferLookup<Triangle> areaTriangles)
    Similar to FixPathStart but tailored for entering a path (adjusts path elements to choose correct entering lane/curve).

  • Private helpers: FixEnterPath_AreaLane, FixEnterPath_EdgeLane
    Area/edge specific implementations for FixEnterPath.

  • public static void SetRandomAreaTarget(ref Unity.Mathematics.Random random, 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)
    Picks a random triangle within an area and builds a path to a random position inside that triangle (useful for random area destinations).

  • public static void CheckUnspawned(int jobIndex, Entity entity, HumanCurrentLane currentLane, Human human, bool isUnspawned, EntityCommandBuffer.ParallelWriter commandBuffer)
    Updates Unspawned and BatchesUpdated components for humans depending on lane flags and human flags (dead/carried etc.).

  • public static void CheckUnspawned(int jobIndex, Entity entity, AnimalCurrentLane currentLane, Animal animal, bool isUnspawned, EntityCommandBuffer.ParallelWriter commandBuffer)
    Animal variant of the CheckUnspawned helper.

Usage Example

// Example: utility usage for lane position and braking calculations
void ExampleUsage(ObjectGeometryData objectGeometry, NetLaneData laneData, Bezier4x3 curve, HumanData humanData)
{
    float lanePosNormalized = 0.0f; // -0.5..0.5 style depending on code usage
    float navigationSize = CreatureUtils.GetNavigationSize(objectGeometry);
    float laneOffset = CreatureUtils.GetLaneOffset(objectGeometry, laneData, lanePosNormalized);
    float3 worldLanePos = CreatureUtils.GetLanePosition(curve, 0.25f, laneOffset);

    // Compute braking info
    float distanceToObstacle = 5.0f;
    float timeStep = 0.02f; // game fixed timestep
    float maxBrakeSpeed = CreatureUtils.GetMaxBrakingSpeed(humanData, distanceToObstacle, timeStep);
    float brakingDistance = CreatureUtils.GetBrakingDistance(humanData, maxBrakeSpeed, timeStep);

    Debug.Log($"Lane pos: {worldLanePos}, MaxBrakeSpeed: {maxBrakeSpeed}, BrakingDistance: {brakingDistance}");

    // Quick path check
    // if (CreatureUtils.PathfindFailed(pathOwner)) { ... }
}

Notes for modders: - Most methods operate on ECS components and low-level path/curve/area data structures. Use in Jobs/Systems with the appropriate ComponentLookup/BufferLookup contexts.
- Several methods are tightly coupled with prefab buffers (ActivityLocationElement, MeshGroup, etc.) and public transport/train component data — use matching lookups when calling from systems.
- The area/triangle/curve helpers are useful when implementing custom spawn, navigation and activity-selection logic.