Skip to content

Game.Debug.ObjectDebugSystem

Assembly: Game
Namespace: Game.Debug

Type: class

Base: BaseDebugSystem

Summary:
ObjectDebugSystem is an ECS debugging system used to draw gizmos for in-game objects (physical objects, markers, spawn locations, buildings/lots, groups, net connections, districts, etc.). It schedules a Burst-compiled IJobChunk (ObjectGizmoJob) that iterates object archetypes and issues drawing commands to a GizmoBatcher obtained from the GizmosSystem. The system exposes several toggleable options to control what is drawn (pivots, outlines, interpolated positions, net/group/district connections, lot heights). The system is disabled by default (base.Enabled = false) and depends on ToolSystem (for the currently selected entity) and GizmosSystem.

Fields

  • private EntityQuery m_ObjectGroup
    Used to query objects to debug/draw. The query requires Game.Objects.Object, Game.Objects.Transform, PrefabRef and excludes Deleted and Hidden.

  • private GizmosSystem m_GizmosSystem
    Cached reference to the GizmosSystem (used to obtain a GizmosBatcher to write draw commands from a job).

  • private ToolSystem m_ToolSystem
    Cached reference to the ToolSystem (used to obtain the currently selected entity for focused drawing).

  • private Option m_GeometryOption
    Toggleable option controlling drawing of physical object geometry.

  • private Option m_MarkerOption
    Toggleable option controlling drawing of marker objects.

  • private Option m_PivotOption
    Toggleable option controlling drawing of object pivots.

  • private Option m_OutlineOption
    Toggleable option controlling drawing of object outlines (wireframes, cylinder/cube leg markers).

  • private Option m_InterpolatedOption
    Toggleable option to draw interpolated positions (when InterpolatedTransform is present).

  • private Option m_NetConnectionOption
    Toggleable option to draw net/road connections for buildings, spawn points and attachments to nets.

  • private Option m_GroupConnectionOption
    Toggleable option to draw group leader/member connections.

  • private Option m_DistrictOption
    Toggleable option to draw connections from objects to their current district geometry center.

  • private Option m_LotHeightOption
    Toggleable option to draw lot height curves for building lots.

  • private TypeHandle __TypeHandle
    Compiler-generated container with all Entity/Component type handles and ComponentLookup handles used by the job. It provides an __AssignHandles method to populate those handles from a SystemState.

  • (Nested) private struct ObjectGizmoJob (BurstCompile, IJobChunk)
    The main job responsible for traversing chunks and issuing GizmoBatcher draw calls. It contains fields for all options, ComponentTypeHandles and ComponentLookups it needs, and implements Execute(in ArchetypeChunk, int, bool, in v128). The job performs all the logic for drawing pivots, outlines, interpolated transforms, stack-adjusted geometry, vehicle offsets, net connections, group connections, district lines and lot height curves. It uses helper methods GetVehicleTransform, GetAttachPosition, and overloaded DrawObject implementations to draw different object types and stacked objects.

  • The job reads components such as Game.Objects.Transform, Stack, Attached, ObjectGeometry, Game.Objects.Marker, Game.Objects.SpawnLocation, PrefabRef, InterpolatedTransform, Temp, CurrentVehicle, GroupMember, CurrentDistrict, Building, Game.Buildings.Lot and uses ComponentLookup for ObjectGeometryData, StackData, BuildingData, BuildingExtensionData, PrefabRef, Transform, Curve, Geometry, CurrentVehicle.

  • It uses GizmoBatcher to issue draw primitives: DrawWireNode, DrawLine, DrawWireCube, DrawWireCylinder, DrawCurve, DrawWireNode etc.

  • Vehicle/group logic: if CurrentVehicle is present, the job may offset objects relative to the vehicle transform (GetVehicleTransform) and draws connections between group leader and members.

  • Stack handling: when Stack and StackData exist for a prefab, the job modifies prefabObjectData values (size/bounds/legsize) for drawing to reflect stacked range/direction.

