Skip to content

Game.Simulation.ResidentAISystem

Assembly:
Namespace: Game.Simulation

Type: class

Base: GameSystemBase

Summary:
ResidentAISystem is the main simulation system responsible for resident (human) AI behavior in Cities: Skylines 2. It drives per-frame resident logic: walking and in-vehicle behavior, boarding and exiting vehicles, queue handling, divert/target selection (shopping, mail, safety, going home), pathfinding setup, and enqueuing related actions (boarding events, resident actions like GoShopping/SendMail). The system schedules Burst jobs (ResidentTickJob, BoardingJob, ResidentActionJob) to run in parallel and uses an inner Actions helper system to collect job-produced events (queues) which are then processed on the main thread or other systems via an EndFrameBarrier command buffer.

Fields

  • private EndFrameBarrier m_EndFrameBarrier
    The EndFrameBarrier system used to create command buffers and synchronize jobs that produce entity command buffers. ResidentAISystem uses it to obtain command buffers for its jobs and to add handles for producer synchronization.

  • private SimulationSystem m_SimulationSystem
    Reference to the SimulationSystem; used to read the current simulation frame index and coordinate per-frame scheduling.

  • private PathfindSetupSystem m_PathfindSetupSystem
    Reference to the PathfindSetupSystem; ResidentAISystem pushes pathfind setup items into this system's queue (via m_PathfindSetupSystem.GetQueue).

  • private TimeSystem m_TimeSystem
    Used to retrieve time-of-day information (normalized time) to alter behaviors (public transport availability, travel methods, etc).

  • private CityConfigurationSystem m_CityConfigurationSystem
    Used to read city-level configuration such as left-hand vs right-hand traffic.

  • private Actions m_Actions
    Inner helper system (nested class) instance. It contains native queues shared with jobs: m_BoardingQueue and m_ActionQueue and manages scheduling of BoardingJob and ResidentActionJob.

  • private PersonalCarSelectData m_PersonalCarSelectData
    Helper used for selecting/creating personal car trailers and configuring personal-car related pathfind parameters.

  • private EntityQuery m_CreatureQuery
    EntityQuery used to select resident entities (non-group members) that must be ticked this frame.

  • private EntityQuery m_GroupCreatureQuery
    EntityQuery used to select group-member residents (members of groups) and tick them (different logic when in a group).

  • private NativeArray<int> m_DeletedResidents
    Persistent array used to collect counters for different DeletedResidentType reasons (stuck loops, no path home, dead, etc). Marked with DebugWatchValue / EnumArray attribute for debugging.

  • private ComponentTypeSet m_ParkedToMovingCarAddTypes
    A component type set used when activating parked cars (components to add when a parked car transitions to moving).

(There are many more private fields in the class — the above are the most important for modders to know about.)

Properties

  • None (ResidentAISystem does not expose public properties).
    Most state and queues are private/internal; interaction is primarily through ECS components and events (command buffers, queues, and archetype events). Jobs and inner systems handle the majority of work.

Constructors

  • public ResidentAISystem()
    Default constructor. The system initializes in OnCreate — constructing helper data structures, queries, archetypes and persistent native arrays.

