Game.CarNavigationSystem

Assembly: Assembly-CSharp
Namespace: Game.Simulation

Type: class

Base: GameSystemBase

Summary:
CarNavigationSystem is the ECS simulation system responsible for per-frame navigation and driving logic for cars. It performs lane selection, reservation, speed and target calculations, trailer handling, out-of-control handling, lane-side effects (wear, flow, pollution), lane signals and traffic ambience accumulation. The system is implemented with highly optimized Burst-compiled jobs (IJobChunk / IJob), native containers and quadtree search trees. It coordinates with several other systems (simulation, terrain, search trees, city configuration) and exposes a nested Actions helper class to collect and apply lane-related side-effects on the main thread. Modders should be careful when interacting with internals — most data is updated by jobs and thread-safety and native lifetime (Allocator.TempJob disposal) must be respected.

Fields

private SimulationSystem m_SimulationSystem
Reference to the global SimulationSystem used to obtain frame index and timing for navigation updates.
private TerrainSystem m_TerrainSystem
Used to sample terrain height during navigation target updates and area navigation.
private Game.Net.SearchSystem m_NetSearchSystem
Provides read access to the net search tree used when finding lanes and iterating nearby net elements.
private Game.Areas.SearchSystem m_AreaSearchSystem
Provides read access to the area search tree used for area lane queries.
private Game.Objects.SearchSystem m_ObjectSearchSystem
Provides read access to static and moving object search trees used for object interactions and lane/blocker checks.
private CityConfigurationSystem m_CityConfigurationSystem
Used to check settings like left-hand traffic which affect lane positioning.
private Actions m_Actions
Nested helper class instance. It contains the lane reservation/effects/signal queues and a LaneObjectUpdater used to apply lane-object changes after the parallel job finishes.
private EntityQuery m_VehicleQuery
EntityQuery used to select car entities for the navigation job (reads Car & UpdateFrame, writes CarCurrentLane, excludes Deleted/Temp/Parked/TripSource).
private TypeHandle __TypeHandle
Internal structure used to cache component/type handles for job scheduling.

Properties

None (the system exposes no public properties intended for external use)

Constructors

public CarNavigationSystem()
Default constructor (marked with Preserve). Typical Unity ECS / GameSystemBase construction — the system is instantiated by the world and initialized in OnCreate.

Methods

protected override void OnCreate() : System.Void
Initializes the system: obtains references to dependent systems (SimulationSystem, TerrainSystem, search systems, CityConfigurationSystem), creates the nested Actions helper, and constructs the EntityQuery used to select vehicles to update. This prepares component lookups and query filters used each frame.
protected override void OnUpdate() : System.Void
Main per-frame entrypoint. Key responsibilities:
Computes which subset of vehicles to update based on the simulation frame (UpdateFrame shared component filter).
Allocates NativeQueue(s) for lane reservations, lane effects, lane signals and traffic ambience (Allocator.TempJob) and hands parallel writers to the job.
Schedules the heavy-lifting Burst-compiled job UpdateNavigationJob (IJobChunk) to run in parallel across vehicle chunks. This job performs lane selection, target movement, blocker checks, trailer updates, reservation enqueuing, and enqueues lane side-effects / signals / ambience events.
Schedules smaller jobs to apply lane reservations, lane effects, lane signals and traffic ambience to component data (ApplyLaneEffectsJob, UpdateLaneReservationsJob, UpdateLaneSignalsJob, ApplyTrafficAmbienceJob).
Ensures proper disposal of temporary native containers using the scheduled job handles, and registers readers/writers with search systems where necessary (AddNetSearchTreeReader/AddWriter etc).
Stores job dependencies in the nested Actions helper (m_Actions.m_Dependency) so the Actions' LaneObjectUpdater can apply changes safely.
protected override void OnCreateForCompiler() : System.Void
Internal helper invoked for compilation-time initialization — assigns queries and component/type handles for the generated code paths. Not generally used by modders.
private void __AssignQueries(ref SystemState state) : System.Void
Internal helper used to create/assign entity queries at compiler-time. Implementation is a no-op placeholder in the decompiled source (creates an EntityQueryBuilder then disposes).
Nested job/struct types of interest:
UpdateNavigationJob (BurstCompile, IJobChunk): main navigation logic for each vehicle chunk, includes many helper methods such as TryFindCurrentLane, FillNavigationPaths, UpdateNavigationTarget, ReserveNavigationLanes, UpdateTrailers, ApplySideEffects, etc.
UpdateLaneSignalsJob (BurstCompile, IJob): dequeues lane signal requests and updates LaneSignal components.
UpdateLaneReservationsJob (BurstCompile, IJob): applies queued lane reservation proposals to LaneReservation components.
ApplyTrafficAmbienceJob (BurstCompile, IJob): accumulates traffic noise/ambience into the TrafficAmbience map.
ApplyLaneEffectsJob (BurstCompile, IJob): applies lane wear, flow and pollution updates from queued LaneEffects.
Actions (nested class): manages lane update queues, a LaneObjectUpdater and exposes Begin/Apply behavior to collect lane-object changes on the main thread.

Notes for modders: - Most useful extension points are to modify or inspect data consumed/produced by the system (LaneReservation, LaneCondition, LaneFlow, LaneSignal, CarCurrentLane, CarNavigation, LaneObject buffers, etc.). However these components are updated in jobs — direct manipulation must respect concurrency and job scheduling. - To influence navigation behavior, consider adding or modifying Prefab lane data, VehicleSideEffectData, or hook into lane signal/reservation components via separate systems that schedule after/before CarNavigationSystem appropriately. - The source contains many helper iterators and utility methods (CarLaneSelectIterator, VehicleCollisionIterator, CarLaneSpeedIterator, VehicleUtils, NetUtils, MathUtils) used by the navigation job — those offer smaller, safer extension points.

Usage Example

using UnityEngine.Scripting;
using Game.Simulation;

// Example: obtain the system from your mod system. The CarNavigationSystem runs automatically each simulation frame.
[Preserve]
public class MyModSystem : GameSystemBase
{
    protected override void OnCreate()
    {
        base.OnCreate();
        var carNav = World.GetOrCreateSystemManaged<Game.Simulation.CarNavigationSystem>();
        // You can schedule your own systems/jobs relative to carNav by reading SimulationSystem.frameIndex or
        // by using component data that CarNavigationSystem reads/writes. Do NOT modify its private queues directly.
    }

    protected override void OnUpdate()
    {
        // Custom mod logic here...
    }
}