Properties

  • None (the system exposes no public properties; all state is private and configured via options added in OnCreate).

Constructors

  • public ObjectDebugSystem()
    Default constructor. Marked with [Preserve] attribute on lifecycle methods but the constructor itself is parameterless and generated as normal.

Methods

  • protected override void OnCreate()
    Initializes the system: caches references to GizmosSystem and ToolSystem, constructs m_ObjectGroup EntityQuery, adds all debug options with default values, and sets the system disabled by default (base.Enabled = false). This is where the toggleable Option instances are created:
  • "Physical Objects" (enabled)
  • "Marker Objects" (enabled)
  • "Draw Pivots" (enabled)
  • "Draw Outlines" (enabled)
  • "Interpolated Positions" (enabled)
  • "Net Connections" (enabled)
  • "Group Connections" (enabled)
  • "District Connections" (disabled)

  • "Lot Heights" (disabled)

  • protected override void OnUpdate()
    Checks if the object query is empty; if not empty schedules drawing by calling DrawObjectGizmos and assigns the returned JobHandle to base.Dependency.

  • private JobHandle DrawObjectGizmos(EntityQuery group, JobHandle inputDeps)
    Prepares and schedules the ObjectGizmoJob using JobChunkExtensions.ScheduleParallel. Populates the job's fields from the system state (option enabled flags, component type handles and component lookups via InternalCompilerInterface and __TypeHandle). Obtains a GizmosBatcher from m_GizmosSystem.GetGizmosBatcher(out dependencies) and combines dependencies before scheduling. Adds a writer handle to the GizmosSystem and returns the scheduled JobHandle.

  • private void __AssignQueries(ref SystemState state)
    Compiler-generated helper used in OnCreateForCompiler to set up queries. In this implementation it simply constructs and disposes a temporary EntityQueryBuilder; __TypeHandle.__AssignHandles is also invoked elsewhere to populate component handles.

  • protected override void OnCreateForCompiler()
    Compiler helper override to call __AssignQueries(ref base.CheckedStateRef) and __TypeHandle.__AssignHandles(ref base.CheckedStateRef). Enables the job type handles when compiling the system.

  • (ObjectGizmoJob methods)

  • Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask, in v128 chunkEnabledMask) — core logic to iterate chunk entities and draw gizmos depending on the enabled options and components present in the chunk.
  • GetVehicleTransform(Entity entity, CurrentVehicle currentVehicle, ObjectGeometryData prefabObjectData, ref Game.Objects.Transform transform) — adjusts transform for objects that are on vehicles (random offset inside vehicle size to spread objects).
  • GetAttachPosition(Attached attached, out float3 attachPosition) — resolves attach position on a net curve (returns true if parent is a net curve).
  • DrawObject overloads — two variants to draw an object's pivot and outline based on ObjectGeometryData (simple) or Stack + StackData (stack-aware). They draw standing legs as cylinders or cubes depending on flags and approximate bounding box/cylinder for object body.

Usage Example

// Example usage (typical in Cities: Skylines 2 modding context):
// The system is created by the ECS world; you can obtain and enable it like this:

var objDebug = World.DefaultGameObjectInjectionWorld.GetOrCreateSystemManaged<Game.Debug.ObjectDebugSystem>();
// enable the system if you want it active
objDebug.Enabled = true;

// Options are internal Option objects added in OnCreate. They are typically exposed
// through an in-game debug UI; direct programmatic toggle isn't public in this type.
// The system uses GizmosSystem and ToolSystem to draw debug gizmos when scheduled.

Notes: - The ObjectGizmoJob is Burst-compiled and scheduled in parallel for performance. - The job uses ComponentLookup (accessible from the SystemState) to read additional prefab and geometry metadata required to draw accurate gizmos. - The system avoids drawing when the entity query is empty (m_ObjectGroup.IsEmptyIgnoreFilter).