Skip to content

Game.Debug.NavigationDebugSystem

Assembly: Assembly-CSharp
Namespace: Game.Debug

Type: class

Base: BaseDebugSystem

Summary:
NavigationDebugSystem is a debug visualization system used by Cities: Skylines 2 to draw navigation gizmos for moving objects (cars, trains, watercraft, aircraft, humans and animals). It runs as a managed ECS system and schedules two Burst-compiled jobs to render per-entity navigation curves and to draw detailed information for the currently selected entity. The system exposes toggleable options (Humans, Animals, Cars, Trains, Ships, Aircrafts) for which categories of navigation to draw. It depends on GizmosSystem, SimulationSystem and ToolSystem and queries moving Game.Objects.Object entities that have navigation-related components.

Nested important types: - NavigationGizmoJob (IJobChunk, BurstCompile): draws navigation curves for chunks of entities in parallel. - SelectedNavigationGizmoJob (IJob, BurstCompile): draws detailed debug info for currently selected entity (lane costs, speed iteration, blockers, area triangles, etc.). - TypeHandle: internal structure to cache component/lookup handles used when scheduling jobs.

Fields

  • private EntityQuery m_NavigationQuery
    Used to select all Game.Objects.Object + Moving entities that also have at least one of the current-lane components (CarCurrentLane, TrainCurrentLane, HumanCurrentLane, WatercraftCurrentLane, AircraftCurrentLane, AnimalCurrentLane). Excludes Temp and Deleted.

  • private GizmosSystem m_GizmosSystem
    Reference to the game's GizmosSystem; used to obtain a GizmoBatcher for drawing lines/curves/wire shapes.

  • private SimulationSystem m_SimulationSystem
    Reference to the SimulationSystem for accessing simulation frame index and related simulation state when drawing selected entity details.

  • private ToolSystem m_ToolSystem
    Reference to the ToolSystem used to detect the currently selected entity (m_ToolSystem.selected).

  • private Option m_HumanOption
    UI option (toggle) for drawing human navigation gizmos. Default enabled in OnCreate.

  • private Option m_AnimalOption
    UI option (toggle) for drawing animal navigation gizmos. Default enabled in OnCreate.

  • private Option m_CarOption
    UI option (toggle) for drawing car navigation gizmos. Default enabled in OnCreate.

  • private Option m_TrainOption
    UI option (toggle) for drawing train navigation gizmos. Default enabled in OnCreate.

  • private Option m_WatercraftOption
    UI option (toggle) for drawing ship/watercraft navigation gizmos. Default enabled in OnCreate.

  • private Option m_AircraftOption
    UI option (toggle) for drawing aircraft navigation gizmos. Default enabled in OnCreate.

  • private TypeHandle __TypeHandle
    Internal container holding cached Entity/Component type handles and ComponentLookup/BufferLookup objects used by the jobs. Assigned in OnCreateForCompiler / __AssignHandles.

Properties

  • None (the system uses private fields and schedules jobs; configuration is via AddOption and system enable/disable).

Constructors

  • public NavigationDebugSystem()
    Default constructor. The system performs its full initialization in OnCreate (overrides) where it obtains required systems, builds the entity query and registers debug options. The constructor itself does not enable the system — OnCreate sets base.Enabled = false by default.

