Game.PetAISystem
Assembly: Game.dll
Namespace: Game.Simulation
Type: class
Base: GameSystemBase
Summary:
PetAISystem is an Entity Component System (ECS) driven system responsible for pet / small-creature behaviour in the simulation. It updates creature state each tick (walking, queueing, boarding/disembarking vehicles), schedules burst-compiled jobs (PetTickJob and BoardingJob) to run logic in parallel, and enqueues boarding/disembarking work that is processed at the end of the frame. The system integrates with many parts of the simulation (vehicles, pathfinding/path owners, building owners, public transport, search tree for moving objects, city configuration) to make pets behave correctly in relation to vehicles and destinations. It is intended for modders who need to understand or extend pet movement and vehicle boarding logic in Cities: Skylines 2.
Fields
-
private EndFrameBarrier m_EndFrameBarrier
This EndFrameBarrier instance is used to create command buffers and to register job dependencies that must be completed before the frame ends. Boarding/finish actions are committed through command buffers produced by this barrier. -
private Game.Objects.SearchSystem m_ObjectSearchSystem
Reference to the object search system used for adding/removing moving objects to the world search tree when pets exit vehicles and become world objects. -
private CityConfigurationSystem m_CityConfigurationSystem
Used to read city configuration settings (e.g. left-hand traffic) needed when calculating vehicle door positions for boarding/exiting. -
private EntityQuery m_CreatureQuery
An entity query that selects Pet/Animal entities that the system will process on each update. The query is configured in OnCreate(). -
private EntityArchetype m_ResetTripArchetype
Archetype used to create ResetTrip events (ResetTrip entities) when a pet arrives at its destination and causes a reset for the trip. -
private ComponentTypeSet m_CurrentLaneTypes
Set of component types representing the movement/navigation components added/removed when a pet spawns/unspawns or leaves/enters a lane (Moving, AnimalNavigation, AnimalCurrentLane, etc). -
private TypeHandle __TypeHandle
Internal generated struct containing type and component lookup handles used to build and schedule the jobs. Populated in OnCreateForCompiler(). -
(nested)
private struct Boarding
Small struct used as messages enqueued into a NativeQueue to describe boarding-related operations (ExitVehicle, TryEnterVehicle, FinishEnterVehicle, CancelEnterVehicle). The queue is written in the parallel JobChunk (PetTickJob) and consumed by BoardingJob on the main thread / non-parallel job. -
(nested)
private enum BoardingType
Enum describing the boarding action type: Exit, TryEnter, FinishEnter, CancelEnter. -
(nested)
private struct PetTickJob : IJobChunk
Burst-compiled job that iterates creature chunks and executes the bulk of pet logic (walking, in-vehicle-checks, triggering boarding events). Writes boarding operations to a NativeQueue and uses a parallel EntityCommandBuffer. -
(nested)
private struct BoardingJob : IJob
Burst-compiled (non-parallel) job that consumes the boarding NativeQueue and applies the final changes (add/remove CurrentVehicle, add to passenger buffers, place pets on lane objects or search tree, add Unspawned/Updated, remove from lane, etc.) via an EntityCommandBuffer. -
(nested)
private struct TypeHandle
Compiler-generated container of many ComponentTypeHandle / ComponentLookup / BufferLookup fields used to fetch handles once and pass into the jobs. Assigned via __AssignHandles().
Properties
- (none public)
PetAISystem does not expose public properties. It relies on internal/private fields and the ECS query/job pipeline.
Constructors
public PetAISystem()
Default constructor (annotated with [Preserve]). Typical ECS system construction is handled by the World; modders will not generally instantiate this directly.
Methods
-
public override int GetUpdateInterval(SystemUpdatePhase phase)
Returns the update interval for this system. PetAISystem uses a lower frequency than every frame and returns 16, meaning it updates once every 16 frames (configurable per phase by this override). -
public override int GetUpdateOffset(SystemUpdatePhase phase)
Returns an update offset for scheduling. PetAISystem returns 5 which offsets when within the interval the system runs. -
protected override void OnCreate()
Initializes the PetAISystem: acquires EndFrameBarrier, ObjectSearchSystem and CityConfigurationSystem, constructs the entity query (m_CreatureQuery) selecting Pet/Animal entities, creates the ResetTrip archetype and defines m_CurrentLaneTypes. Also calls RequireForUpdate(m_CreatureQuery) to only run when there are matching entities. -
protected override void OnUpdate()
Main scheduling method. Creates a NativeQueue, constructs a PetTickJob and schedules it as a parallel JobChunk over m_CreatureQuery. Creates a BoardingJob that consumes the boarding queue and applies changes to the entity world (passengers buffers, search tree, CurrentVehicle components and lane components). Links job dependencies with internal search tree writers and the end frame barrier, disposes of the queue after completion, and updates base.Dependency with the composed job handle. -
protected override void OnCreateForCompiler()
Compiler-time helper which assigns internal query and type handles (calls __AssignQueries and __TypeHandle.__AssignHandles). Used by the generated code path to ensure all handles are ready. -
private void __AssignQueries(ref SystemState state)
Internal helper used by generated-code OnCreateForCompiler. Not intended for direct use. -
(nested job methods) PetTickJob.Execute / BoardingJob.Execute and many private helper methods inside these jobs: TickGroupMemberInVehicle, TickInVehicle, TickGroupMemberWalking, TickWalking, TickQueue, ExitVehicle (enqueues exit boarding), HasEveryoneBoarded, CheckTarget, CurrentVehicleBoarding, CurrentVehicleDisembarking, GroupLeaderDisembarking, PathEndReached, TryEnterVehicle, FinishEnterVehicle, CancelEnterVehicle.
These implement the core logic of pet movement, queuing, boarding/disembarking decisions, handling destroyed vehicles, public transport boarding states, vehicle controller indirection, adding/removing passengers and lane objects, and creating ResetTrip events for household pets arriving at their home.
Notes on behaviour:
- The job distinguishes pets inside CurrentVehicle (and group members) vs pets on the ground with AnimalCurrentLane.
- Boarding decisions are not executed immediately inside the parallel chunk job; they are enqueued to a NativeQueue
Usage Example
// Example: how a mod might access the PetAISystem and query its update interval.
// Note: adapt for the exact World accessor available in your mod environment.
using Unity.Entities;
using Game.Simulation;
public static class PetAIUtils
{
public static int GetPetSystemUpdateInterval(World world)
{
var petSystem = world.GetExistingSystemManaged<PetAISystem>();
if (petSystem == null) return -1;
// PetAISystem overrides GetUpdateInterval; call via type if needed.
return petSystem.GetUpdateInterval(SystemUpdatePhase.Simulation);
}
}
(For most modding tasks you will not subclass PetAISystem; instead, use its behaviour by modifying data components (e.g. CurrentVehicle, Target, AnimalCurrentLane) on pet entities, or by injecting behaviour via other systems that interact with vehicles, Owner or the search tree. If you need to alter boarding behavior, consider patching / replacing the nested job logic or enqueueing boarding operations compatible with the NativeQueue