Game.Debug.GarbageDebugSystem
Assembly: Game (assembly name inferred from project layout)
Namespace: Game.Debug
Type: class
Base: BaseDebugSystem
Summary: GarbageDebugSystem is a debug/visualization system used by Cities: Skylines 2 modding framework to draw gizmos for building-related garbage data. The system finds buildings that have a GarbageProducer and Transform, and can display: - accumulated garbage stored in the building (as a vertical wire-cube), - the per-prefab garbage production/consumption rate (also as a vertical wire-cube).
It offloads drawing to a parallel IJobChunk (GarbageGizmoJob) and uses the engine's GizmosSystem to batch gizmo draws. The job reads GarbageParameterData (singleton) to compute heights and coloring thresholds. The system registers two UI options to toggle the two visualization modes (Accumulated Garbage and Produce Garbage). The system is disabled by default (base.Enabled = false) and must be enabled manually.
Fields
private EntityQuery m_BuildingGroup
Contains the query that matches buildings with the required components:- ReadOnly Building
- ReadOnly Game.Objects.Transform
-
ReadOnly GarbageProducer
Entities with Deleted, Temp or Hidden are excluded. -
private GizmosSystem m_GizmosSystem
Reference to the GizmosSystem used to obtain a GizmoBatcher for rendering wire-cubes and to register the job as a writer of gizmo batches. -
private Option m_AccumulatedOption
Toggle option (added via AddOption) controlling whether accumulated garbage per building is drawn. Default enabled (true), but the whole system is disabled by default. -
private Option m_ProduceOption
Toggle option controlling whether per-prefab garbage production/consumption is drawn. Default enabled (true). -
private TypeHandle __TypeHandle
Holds ComponentTypeHandle and ComponentLookup instances used by the scheduled job; populated by __AssignHandles in the nested TypeHandle struct during compiler-time initialization. -
(Nested)
private struct GarbageGizmoJob
A Burst-compiled IJobChunk that: - Reads PrefabRef, GarbageProducer, Game.Objects.Transform, and a ComponentLookup
. - Reads a GarbageParameterData singleton.
- Has flags m_AccumulatedOption and m_ProduceOption to turn drawing modes on/off.
- Uses a GizmoBatcher to draw wire cubes representing garbage height and color.
- DrawGarbage: draws cube scaled by accumulated garbage and colors between green and red depending on thresholds.
- DrawConsume: draws cube scaled by consumption value and colors based on value magnitude.
-
Execute: iterates chunk arrays and calls the appropriate draw methods depending on toggles.
-
(Nested)
private struct TypeHandle
Provides read-only ComponentTypeHandle/ComponentLookup fields for: - GarbageProducer
- PrefabRef
- Game.Objects.Transform
- ConsumptionData (ComponentLookup)
It has an __AssignHandles(ref SystemState state) method to initialize the handles from the current SystemState (GetComponentTypeHandle / GetComponentLookup).
Properties
- This class exposes no public properties. All relevant state is private fields and nested structs used for job scheduling and drawing.
Constructors
public GarbageDebugSystem()
Default constructor. The system uses OnCreate to perform initialization; the constructor only exists to satisfy the runtime and compiler expectations and is annotated with [Preserve] for linker safety.
Methods
protected override void OnCreate()
Initializes the system:- Retrieves/creates the GizmosSystem instance from the World.
- Creates the m_BuildingGroup EntityQuery that matches Building + Transform + GarbageProducer, excluding Deleted, Temp and Hidden.
- Sets base.Enabled = false (system is disabled by default).
-
Registers two options via AddOption: "Accumulated Garbage" and "Produce Garbage" (both default enabled). This method is annotated [Preserve].
-
protected override void OnUpdate()
If the building query is not empty: - Builds a GarbageGizmoJob instance and populates its handles using InternalCompilerInterface.GetComponentTypeHandle / GetComponentLookup and other fields.
- Obtains a GizmoBatcher from m_GizmosSystem (which returns an additional JobHandle dependency).
- Reads the GarbageParameterData singleton to configure job drawing logic.
- Schedules the job in parallel using JobChunkExtensions.ScheduleParallel, combining dependencies with base.Dependency and the gizmo-batcher dependency.
- Stores the returned JobHandle into base.Dependency so the ECS scheduler knows about it.
-
Calls m_GizmosSystem.AddGizmosBatcherWriter(base.Dependency) to register that the scheduled job will write into the gizmo batcher.
-
private void __AssignQueries(ref SystemState state)
Compiler helper method (inlined) invoked by OnCreateForCompiler; currently initializes an EntityQueryBuilder (disposed immediately) and exists to satisfy generated-code patterns. -
protected override void OnCreateForCompiler()
Compiler-time initialization routine: - Calls base.OnCreateForCompiler().
-
Calls __AssignQueries(ref base.CheckedStateRef) and __TypeHandle.__AssignHandles(ref base.CheckedStateRef). This ensures the TypeHandle handles are prepared for the job.
-
(Nested)
void TypeHandle.__AssignHandles(ref SystemState state)
Initializes ComponentTypeHandle/ComponentLookup fields via state.GetComponentTypeHandle(isReadOnly:true) / state.GetComponentLookup (isReadOnly:true). -
(Nested) GarbageGizmoJob methods:
private void DrawGarbage(Game.Objects.Transform t, int value)
Computes a cube height from value, offsets position upwards, computes color (green -> red) based on m_GarbageParameterData thresholds, and draws a wire cube using m_GizmoBatcher.DrawWireCube.private void DrawConsume(Game.Objects.Transform t, float value)
Scales height from consumption value, computes color with a Lerp between green and red using a saturate on value/20000f, and draws a wire cube.public void Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex, bool useEnabledMask, in v128 chunkEnabledMask)
Main chunk execution: gets NativeArrays for PrefabRef, GarbageProducer, and Transform. If m_AccumulatedOption is true, iterates buildings and calls DrawGarbage with producer.m_Garbage. If m_ProduceOption is true, iterates prefabs and fetches consumption via m_ConsumptionDatas[prefab].m_GarbageAccumulation and calls DrawConsume.void IJobChunk.Execute(...)explicit interface call forwards to the public Execute.
Notes on execution and safety:
- The job is [BurstCompile]ed for performance.
- ComponentLookup
Usage Example
[Preserve]
protected override void OnCreate()
{
base.OnCreate();
// Acquire the gizmos system and create the building query that the job will process.
m_GizmosSystem = base.World.GetOrCreateSystemManaged<GizmosSystem>();
m_BuildingGroup = GetEntityQuery(new EntityQueryDesc
{
All = new ComponentType[3]
{
ComponentType.ReadOnly<Building>(),
ComponentType.ReadOnly<Game.Objects.Transform>(),
ComponentType.ReadOnly<GarbageProducer>()
},
None = new ComponentType[3]
{
ComponentType.ReadOnly<Deleted>(),
ComponentType.ReadOnly<Temp>(),
ComponentType.ReadOnly<Hidden>()
}
});
// System disabled by default; options control the two visualization modes.
base.Enabled = false;
m_AccumulatedOption = AddOption("Accumulated Garbage", defaultEnabled: true);
m_ProduceOption = AddOption("Produce Garbage", defaultEnabled: true);
}
Additional notes:
- To enable the visualizations at runtime, enable this system (World.GetExistingSystemManaged