Methods

  • protected override void OnCreate() : System.Void
    Initializes the system: acquires GizmosSystem, SimulationSystem, ToolSystem, constructs m_NavigationQuery, adds UI options for Humans / Animals / Cars / Trains / Ships / Aircrafts and disables the system by default (base.Enabled = false). Marked with [Preserve] to avoid stripping.

  • protected override void OnUpdate() : System.Void
    Main update loop. If the navigation query is non-empty, schedules:

  • NavigationGizmoJob (parallel JobChunk) to draw non-selected entity navigation curves if relevant options are enabled.

  • SelectedNavigationGizmoJob (IJob) to render detailed debug info for the selected entity when m_ToolSystem.selected != Entity.Null. Jobs are combined and assigned into base.Dependency. Uses m_ToolSystem.selected to decide whether to schedule the selected-entity job.

  • private JobHandle DrawNavigationGizmos(EntityQuery group, JobHandle inputDeps) : JobHandle
    Prepares and schedules the NavigationGizmoJob over the provided EntityQuery. Populates the job struct with component type handles, component lookups and a gizmo batcher (m_GizmosSystem.GetGizmosBatcher). Adds the gizmo batcher writer and returns the scheduled job handle. The job draws curves and lines for each entity chunk based on enabled options and the current time offset.

  • private JobHandle DrawSelectedGizmos(JobHandle inputDeps) : JobHandle
    Prepares and schedules the SelectedNavigationGizmoJob to draw lane costs, speed iteration visualization and blockers for the selected entity. Populates many ComponentLookup/BufferLookup fields, passes the simulation frame index, and receives a GizmoBatcher. The job computes and draws detailed internal debug overlays (lane selection costs, lane speed iteration, area triangles, blockers as wire shapes, train pivot/curves, etc.).

  • private void __AssignQueries(ref SystemState state) : System.Void
    Internal helper used for compiler-generated setup. Keeps a placeholder EntityQueryBuilder usage; the real query is assigned in OnCreate.

  • protected override void OnCreateForCompiler() : System.Void
    Compiler helper invoked to assign queries and type handles during codegen / editor-time; calls __AssignQueries and __TypeHandle.__AssignHandles.

  • NavigationGizmoJob.Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask, in v128 chunkEnabledMask) : System.Void
    (IJobChunk implementation) Iterates entities in the chunk and draws navigation curves and connecting lines for each enabled vehicle/creature category. Uses component type handles and ComponentLookup to fetch bezier curves, cuts curve segments, and uses m_GizmoBatcher to draw lines, curves, and flowing curves. Handles lane change visualization and draws lines from object transform to lane start point.

  • NavigationGizmoJob.DrawNavigationCurve(Bezier4x3 curve, float totalLength, float timeOffset, UnityEngine.Color color, float2 curveDelta) : System.Void
    Helper used by NavigationGizmoJob to choose between a static DrawCurve or an animated DrawFlowCurve depending on the visible segment length.

  • SelectedNavigationGizmoJob.Execute() : System.Void
    (IJob implementation) Performs heavy per-selected-entity debugging: calculates lane selection costs for cars/watercraft, iterates lane speed logic for cars/watercraft/aircraft/trains, draws area lane triangles, draws blockers (wire boxes/cylinders) with color scaled by speed factor, draws lane curves and transitions, and visualizes train pivots and navigation lanes. Uses many ComponentLookup and BufferLookup references and temporary buffers/iterators to replicate internal routing logic for visualization.

  • SelectedNavigationGizmoJob.DrawBlocker(Entity blocker, float speedFactor) : System.Void
    Draws the visual representation of a blocking object (blocker) using the Prefab's ObjectGeometryData. Chooses a wire cylinder or cube, colors it interpolated between red and yellow based on speedFactor.

  • Many nested iterator/helper types are used by the SelectedNavigationGizmoJob (CarLaneSelectIterator, CarLaneSpeedIterator, WatercraftLaneSelectIterator, WatercraftLaneSpeedIterator, AircraftLaneSpeedIterator, TrainLaneSpeedIterator). These are internal constructs invoked inside the job to calculate and visualize lane costs and feasible speeds.

Notes: - Both jobs are Burst-compiled for performance and use ComponentTypeHandle / ComponentLookup / BufferLookup patterns compatible with Unity's ECS Jobs. - The system relies on m_GizmosSystem.GetGizmosBatcher to obtain a batcher; the batcher writer is registered so the jobs can draw safely from worker threads.

Usage Example

// Example: enable the NavigationDebugSystem from a mod initialization script
using Unity.Entities;
using Game.Debug;

public static class DebugEnable
{
    public static void EnableNavigationGizmos(World world)
    {
        // Acquire the managed system and enable it so options and drawing are active.
        var navSys = world.GetOrCreateSystemManaged<NavigationDebugSystem>();
        navSys.Enabled = true; // BaseDebugSystem exposes enabling; OnCreate initially sets Enabled = false.
    }
}

// Typical call (from a mod's initialization):
// EnableNavigationGizmos(World.DefaultGameObjectInjectionWorld);

Additional tips: - The system provides UI toggles (Humans, Animals, Cars, Trains, Ships, Aircrafts) created via AddOption in OnCreate. Toggle them in-game through the debug UI exposed by the BaseDebugSystem framework. - When an entity is selected (ToolSystem.selected), the system draws extra, detailed diagnostics for that entity (lane costs, predicted speeds, blocker geometry). This is useful for inspecting per-vehicle routing and lane selection behavior.