Methods

  • protected override void OnCreate()
    Initializes references to other systems (EndFrameBarrier, SimulationSystem, PathfindSetupSystem, TimeSystem, CityConfigurationSystem), creates EntityQueries, archetypes, ComponentTypeSets, and allocates persistent NativeArray counters such as m_DeletedResidents. Also constructs the PersonalCarSelectData helper.

  • protected override void OnDestroy()
    Disposes of any persistent native resources (for example m_DeletedResidents) created in OnCreate.

  • protected override void OnUpdate()
    Main scheduling function. Sets up shared component filters (UpdateFrame), creates/assigns the Actions' native queues, pre-updates personal-car helper, constructs and schedules the ResidentTickJob (parallel, twice — once for non-group members, once for group members), and schedules/coordinates BoardingJob and ResidentActionJob through the inner Actions system. It wires job dependencies into PathfindSetupSystem, EndFrameBarrier, and other systems that consume produced queues or buffers.

  • protected override void OnCreateForCompiler()
    Internal helper used by the generated code / compiler flow to assign queries and component handles. (Part of DOTS/ECS codegen pattern.)

  • private void __AssignQueries(ref SystemState state)
    Compiler-generated helper; sets up queries used by the system (empty in this generated file).

  • (Nested types / jobs)

  • public class Actions
    • Embedded helper-system that actually schedules BoardingJob and ResidentActionJob. Contains its own OnCreate and OnUpdate logic to set up auxiliary TypeHandles, EndFrameBarrier reference, object search system and other systems. It exposes NativeQueue m_BoardingQueue and NativeQueue m_ActionQueue used by the ResidentTickJob to enqueue events for processing.
  • private struct ResidentTickJob : IJobChunk (Burst compiled)
    • The per-resident chunked Burst job implementing most in-world resident behavior. Handles walking, in-vehicle logic, group-member vs single-member behavior, path checks, divert logic, waiting/queue handling, boarding decisions and enqueuing Boarding events and Pathfind setup work. Heavily optimized to run in parallel across chunks.
  • private struct BoardingJob : IJob (Burst compiled)
    • Processes the boarding queue (m_BoardingQueue). Handles TryEnter, FinishEnter, CancelEnter, Exit, RequireStop events, updates vehicle passenger buffers, free-space accounting and issues the final entity commands via an EntityCommandBuffer (m_CommandBuffer).

  • private struct ResidentActionJob : IJob (Burst compiled)

    • Processes the action queue (m_ActionQueue). Handles ResidentActionType.SendMail and ResidentActionType.GoShopping; updates MailBoxes, HouseholdNeed, and enqueues ResourceBought events via command buffer.

  • Utility methods (private, used inside ResidentTickJob and BoardingJob):

  • Path/target/divert helpers: SetDivert, SetTarget, FindNewPath, CheckPath, CheckLane, FindDivertTargets, AddPathAction, etc.
  • Vehicle/boarding helpers: TryEnterVehicle, FinishEnterVehicle, CancelEnterVehicle, ExitVehicle, FinishExitVehicle, TryFindVehicle, GetFreeSpace, GetPendingGroupMemberCount, RequireStop, WaitTimeExceeded, WaitTimeEstimate.
  • Movement/queue handling: TickWalking, TickInVehicle, TickGroupMemberWalking, TickGroupMemberInVehicle, ParkingSpaceReached, TransportStopReached, QueueReached, WaitHere, FindWaitingPosition, TryFindNextLane.
  • Misc helpers: UpdateMoodFlags, HandleHealthProblem, GetHomeBuilding, GetHousehold, GetTicketPrice, ActivateParkedCar, HasEveryoneBoarded, PathEndReached, ReachTarget and related reach-* handlers.

(There are many helper functions; modders reading this class should pay special attention to ResidentTickJob and BoardingJob implementations.)

Usage Example

Note: ResidentAISystem is an engine-managed ECS system. Most of its functionality is driven by the ECS world and scheduled jobs. As a modder you typically don't call its internals directly; instead you interact by adding/modifying components/entities, or by reading events it enqueues (queues/command buffers) if exposed. Example below shows how to obtain the system reference from a World and (non-recommended) illustrate access — most fields are private.

// Example: obtain the ResidentAISystem instance from the World.
// Use this for debugging/inspection only — do not rely on private internals.
var world = Unity.Entities.World.DefaultGameObjectInjectionWorld;
var residentAISystem = world.GetOrCreateSystemManaged<Game.Simulation.ResidentAISystem>();

// Typical modding usage: modify components on citizens/households/buildings so
// ResidentAISystem behavior changes (e.g., add HealthProblem, set TravelPurpose, etc.).
// Example (pseudo):
// entityManager.AddComponentData(residentCitizenEntity, new TravelPurpose { m_Purpose = Purpose.Shopping, m_Data = 1 });

Notes and tips for modders: - ResidentAISystem is highly performance-sensitive and uses Burst jobs and DOTS idioms; when adding features, prefer adding components/entities and letting the existing jobs react, or schedule your own jobs that cooperate via the same component types / queues. - Boarding and action events are communicated via NativeQueue and NativeQueue internal to the Actions helper. Those queues are private; to hook into boarding flow you typically modify vehicle/builder component data or provide new BoardingVehicle / Boarding-related components the system reads. - For pathfinding interventions, PathfindSetupSystem receives setup items from ResidentAISystem — you can inspect or extend that pipeline by adding systems that dequeue from PathfindSetupSystem's queue.