Skip to content

Game.SearchTreeDebugSystem

Assembly: Assembly-CSharp
Namespace: Game.Debug

Type: class

Base: BaseDebugSystem

Summary: SearchTreeDebugSystem is an in-game debug system used to visualize and inspect various spatial search trees (quadtrees / bounds trees) used by the engine. It schedules Burst-compiled jobs that iterate over native quadtrees for different subsystems (objects, nets, lanes, zones, areas, routes, effects, local effects) and draws wireframe rectangles using the GizmosSystem to indicate tree nodes and items. The system exposes toggle-able options (Static Objects, Moving Objects, Nets, Lanes, Zones, Areas, Routes, Effects, Local Effects) to control which search trees are visualized. It runs as a managed ECS system and uses job handles and reader/writer registration to coordinate with the underlying search systems and the GizmosSystem.

Fields

  • private Game.Objects.SearchSystem m_ObjectSearchSystem
    Used to access the static and moving object search trees (Game.Objects.SearchSystem). Retrieved in OnCreate.

  • private Game.Net.SearchSystem m_NetSearchSystem
    Used to access network-related search trees (nets, lanes).

  • private Game.Zones.SearchSystem m_ZoneSearchSystem
    Used to access the zone search tree (uses Bounds2 as item bounds).

  • private Game.Areas.SearchSystem m_AreaSearchSystem
    Used to access area search tree.

  • private Game.Routes.SearchSystem m_RouteSearchSystem
    Used to access route search tree.

  • private Game.Effects.SearchSystem m_EffectSearchSystem
    Used to access global effect source search tree.

  • private LocalEffectSystem m_LocalEffectSystem
    Used to access local (per-frame) effect search tree.

  • private GizmosSystem m_GizmosSystem
    Provides a GizmoBatcher for drawing wire rectangles and is registered as a writer when jobs use it.

  • private Option m_StaticObjectOption
    Option toggle controlling visualization of static objects search tree (default enabled).

  • private Option m_MovingObjectOption
    Option toggle controlling visualization of moving objects search tree (default enabled).

  • private Option m_NetOption
    Option toggle controlling visualization of nets search tree (default disabled).

  • private Option m_LaneOption
    Option toggle controlling visualization of lanes search tree (default disabled).

  • private Option m_ZoneOption
    Option toggle controlling visualization of zones search tree (default disabled).

  • private Option m_AreaOption
    Option toggle controlling visualization of areas search tree (default disabled).

  • private Option m_RouteOption
    Option toggle controlling visualization of routes search tree (default disabled).

  • private Option m_EffectOption
    Option toggle controlling visualization of global effects search tree (default disabled).

  • private Option m_LocalEffectOption
    Option toggle controlling visualization of local effects search tree (default disabled).

Additional nested types (not fields) used by the system: - NativeQuadTreeGizmoJob — a generic IJob that calls Iterate on a native quad tree with a supplied iterator. - QuadTreeBoundsXZ.DebugIterator (used) — iterator implementation for QuadTree bounds that draws gizmos. - Bounds2DebugIterator — an iterator specialized for Bounds2 (zones) that draws white node rects and red item rects. - LocalEffectDebugIterator — iterator for local effect items/bounds that draws gizmos for effect bounds.

Properties

  • This type has no public properties.

Constructors

  • public SearchTreeDebugSystem()
    Default constructor. The system is created and initialized by the ECS world; OnCreate performs the actual initialization of references and UI options.

Methods

  • protected override void OnCreate() : System.Void
    Initializes the system: obtains references to all relevant search systems (objects, net, zones, areas, routes, effects, local effects) and GizmosSystem from the ECS world, creates the Option toggles (Static Objects, Moving Objects, Nets, Lanes, Zones, Areas, Routes, Effects, Local Effects) with their default enabled states, and disables the debug system by default (base.Enabled = false). Marked with [Preserve] to avoid stripping.

  • protected override JobHandle OnUpdate(JobHandle inputDeps) : Unity.Jobs.JobHandle
    Main update that runs every frame while the system is enabled. It creates a Bounds3 representing an unbounded area, then for each enabled Option schedules a corresponding job to iterate the appropriate search tree and draw gizmos. Jobs are combined into a single returned JobHandle. For each scheduled job the method also registers the job handle as a reader with the corresponding search system and registers the gizmo batcher writer handle with the GizmosSystem.

  • private JobHandle StaticObjectSearchTreeDebug(JobHandle inputDeps, Bounds3 bounds) : Unity.Jobs.JobHandle
    Schedules a NativeQuadTreeGizmoJob to iterate the static object search tree (m_ObjectSearchSystem.GetStaticSearchTree) using QuadTreeBoundsXZ.DebugIterator. Registers the job as a static search tree reader and the GizmosSystem batcher as a writer.

  • private JobHandle MovingObjectSearchTreeDebug(JobHandle inputDeps, Bounds3 bounds) : Unity.Jobs.JobHandle
    Schedules a NativeQuadTreeGizmoJob to iterate the moving object search tree (m_ObjectSearchSystem.GetMovingSearchTree) using QuadTreeBoundsXZ.DebugIterator. Registers the job with the moving tree and gizmos writer.

  • private JobHandle NetSearchTreeDebug(JobHandle inputDeps, Bounds3 bounds) : Unity.Jobs.JobHandle
    Schedules a job to iterate the net search tree (m_NetSearchSystem.GetNetSearchTree) using QuadTreeBoundsXZ.DebugIterator.

  • private JobHandle LaneSearchTreeDebug(JobHandle inputDeps, Bounds3 bounds) : Unity.Jobs.JobHandle
    Schedules a job to iterate the lane search tree (m_NetSearchSystem.GetLaneSearchTree) using QuadTreeBoundsXZ.DebugIterator.

  • private JobHandle ZoneSearchTreeDebug(JobHandle inputDeps, Bounds3 bounds) : Unity.Jobs.JobHandle
    Schedules a job that iterates the zone search tree (m_ZoneSearchSystem.GetSearchTree) using the local Bounds2DebugIterator, which draws white node bounds and red item bounds for zone items.

  • private JobHandle AreaSearchTreeDebug(JobHandle inputDeps, Bounds3 bounds) : Unity.Jobs.JobHandle
    Schedules a job to iterate the area search tree (m_AreaSearchSystem.GetSearchTree) using QuadTreeBoundsXZ.DebugIterator.

  • private JobHandle RouteSearchTreeDebug(JobHandle inputDeps, Bounds3 bounds) : Unity.Jobs.JobHandle
    Schedules a job to iterate the route search tree (m_RouteSearchSystem.GetSearchTree) using QuadTreeBoundsXZ.DebugIterator.

  • private JobHandle EffectSearchTreeDebug(JobHandle inputDeps, Bounds3 bounds) : Unity.Jobs.JobHandle
    Schedules a job to iterate the global effect source search tree (m_EffectSearchSystem.GetSearchTree) using QuadTreeBoundsXZ.DebugIterator.

  • private JobHandle LocalEffectSearchTreeDebug(JobHandle inputDeps, Bounds3 bounds) : Unity.Jobs.JobHandle
    Schedules a job to iterate the local effect search tree (m_LocalEffectSystem.GetSearchTree) using LocalEffectDebugIterator which inspects LocalEffectSystem.EffectBounds and EffectItem and draws gizmos.

