Skip to content

Game.Debug.ZoneDebugSystem

Assembly: Game (Game.dll)
Namespace: Game.Debug

Type: class

Base: BaseDebugSystem

Summary:
ZoneDebugSystem is an editor/debugging ECS system used to visualize zoning information for Cities: Skylines 2. It draws gizmos for Blocks and VacantLots (pivots, grid lines and lot outlines) using a Burst-compiled IJobChunk (BlockGizmoJob). The system reads Block components and VacantLot dynamic buffers, queries zone prefab data to color lots by zone type, and submits draw calls through a shared GizmosSystem/GizmoBatcher. It registers required readers/writers with the ZoneSystem and GizmosSystem to safely schedule the job in the main update.

Fields

  • private EntityQuery m_BlockGroup
    Query that selects entities with Block components and excludes Deleted and Hidden components. Used to limit the job to existing blocks and to RequireForUpdate the system.

  • private GizmosSystem m_GizmosSystem
    Reference to the GizmosSystem instance (retrieved via World.GetOrCreateSystemManaged). Used to obtain a GizmoBatcher for drawing and to register the job as a writer.

  • private ZoneSystem m_ZoneSystem
    Reference to the ZoneSystem instance (retrieved via World.GetOrCreateSystemManaged). Used to access zone prefabs and to register the job as a prefab reader.

  • private Option m_PivotOption
    Debug option (added via AddOption) that toggles drawing of block pivot indicators. Default set in OnCreate (defaultEnabled: false).

  • private Option m_GridOption
    Debug option controlling drawing of block grid lines. Default enabled in OnCreate.

  • private Option m_LotOption
    Debug option controlling drawing of vacant lots. Default enabled in OnCreate.

  • private TypeHandle __TypeHandle
    Internal struct that caches ComponentTypeHandle / BufferTypeHandle / ComponentLookup handles needed by the job (Block, Temp, VacantLot, Error, ZoneData). __TypeHandle.__AssignHandles is called during OnCreateForCompiler to initialize handles.

  • private struct BlockGizmoJob (nested)
    Burst-compiled IJobChunk that performs the per-chunk gizmo drawing. It reads Block components and VacantLot buffers, Temp/Error markers and uses ZonePrefabs and ZoneData to determine colors. Submits draw calls through a GizmoBatcher instance.

  • Key fields inside BlockGizmoJob:

    • m_PivotOption, m_GridOption, m_LotOption (bools) — copies of the Option.enabled values to control behavior inside the job.
    • m_ZonePrefabs (ZonePrefabs) — to map vacant lot type to prefab index.
    • m_BlockType (ComponentTypeHandle) — read-only block component handle.
    • m_TempType (ComponentTypeHandle) — read-only temp/error marker handle.
    • m_VacantLotType (BufferTypeHandle) — read-only vacant lot dynamic buffer handle.
    • m_ErrorType (ComponentTypeHandle) — read-only error marker handle.
    • m_PrefabZoneData (ComponentLookup) — read-only lookup for ZoneData from prefabs.
    • m_GizmoBatcher (GizmoBatcher) — batcher used to emit wire lines/cubes/nodes.

  • Important methods:

    • Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask, in v128 chunkEnabledMask) — iterates chunk entities and draws pivots, grid lines and, when enabled, vacant lot wire cubes and corner/edge markers.
    • GetZoneColor(ZoneData zoneData) — maps AreaType to Color (Residential=green, Commercial=cyan, Industrial=yellow, default=white).

  • private struct TypeHandle (nested)
    Holds cached ComponentTypeHandle/BufferTypeHandle/ComponentLookup instances. Provides __AssignHandles(ref SystemState state) to acquire the handles from the SystemState (called in OnCreateForCompiler).

Properties

  • (none public)
    ZoneDebugSystem exposes no public properties. The debug toggles are stored in private Option fields created via AddOption; their enabled state is used when scheduling the job.

Constructors

  • public ZoneDebugSystem()
    Default constructor. The system is set up in OnCreate; base.Enabled is set to false by default so the system does not run until enabled explicitly (or by the debug UI).

