Skip to content

Game.Debug.PathfindDebugSystem

Assembly: Game (Cities: Skylines 2)
Namespace: Game.Debug

Type: class

Base: BaseDebugSystem

Summary:
PathfindDebugSystem is a debug visualization system for the game's pathfinding subsystem. It can draw the pathfinding graph (edges, nodes, midpoints), visualize active pathfind queries, and show cost / restriction information. It uses Unity's Job system (IJob / IJobParallelForDefer) and Burst-compiled jobs to read NativePathfindData and produce gizmo drawings via the GizmosSystem/GizmoBatcher. The system collects and maintains transient debug primitives (lines and nodes) in a NativeList, and exposes UI options to toggle graph drawing, restriction highlighting, and various cost components.

Fields

  • private PathfindQueueSystem m_PathfindQueueSystem
    Pathfind queue system reference used to read pathfind data, actions and to register data readers/writers for job dependency handling.

  • private GizmosSystem m_GizmosSystem
    Gizmos system reference used to obtain a GizmoBatcher for drawing debug geometry and to register gizmo writers.

  • private RenderingSystem m_RenderingSystem
    Rendering system reference used for frame delta (time) to animate/age gizmo lines.

  • private NativeList<PathfindLine> m_PathfindLines
    NativeList holding PathfindLine entries (owner entity, flags, timing info and Line3.Segment geometry). It is allocated with Allocator.Persistent and updated by jobs to accumulate gizmo lines to render.

  • private Option m_GraphOption
    Debug option controlling whether the path graph (edges/nodes) is drawn.

  • private Option m_RestrictedOption
    Debug option that toggles restricted-access coloring logic for edges (shows restrictions/authorization/enter/exit semantics).

  • private Option m_TimeCostOption
    Debug option to include time cost in cost-based edge coloring.

  • private Option m_BehaviorCostOption
    Debug option to include behavior cost in cost-based edge coloring.

  • private Option m_MoneyCostOption
    Debug option to include money cost in cost-based edge coloring.

  • private Option m_ComfortCostOption
    Debug option to include comfort cost in cost-based edge coloring.

  • private Option m_PathfindOption
    Debug option controlling visualization of active pathfind queries (start/end markers, connector lines, query results).

Properties

  • None (this system exposes no public properties).

Constructors

  • public PathfindDebugSystem()
    Default constructor. The system relies on OnCreate for initialization and adds Preserve attribute to lifecycle methods to ensure they are kept by code stripping.

Methods

  • protected override void OnCreate()
    Initializes references to PathfindQueueSystem, GizmosSystem and RenderingSystem from the ECS World, allocates the NativeList, registers debug options (Graph, Show Restrictions, cost options, Visualize Queries) and disables the system by default (base.Enabled = false). Marked with [Preserve].

  • protected override void OnDestroy()
    Disposes m_PathfindLines (NativeList) and calls base.OnDestroy. Marked with [Preserve].

  • protected unsafe override JobHandle OnUpdate(JobHandle inputDeps)
    Main update loop. If neither graph nor pathfind visualization options are enabled, returns the incoming dependencies early. Otherwise it:

  • Acquires NativePathfindData from the PathfindQueueSystem and combines its dependency.
  • If graph drawing is enabled, schedules an EdgeCountJob to read edge count and then schedules a Burst-compiled PathfindEdgeGizmoJob (IJobParallelForDefer) to draw edges/nodes/middle-connections. Uses a temporary NativeReference to pass the edge count to Schedule forEach count.
  • If pathfind visualization is enabled, it iterates over pending pathfind Actions from the PathfindQueueSystem, schedules FillPathfindGizmoLinesJob jobs to append pending start/end connector lines for debug, schedules SetPathfindGizmoLineFlagsJob when actions complete to mark lines as Failed/TooLong, and finally schedules PathfindLineGizmoJob to draw/animate the collected PathfindLine entries using the GizmoBatcher.
  • Registers job handles with PathfindQueueSystem and GizmosSystem where appropriate to ensure correct data access semantics. Marked with [Preserve] and uses unsafe code path for pointer-based scheduling of deferred parallel-for counts.

Notes on job types used (nested private structs): - PathfindLine: small struct representing a debug line / node with owner entity, flags, time (x=delay?, y,z used for timing/animation) and Line3.Segment geometry. - EdgeCountJob: reads NativePathfindData and writes the total edge count into a NativeReference. - PathfindEdgeGizmoJob: iterates edges and draws them colored by method/costs/restrictions; also draws endpoints and middle connections where applicable. - FillPathfindGizmoLinesJob: builds connector lines between start and end targets for pathfind actions and adds PathfindLine entries marked Pending. - SetPathfindGizmoLineFlagsJob: marks existing Pending PathfindLine entries for a specific owner entity with final flags (Failed) and TooLong marker. - PathfindLineGizmoJob: animates/ages PathfindLine entries and issues draw calls (lines, wire nodes, arrowheads) and prunes completed entries.

Threading / Safety considerations: - Uses Burst-compiled jobs and Native containers; m_PathfindLines is written by jobs scheduled from the main system and must be kept alive and disposed in OnDestroy. - The system adds readers/writers to PathfindQueueSystem and GizmosSystem to coordinate dependencies; when extending or calling similar APIs ensure to register appropriate readers/writers.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();

    // Typical initialization performed by the system:
    m_PathfindQueueSystem = base.World.GetOrCreateSystemManaged<PathfindQueueSystem>();
    m_GizmosSystem = base.World.GetOrCreateSystemManaged<GizmosSystem>();
    m_RenderingSystem = base.World.GetOrCreateSystemManaged<RenderingSystem>();
    m_PathfindLines = new NativeList<PathfindLine>(Allocator.Persistent);

    // Register debug options (these appear in the debug UI)
    m_GraphOption = AddOption("Draw Graph", defaultEnabled: true);
    m_RestrictedOption = AddOption("Show Restrictions", defaultEnabled: false);
    m_TimeCostOption = AddOption("Show time cost", defaultEnabled: false);
    m_BehaviorCostOption = AddOption("Show behavior cost", defaultEnabled: false);
    m_MoneyCostOption = AddOption("Show money cost", defaultEnabled: false);
    m_ComfortCostOption = AddOption("Show comfort cost", defaultEnabled: false);
    m_PathfindOption = AddOption("Visualize Queries", defaultEnabled: true);

    // The system starts disabled; enable it from debug UI or code when needed.
    base.Enabled = false;
}

Additional tips: - Toggle "Draw Graph" to see per-edge colors representing methods/costs or restriction states. - Toggle individual cost options (time/behavior/money/comfort) to influence the cost-based color scale used when graph coloring is enabled. - "Visualize Queries" will show connector lines for active pathfind requests and mark completed queries as green or failed as red/yellow (too long). - If you extend or reuse jobs, ensure you respect dependencies returned by GetDataContainer and GizmosSystem.GetGizmosBatcher, and always Dispose Native containers you allocate.