Skip to content

Game.Debug.LightDebugSystem

Assembly: Assembly-CSharp.dll
Namespace: Game.Debug

Type: class

Base: BaseDebugSystem

Summary:
LightDebugSystem is a debug-only ECS system used to visualize HDRP punctual lights in the scene (positions and spot cones). It reads light data prepared by HDRPDotsInputs, packages that data into a Burst-compiled IJob (LightGizmoJob) and uses the GizmosSystem/GizmoBatcher to draw batched gizmos. The system is created disabled by default and exposes two toggle Options to control whether positions and/or spot cones are drawn. It takes care to complete the HDRPDotsInputs job handle before scheduling its own job and wires dependencies into the GizmosSystem so gizmo rendering waits on the scheduled job.

Fields

  • private EntityQuery m_LightEffectPrefabQuery
    This query matches entities with LightEffectData and PrefabData. It is prepared in OnCreate but isn't used elsewhere in the current implementation — likely intended for future filtering or prefab-based debugging.

  • private GizmosSystem m_GizmosSystem
    Reference to the GizmosSystem instance (fetched via World.GetOrCreateSystemManaged). Used to obtain a GizmoBatcher for writing gizmo geometry and to register job dependencies with the gizmo pipeline.

  • private Option m_SpotOption
    Option controlling whether spot light cones are visualized. Added in OnCreate with label "Spot Lights Cones" and defaultEnabled = false.

  • private Option m_PositionOption
    Option controlling whether punctual light positions are visualized. Added in OnCreate with label "Show positions" and defaultEnabled = false.

  • private struct LightGizmoJob (nested)
    A private Burst-compiled IJob that receives a NativeArray of HDRPDotsInputs.PunctualLightData and a GizmoBatcher. It has flags for the spot and position options and is responsible for producing the actual geometry for gizmos. The job is annotated so the NativeArray is deallocated on completion.

Properties

  • None.
    This system exposes no public properties.

Constructors

  • public LightDebugSystem()
    Default parameterless constructor. The system's initialization work is performed in OnCreate. The constructor itself does not perform special logic.

Methods

  • protected override void OnCreate() : System.Void
    Initializes the system:
  • Calls base.OnCreate().
  • Fetches or creates GizmosSystem via World.GetOrCreateSystemManaged().
  • Creates an EntityQuery for LightEffectData + PrefabData (m_LightEffectPrefabQuery).
  • Adds two debug Options: "Show positions" and "Spot Lights Cones" (both default to false).

  • Disables the system by default (base.Enabled = false). This method wires up the system to the gizmo infrastructure and exposes toggle options to the user.

  • protected override void OnUpdate() : System.Void
    Main update logic executed each frame while the system is enabled:

  • Completes HDRPDotsInputs.punctualLightsJobHandle to ensure the punctual light data is ready.
  • If HDRPDotsInputs.s_punctualLightdata is not empty, prepares a LightGizmoJob:
    • Retrieves a GizmosBatcher from m_GizmosSystem.GetGizmosBatcher(out dependencies).
    • Copies HDRPDotsInputs.s_punctualLightdata into a NativeArray with Allocator.Persistent. (The job is annotated with DeallocateOnJobCompletion to free this array after the job runs.)
    • Schedules the Burst-compiled IJob using the returned dependencies.
    • Registers the job handle with GizmosSystem via AddGizmosBatcherWriter(jobHandle).
    • Assigns base.Dependency = jobHandle so the ECS world is aware of the scheduled job dependency.
  • If there are no punctual lights, no job is scheduled.

Notes: - The system relies on HDRPDotsInputs.s_punctualLightdata and HDRPDotsInputs.punctualLightsJobHandle — these are external static containers/job handles that provide the runtime light data. - The issued NativeArray uses Allocator.Persistent but is freed by the job attribute [DeallocateOnJobCompletion], so no explicit disposal in the system is needed. - The system obtains and forwards dependency handles to ensure correct ordering between the light-data producer, the gizmo job, and rendering.

  • private void LightGizmoJob.Execute() : System.Void
    The job's Execute method is responsible for iterating the punctual light data and submitting gizmo geometry to the provided GizmoBatcher according to the options:
  • If m_PositionOption is true, it should emit a visual marker at each punctual light's position.
  • If m_SpotOption is true and the light data indicates a spot light, it should emit cone geometry representing the spot light's direction and angle.
  • The job is Burst-compiled and marked to read the input array and options; it writes into the GizmoBatcher. The NativeArray holding input data is marked with [DeallocateOnJobCompletion] so it is freed automatically after job completion.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // LightDebugSystem sets up its options and gizmo system in OnCreate.
    // By default the system is disabled; enable it in a debug build or via a mod options toggle:
    this.Enabled = true; // enable to start drawing light gizmos
}

protected override void OnUpdate()
{
    // The system will complete HDRPDotsInputs' producer, copy punctual light data
    // into a NativeArray, schedule a Burst job (LightGizmoJob) to produce gizmos,
    // and register the job with GizmosSystem so the gizmos are drawn safely.
}

Notes and recommendations: - The system depends on HDRPDotsInputs.s_punctualLightdata and HDRPDotsInputs.punctualLightsJobHandle; ensure those producers are properly scheduled and populated by the HDRP light extraction pipeline. - Because the system disables itself by default (base.Enabled = false), enable it only when debugging to avoid unnecessary overhead. - The LightGizmoJob uses [DeallocateOnJobCompletion] to free the NativeArray — confirm the job path always runs or adapt allocation strategy if you change scheduling.