Nested / helper types and their important members:

  • NativeQuadTreeGizmoJob (private struct) : IJob
  • Fields:
    • [ReadOnly] NativeQuadTree m_Tree — the native quad tree to iterate (read-only).
    • TIterator m_Iterator — iterator instance passed to Iterate.

  • Methods:

    • void Execute() — calls m_Tree.Iterate(ref m_Iterator). Burst-compiled.

  • Bounds2DebugIterator (public struct) : INativeQuadTreeIterator, IUnsafeQuadTreeIterator

  • Constructor: Bounds2DebugIterator(Bounds2 bounds, GizmoBatcher gizmoBatcher) — stores the query bounds and gizmo batcher.
  • bool Intersect(Bounds2 bounds) — tests intersection against iterator's query bounds and draws a white wire rect for nodes that intersect.

  • void Iterate(Bounds2 bounds, TItem edgeEntity) — when an item is inside the query bounds, draws a red wire rect for the item bounds.

  • LocalEffectDebugIterator (public struct) : INativeQuadTreeIterator, IUnsafeQuadTreeIterator

  • Constructor: LocalEffectDebugIterator(Bounds2 bounds, GizmoBatcher gizmoBatcher)
  • bool Intersect(LocalEffectSystem.EffectBounds bounds) — checks intersection and draws white rect for effect bounds nodes.
  • void Iterate(LocalEffectSystem.EffectBounds bounds, LocalEffectSystem.EffectItem item) — draws red rects for intersecting local effect items.

Notes on threading/registration: - Each scheduled job obtains the native tree as read-only (Get...SearchTree(readOnly: true, out dependencies)) and the GizmoBatcher via m_GizmosSystem.GetGizmosBatcher(out dependencies2). The job is scheduled with dependencies combined and then the corresponding search system is informed of the reader job with Add...Reader(jobHandle). The GizmosSystem is informed with AddGizmosBatcherWriter(jobHandle). This ensures correct synchronization between writers/readers.

Usage Example

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

    // Obtain systems from the ECS world
    m_ObjectSearchSystem = base.World.GetOrCreateSystemManaged<Game.Objects.SearchSystem>();
    m_NetSearchSystem = base.World.GetOrCreateSystemManaged<Game.Net.SearchSystem>();
    m_ZoneSearchSystem = base.World.GetOrCreateSystemManaged<Game.Zones.SearchSystem>();
    m_AreaSearchSystem = base.World.GetOrCreateSystemManaged<Game.Areas.SearchSystem>();
    m_RouteSearchSystem = base.World.GetOrCreateSystemManaged<Game.Routes.SearchSystem>();
    m_EffectSearchSystem = base.World.GetOrCreateSystemManaged<Game.Effects.SearchSystem>();
    m_LocalEffectSystem = base.World.GetOrCreateSystemManaged<LocalEffectSystem>();
    m_GizmosSystem = base.World.GetOrCreateSystemManaged<GizmosSystem>();

    // Add options (these create toggles in the debug UI)
    m_StaticObjectOption = AddOption("Static Objects", defaultEnabled: true);
    m_MovingObjectOption = AddOption("Moving Objects", defaultEnabled: true);
    m_NetOption = AddOption("Nets", defaultEnabled: false);
    m_LaneOption = AddOption("Lanes", defaultEnabled: false);
    m_ZoneOption = AddOption("Zones", defaultEnabled: false);
    m_AreaOption = AddOption("Areas", defaultEnabled: false);
    m_RouteOption = AddOption("Routes", defaultEnabled: false);
    m_EffectOption = AddOption("Effects", defaultEnabled: false);
    m_LocalEffectOption = AddOption("Local Effects", defaultEnabled: false);

    // Disable the system by default; enable when needed from debug UI
    base.Enabled = false;
}

{{ This system is intended for debugging and visualization only. It relies on engine internals such as NativeQuadTree, GizmoBatcher and various SearchSystem implementations. When enabling / using it in mods, take care to respect the reader/writer registration patterns (Add...Reader / AddGizmosBatcherWriter) and schedule job dependencies correctly to avoid race conditions. }}