Skip to content

Game.Simulation.HumanNavigationSystem

Assembly:
Namespace: Game.Simulation

Type: public class HumanNavigationSystem : GameSystemBase

Base: GameSystemBase

Summary:
HumanNavigationSystem is the simulation system responsible for pedestrian (human/creature) navigation and behavior in Cities: Skylines 2. It: - Updates per-frame navigation targets, speeds and collision avoidance for human entities. - Manages group-following logic (Groups nested type) and lane-related actions and signals (Actions nested type). - Schedules Burst-compiled jobs (GroupNavigationJob, UpdateNavigationJob, UpdateLaneSignalsJob) to process large numbers of pedestrians in parallel using Unity's ECS/Jobs/Burst frameworks. - Uses multiple read-only ComponentLookup/BufferLookup and QuadTree search structures to find lanes, areas, static/moving objects and to compute lane/area targets, queues and blockers.

This system is central for modders who want to influence pedestrian routing, lane signals, blocking behavior or to hook into human navigation logic. Many of the data structures and lookups are internal/readonly and the work is performed in jobs — so modifications typically require either creating your own system or safely injecting data via supported Component/Owner/Signal structures.

Fields

  • private SimulationSystem m_SimulationSystem
    Reference to the global SimulationSystem (used to get frame index and other simulation timing info).

  • private CityConfigurationSystem m_CityConfigurationSystem
    Reference to city configuration (e.g., left/right hand traffic setting).

  • private Game.Net.SearchSystem m_NetSearchSystem
    Search tree provider for net (roads/lanes) queries. Used to obtain read-only net search tree for jobs.

  • private Game.Areas.SearchSystem m_AreaSearchSystem
    Search tree provider for area lanes/areas lookup.

  • private Game.Objects.SearchSystem m_ObjectSearchSystem
    Search tree provider for static/moving object queries.

  • private Actions m_Actions
    Nested Actions system instance. Manages lane object updater and a queue for lane signals used by jobs to request signal priorities.

  • private EntityQuery m_CreatureQuery
    EntityQuery used to select human entities that should be updated this frame.

  • private TypeHandle __TypeHandle
    Compiler-generated collection of component/handle references used to build jobs and lookups.

Properties

  • None (the system does not expose public properties).
    Note: most data is passed into jobs via ComponentLookup/BufferLookup and internal fields; modders should interact through ECS components, signals or their own systems rather than relying on internals.

Constructors

  • public HumanNavigationSystem()
    Default constructor (compiler generated, preserved). The system is typically created/managed by the World (GetOrCreateSystemManaged).

Methods

  • protected override void OnCreate()
    Initializes references to other systems (SimulationSystem, CityConfigurationSystem, net/area/object search systems), creates the Actions system and sets up the creature EntityQuery used to schedule pedestrian navigation jobs.

  • protected override void OnUpdate()
    Main update method. Picks the UpdateFrame slice (frameIndex % 16), sets a shared component filter on the creature query, prepares a NativeQueue for lane signals, gathers read-only search trees (net/static/moving/area) and schedules the Burst-compiled jobs:

  • UpdateNavigationJob (schedules in parallel for the creature query) — core pedestrian target/speed/collision/queue logic.
  • GroupNavigationJob (nested Groups class) is scheduled separately and handles group leader/follower path propagation.

  • UpdateLaneSignalsJob (nested in Actions) consumes lane signal queue and writes to LaneSignal components. This method wires job dependencies and registers jobs as readers on search systems so the search trees are safe to read concurrently.

  • protected override void OnCreateForCompiler()
    Compiler helper that assigns query and handle references for generated TypeHandle fields.

  • private void __AssignQueries(ref SystemState state)
    Compiler-generated helper (no-op here) used during system setup for query assignment.

  • Nested types and jobs of interest:

  • Groups (nested GameSystemBase): sets up m_CreatureQuery for group-specific handling and schedules GroupNavigationJob to update followers' path elements and leader flags.
  • Actions (nested GameSystemBase): holds LaneObjectUpdater and a NativeQueue to collect lane signal petitions from jobs, and schedules UpdateLaneSignalsJob which writes to LaneSignal components.
  • GroupNavigationJob (IJobChunk, BurstCompile): Copies/edits PathElement buffers and HumanCurrentLane for group members, handles leader/follower relationship and leader flags on path elements.
  • UpdateNavigationJob (IJobChunk, BurstCompile): The main, large job that:
    • Locates current lane if needed (TryFindCurrentLane).
    • Updates target positions and speeds based on lane type, signals, parking, taxi stands, areas and transform targets.
    • Handles action targets, area/triangle target selection, transform target calculations and collision/queue/blocker resolution via helper iterators (CreatureTargetIterator, CreatureCollisionIterator).
    • Emits lane signal petitions (enqueues lane signals) and updates lane-based flags and queues.
  • UpdateLaneSignalsJob (IJob): dequeues Signals and writes to LaneSignal components.

Notes about methods inside jobs (some examples): - TryFindCurrentLane(ref HumanCurrentLane currentLane, Game.Objects.Transform transform) — searches surrounding area and selects the best lane/area/hangaround location for the human. - UpdateNavigationTarget(...) — computes target position/direction, max speed, braking, target activity, handles leader/follower, collision iteration and final blocker/queue assignment. - MoveAreaTarget / MoveLaneTarget / MoveTransformTarget — helper routines for selecting targets within area lanes, lanes and transform/spawn/activity locations. - CalculateTargetPos(...) — converts curve/lane positions into world positions using curve and net lane data.

Usage Example

// Example: obtaining the system instance from a mod and ensuring it's created.
// Use within a MonoBehaviour or other system initialization code.
[UnityEngine.Scripting.Preserve]
void EnsureHumanNavigationSystemExists()
{
    // Get or create the system in the current World
    var world = Unity.Entities.World.DefaultGameObjectInjectionWorld;
    var humanNav = world.GetOrCreateSystemManaged<Game.Simulation.HumanNavigationSystem>();

    // humanNav is managed by the ECS world. Most modifications should be done by:
    // - Adding/updating ECS components on entities (Humans, Lanes, LaneSignal, Owner, etc.)
    // - Creating a separate system that runs after/before HumanNavigationSystem to inject or read data.
}

Additional modding tips: - HumanNavigationSystem relies heavily on read-only lookups, buffer data and quad trees. To influence human routing, consider: - Modifying LaneSignal components (LaneSignal.m_Petitioner / m_Priority) or providing your own lane reservation logic. - Updating Owner/Connected components or spawn/activity location data to change area targets. - Implementing a separate system that writes safe data (components or queued requests) and schedules before HumanNavigationSystem runs. - Avoid direct modification of private internals; instead use ECS components and standard game structures—jobs run Burst and expect data layout/consistency.