Skip to content

Game.Debug.AudioGroupingDebugSystem

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

Type: class

Base: GameSystemBase

Summary:
AudioGroupingDebugSystem is a debug rendering system used to visualize audio grouping / ambience levels in the world. It fetches traffic and zone ambience maps, reads AudioGroupingSettingsData from a singleton entity, samples terrain height, and draws wireframe gizmos (wire cubes) showing relative audio/ambience intensity and group type. The system constructs and schedules an IJob (AudioGroupingGizmoJob) to perform the actual gizmo drawing with the engine's GizmoBatcher. The system is disabled by default (base.Enabled = false) and expects a singleton entity that holds a DynamicBuffer with at least the expected number of entries.

Fields

  • private TrafficAmbienceSystem m_TrafficAmbienceSystem
    {{ Holds a reference to the TrafficAmbienceSystem used to obtain traffic ambience map data (NativeArray). }}

  • private ZoneAmbienceSystem m_ZoneAmbienceSystem
    {{ Holds a reference to the ZoneAmbienceSystem used to obtain zone ambience map data (NativeArray). }}

  • private TerrainSystem m_TerrainSystem
    {{ Holds a reference to the TerrainSystem used to obtain TerrainHeightData for sampling ground heights when positioning gizmos. }}

  • private GizmosSystem m_GizmosSystem
    {{ Holds a reference to the GizmosSystem used to get a GizmoBatcher for drawing wireframe gizmos. }}

  • private EntityQuery m_AudioGroupingConfigurationQuery
    {{ An EntityQuery used to find the singleton entity that contains the AudioGroupingSettingsData buffer. The system expects a single settings entity and reads the buffer from it. }}

  • private TypeHandle __TypeHandle
    {{ Internal struct instance that stores BufferLookup handles (BufferLookup) used when creating buffer access inside jobs. Populated by __AssignHandles during OnCreateForCompiler. }}

Properties

  • None (this system does not expose public properties).
    {{ The system uses internal fields and interacts with other systems; it does not declare public properties for modder usage. }}

Constructors

  • public AudioGroupingDebugSystem()
    {{ Default constructor. Marked with [Preserve] attribute in code to avoid stripping. Initialization of system fields happens in OnCreate; the constructor itself performs no logic. }}

Methods

  • protected override void OnCreate() : System.Void
    {{ Initializes dependencies: fetches references to GizmosSystem, TrafficAmbienceSystem, ZoneAmbienceSystem and TerrainSystem from the world. Disables the system by default (base.Enabled = false) and creates an EntityQuery to find AudioGroupingSettingsData buffer. This setup prepares buffers/handles used later in OnUpdate. }}

  • protected override void OnUpdate() : System.Void
    {{ Main update method that prepares and schedules an AudioGroupingGizmoJob. It:

  • Gets the settings singleton entity via m_AudioGroupingConfigurationQuery.GetSingletonEntity().
  • Acquires a BufferLookup through the internal TypeHandle.
  • Requests traffic and zone maps from the respective systems (obtaining job dependencies).
  • Gets terrain height data and a GizmoBatcher (also with dependencies).
  • Populates the job struct and schedules it with combined dependencies.

  • Registers the created Dependency as a reader/writer with the respective systems (m_TrafficAmbienceSystem.AddReader, m_ZoneAmbienceSystem.AddReader, m_GizmosSystem.AddGizmosBatcherWriter). This ensures the job runs safely with ECS job dependencies. }}

  • private void __AssignQueries(ref SystemState state) : System.Void
    {{ Internal helper used by the compiler-generated flow to initialize/assign any EntityQuery instances. In this implementation it constructs and disposes an EntityQueryBuilder (no queries are added here because the main query is created in OnCreate). }}

  • protected override void OnCreateForCompiler() : System.Void
    {{ Compiler-inserted initialization entrypoint. Calls __AssignQueries and __AssignHandles on the TypeHandle to ensure buffer lookups and queries are prepared for use by generated code and jobs. }}

  • AudioGroupingGizmoJob.Execute() : System.Void
    {{ The IJob implementation that does the visual work. Details:

  • Reads the settings buffer (DynamicBuffer) from the provided settings entity.
  • Iterates the traffic map; for cells with traffic > 0, it computes a scaled height (using a specific buffer element scale) and draws a white wire cube positioned above sampled terrain height to indicate traffic volume.
  • Iterates the zone map; for each zone cell it loops over 21 configured group ambience slots. For each slot it computes an ambience strength (scale * zone value for that GroupAmbienceType). If > 0 it computes a cell-specific offset, samples terrain height, chooses a color based on the GroupAmbienceType (e.g. residential -> green, commercial -> blue, industrial -> yellow, etc.), and draws a wire cube scaled to represent the ambience value.
  • Uses TrafficAmbienceSystem.GetCellCenter and ZoneAmbienceSystem.GetCellCenter to position cubes and TerrainUtils.SampleHeight with the TerrainHeightData to place them on the terrain.

  • Uses GizmoBatcher.DrawWireCube for rendering. This job reads NativeArray, NativeArray, TerrainHeightData, and a BufferLookup, and uses a GizmoBatcher provided by the GizmosSystem. }}

  • TypeHandle.__AssignHandles(ref SystemState state) : System.Void
    {{ Populates the TypeHandle's BufferLookup by calling state.GetBufferLookup(isReadOnly: true). This is used later to create buffer access inside the scheduled job. }}

Usage Example

// Example: create a singleton settings entity and enable the debug system.
// Note: AudioGroupingSettingsData and GroupAmbienceType types are part of the game's types.
// This snippet runs in a context where you have access to World (Unity.Entities.World).

using Unity.Entities;
using Unity.Mathematics;
using UnityEngine;

public static class AudioGroupingDebugSetup
{
    public static void EnsureAudioGroupingDebug(World world)
    {
        var em = world.EntityManager;

        // Create a singleton settings entity with a buffer if it doesn't exist.
        Entity settingsEntity;
        var query = em.CreateEntityQuery(ComponentType.ReadOnly<AudioGroupingSettingsData>());
        if (query.IsEmpty)
        {
            settingsEntity = em.CreateEntity();
            var buffer = em.AddBuffer<AudioGroupingSettingsData>(settingsEntity);

            // The system reads up to 21 entries (k < 21 in the job). Ensure at least that many entries.
            for (int i = 0; i < 21; i++)
            {
                buffer.Add(new AudioGroupingSettingsData
                {
                    // Fill with default values appropriate for your mod:
                    // m_Type = (GroupAmbienceType)i, m_Scale = 1f, etc.
                    m_Type = (GroupAmbienceType)math.min(i, (int)GroupAmbienceType.OfficeHigh),
                    m_Scale = 1f
                });
            }
        }
        else
        {
            settingsEntity = query.GetSingletonEntity();
        }

        // Enable the debug system so it draws gizmos.
        var debugSys = world.GetExistingSystemManaged<AudioGroupingDebugSystem>();
        if (debugSys != null)
        {
            debugSys.Enabled = true;
        }
    }
}

Notes and tips: - The debug system is disabled by default; enable it only in debug builds or when needed. - Ensure the AudioGroupingSettingsData buffer has at least the indices accessed by the job (the code loops up to 21 and also accesses index 14 for traffic scaling). - This system relies on other world systems (TrafficAmbienceSystem, ZoneAmbienceSystem, TerrainSystem, GizmosSystem). These must be present and produce valid data for meaningful visuals.