Methods

  • protected override void OnCreate() : System.Void
    Initializes the system:
  • Retrieves GizmosSystem and ZoneSystem via World.GetOrCreateSystemManaged.
  • Builds the EntityQuery for blocks (Block, exclude Deleted/Hidden).
  • Adds debug options: "Draw Pivots" (default false), "Draw Grids" (default true), "Vacant Lots" (default true).
  • Calls RequireForUpdate(m_BlockGroup) to ensure the system updates only when blocks exist.

  • Sets base.Enabled = false to keep the system off by default.

  • protected override JobHandle OnUpdate(JobHandle inputDeps) : Unity.Jobs.JobHandle
    Schedules and returns the Burst-compiled BlockGizmoJob:

  • Prepares component handles via InternalCompilerInterface.GetComponentTypeHandle / GetBufferTypeHandle / GetComponentLookup using the cached __TypeHandle members and base.CheckedStateRef.
  • Obtains a GizmoBatcher from m_GizmosSystem.GetGizmosBatcher(out dependencies) and passes it into the job.
  • Schedules the job in parallel over m_BlockGroup via JobChunkExtensions.ScheduleParallel, combining the job's internal dependency with inputDeps.
  • Registers the returned jobHandle with m_ZoneSystem.AddPrefabsReader(jobHandle) to signal a read dependency on prefab data.
  • Registers with m_GizmosSystem.AddGizmosBatcherWriter(jobHandle) to indicate the job writes to the gizmo batcher.

  • Returns the scheduled job handle.

  • private void __AssignQueries(ref SystemState state) : System.Void
    Internal compiler helper; currently creates and disposes an EntityQueryBuilder (no-op in decompiled form). Called from OnCreateForCompiler.

  • protected override void OnCreateForCompiler() : System.Void
    Compiler helper override that calls __AssignQueries(ref base.CheckedStateRef) and __TypeHandle.__AssignHandles(ref base.CheckedStateRef) to ensure handles are initialized for the job.

  • private void __AssignHandles(ref SystemState state) (in TypeHandle) : System.Void
    Populates component/buffer/lookup handles: Block, Temp, VacantLot, Error, ZoneData as read-only handles. Called from OnCreateForCompiler.

  • BlockGizmoJob.Execute(...) (in BlockGizmoJob) : System.Void
    Core logic that:

  • Reads the Block array and VacantLot buffers from the chunk.
  • Chooses pen colors based on presence of Error/Temp components.
  • For each block, optionally draws pivot node (DrawWireNode) and grid lines (lines between calculated grid corners).

  • If lot drawing is enabled, iterates each VacantLot in the block's buffer and:

    • Computes lot world transform and scale.
    • Looks up the corresponding ZoneData via m_PrefabZoneData and m_ZonePrefabs to pick a zone color.
    • Draws a wire cube representing the maximum allowed building envelope (height limited by zone/m_MaxHeight and vacantLot height).
    • Draws small marker lines for corners/edges according to LotFlags.

  • BlockGizmoJob.GetZoneColor(ZoneData zoneData) : Color
    Helper to map zoneData.m_AreaType to a Color (Residential=green, Commercial=cyan, Industrial=yellow, default white).

Usage Example

// ZoneDebugSystem - OnCreate excerpt (already present in the system):
[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    m_GizmosSystem = base.World.GetOrCreateSystemManaged<GizmosSystem>();
    m_ZoneSystem = base.World.GetOrCreateSystemManaged<ZoneSystem>();
    m_BlockGroup = GetEntityQuery(ComponentType.ReadOnly<Block>(), ComponentType.Exclude<Deleted>(), ComponentType.Exclude<Hidden>());
    m_PivotOption = AddOption("Draw Pivots", defaultEnabled: false);
    m_GridOption = AddOption("Draw Grids", defaultEnabled: true);
    m_LotOption = AddOption("Vacant Lots", defaultEnabled: true);
    RequireForUpdate(m_BlockGroup);
    base.Enabled = false; // off by default
}

// Typical way to enable the debug system at runtime (example):
var world = World.DefaultGameObjectInjectionWorld;
var zoneDebug = world?.GetExistingSystemManaged<Game.Debug.ZoneDebugSystem>();
if (zoneDebug != null)
{
    zoneDebug.Enabled = true; // enable the system so it starts scheduling its gizmo job
    // Note: options (m_PivotOption/m_GridOption/m_LotOption) are private and exposed through the debug UI
    // The job will read their enabled state each frame and draw accordingly.
}

Notes for modders: - The actual drawing is performed inside a Burst-compiled IJobChunk; ensure any changes to components/handles are correctly registered via AddPrefabsReader / AddGizmosBatcherWriter or via the relevant system API to avoid race conditions. - Zone colors come from ZoneData.m_AreaType; to change color mapping adjust GetZoneColor in the nested job (or theme ZoneData). - The system relies on Block and VacantLot ECS data structures and on GizmosSystem/GizmoBatcher APIs to emit debug geometry.