Game.Audio.AudioGroupingSystem

Assembly: Assembly-CSharp
Namespace: Game.Audio

Type: class

Base: GameSystemBase

Summary: AudioGroupingSystem manages grouped ambient audio sources (far and near) for different ambience types (traffic, forest, rain, etc.). It reads ambience maps, camera position, terrain height, climate and effect flags, and updates EffectInstance entities (created as needed) via a Burst-compiled IJob (AudioGroupingJob). The system creates and disposes native arrays for settings and ambience entities, schedules a job each update to compute intensities and transform updates, and coordinates reads/writes with other systems (AudioManager, TerrainSystem, TrafficAmbienceSystem, ZoneAmbienceSystem). It also respects special conditions such as forest fires and season-dependent effect flags.

---

Fields

• private TrafficAmbienceSystem m_TrafficAmbienceSystem
  Managed reference to the TrafficAmbienceSystem used to obtain traffic ambience map data.

• private ZoneAmbienceSystem m_ZoneAmbienceSystem
  Managed reference to the ZoneAmbienceSystem used to obtain zone ambience map data.

• private EffectFlagSystem m_EffectFlagSystem
  Managed reference to the EffectFlagSystem used to query effect-related flags (e.g., night/cold).

• private SimulationSystem m_SimulationSystem
  Managed reference (present but not used in shown code) to the SimulationSystem.

• private ClimateSystem m_ClimateSystem
  Managed reference to climate data (precipitation, isRaining).

• private AudioManager m_AudioManager
  Managed reference to the AudioManager used to obtain SourceUpdateData for audio source transforms/intensities.

• private EntityQuery m_AudioGroupingConfigurationQuery
  Query used to fetch audio grouping configuration entities containing AudioGroupingSettingsData buffers.

• private EntityQuery m_AudioGroupingMiscSettingQuery
  Query to fetch global AudioGroupingMiscSetting singleton (e.g., forest fire distance).

• private NativeArray<Entity> m_AmbienceEntities
  Persistent native array of entities used as "far" group effect instances (created via CreateEffect).

• private NativeArray<Entity> m_NearAmbienceEntities
  Persistent native array of entities used as "near" group effect instances (may contain Entity.Null).

• private NativeArray<AudioGroupingSettingsData> m_Settings
  Persistent native array holding the AudioGroupingSettingsData entries read from configuration entities.

• private TerrainSystem m_TerrainSystem
  Managed reference to TerrainSystem used for height sampling and registering CPU readers.

• private EntityQuery m_OnFireTreeQuery
  Query to find tree entities that are on fire (used to suppress forest ambience if nearby).

• private NativeArray<float> m_CurrentValues
  EnumArray annotated NativeArray used to store current computed ambience values per GroupAmbienceType (22 entries in the code). Marked with DebugWatchValue.

• private TypeHandle __TypeHandle
  Local struct instance that stores ComponentLookup handles required by the job and assigned in OnCreateForCompiler.

Properties

• None (no public properties on this system).
  Note: internal ComponentLookup handles are stored in the TypeHandle struct and assigned via __AssignHandles.

Constructors

• public AudioGroupingSystem()
  Default constructor. Marked with [Preserve] attribute; initialization logic happens in OnCreate.

Methods

• protected override void OnCreate()
  Initializes references to required managed systems (AudioManager, TrafficAmbienceSystem, ZoneAmbienceSystem, TerrainSystem, EffectFlagSystem, ClimateSystem). Allocates m_CurrentValues (persistent NativeArray of length 22) and sets up EntityQueries for configuration, misc settings and on-fire trees. Calls RequireForUpdate on the audio grouping configuration query so system only updates when configuration exists.

• private Entity CreateEffect(Entity sfx)
  Creates a new entity with an EffectInstance component and a PrefabRef pointing to the provided sfx prefab entity. Used to construct ambience effect entities for far/near group sounds.

• private void Initialize()
  Reads all AudioGroupingSettingsData buffers from configuration entities, consolidates them into m_Settings (persistent NativeArray), and allocates/creates m_AmbienceEntities and m_NearAmbienceEntities arrays and corresponding EffectInstance entities (using CreateEffect). Called lazily from OnUpdate the first time the ambient entities are needed.

• protected override void OnDestroy()
  Disposes of created NativeArrays (m_AmbienceEntities, m_NearAmbienceEntities, m_Settings, m_CurrentValues) when the system is destroyed, then calls base.OnDestroy.

• protected override void OnUpdate()
  Main runtime logic:

• Ensures game is in Game mode and not loading.
• Ensures initialization (Initialize) has run and ambience EffectInstance entities exist.
• Gets main camera position and AudioGroupingMiscSetting singleton.
• Prepares and schedules a Burst-compiled AudioGroupingJob that:
  • Reads traffic and zone ambience maps, terrain height data, effect flags, climate data.
  • Iterates m_AmbienceEntities and m_NearAmbienceEntities to compute intensities (num2/num3) for each ambience group type according to GroupAmbienceType and AudioGroupingSettingsData.
  • Applies height-based attenuation, fade speed smoothing (lerp from previous intensity), clamps intensity, sets EffectInstance position/rotation/intensity, and enqueues transform updates into AudioManager's SourceUpdateData (Add/Remove).
  • Respects special conditions like required/forbidden effect flags (e.g., Cold), forest fires (skips forest ambience if fire nearby), and rain/precipitation for rain ambience.
• Combines job dependencies with system dependency, registers required readers/writers with TerrainSystem, AudioManager and TrafficAmbienceSystem.

• Note: the job obtains an array of on-fire tree entities (m_OnFireTrees) that is deallocated on job completion.

• private void __AssignQueries(ref SystemState state)
  Compiler helper used to set up queries for compiler-time. In this decompiled code it just constructs and disposes an EntityQueryBuilder; actual query setup happens elsewhere.

• protected override void OnCreateForCompiler()
  Compiler-time initialization that calls __AssignQueries and assigns component lookup handles via __TypeHandle.__AssignHandles.

Inner types / job:

• AudioGroupingJob (private struct, BurstCompile, implements IJob)
• Fields: ComponentLookup m_EffectInstances (read/write), ReadOnly ComponentLookup m_EffectDatas, ReadOnly ComponentLookup m_PrefabRefs, ReadOnly ComponentLookup m_TransformData, NativeArray m_TrafficAmbienceMap, NativeArray m_AmbienceMap, NativeArray m_Settings, SourceUpdateData m_SourceUpdateData, EffectFlagSystem.EffectFlagData m_EffectFlagData, float3 m_CameraPosition, NativeArray m_AmbienceEntities, NativeArray m_NearAmbienceEntities, NativeArray m_CurrentValues, [DeallocateOnJobCompletion] NativeArray m_OnFireTrees, ReadOnly TerrainHeightData m_TerrainData, ReadOnly float m_ForestFireDistance, ReadOnly float m_Precipitation, ReadOnly bool m_IsRaining.
• Execute(): Implements the per-update logic described above—samples terrain height, computes per-group intensities using TrafficAmbienceSystem.GetTrafficAmbience2 and ZoneAmbienceSystem.GetZoneAmbience / GetZoneAmbienceNear, respects rain, forest/nights, fade speeds and heights, updates EffectInstance components and registers transforms in SourceUpdateData. Uses IsNearForestOnFire to skip forest ambience when necessary.

• IsNearForestOnFire(float3 cameraPosition): helper that scans m_OnFireTrees and uses transform component positions to see if any on-fire tree is within m_ForestFireDistance of the camera.

• TypeHandle (private struct)

• Holds ComponentLookup fields used by the job: EffectInstance (RW), EffectData (RO), PrefabRef (RO), Game.Objects.Transform (RO).
• __AssignHandles(ref SystemState state): obtains ComponentLookup instances from the SystemState and stores them into the TypeHandle fields. This method is marked AggressiveInlining.

Notes / Implementation details: - The system lazily creates per-group EffectInstance entities on first update (Initialize). - Uses NativeArray and deallocations carefully: m_OnFireTrees is decorated with [DeallocateOnJobCompletion] to free the temp array after the job completes. - Uses InternalCompilerInterface.GetComponentLookup to pass ComponentLookup instances into the job (ensuring proper safety/state checks). - Observes effect condition flags (EffectConditionFlags) for required/forbidden conditions (Cold) and uses EffectFlagSystem.EffectFlagData for night/cold season checks. - Uses TerrainUtils.SampleHeight via TerrainHeightData to convert world Y to local camera Y relative to terrain. - The job is Burst-compiled for performance and scheduled as an IJob with combined dependencies.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    // AudioGroupingSystem will initialize its managed references and native arrays there.
    // Typically you don't need to call Initialize() manually; it's invoked lazily in OnUpdate.
}

// Typical runtime (system handles scheduling internally)
[Preserve]
protected override void OnUpdate()
{
    // The system will gather camera position, schedule AudioGroupingJob and update effect instances.
}

Additional tips: - If you add or change AudioGroupingSettingsData assets/entities, ensure the system recomputes or is restarted so Initialize reads new settings. - When debugging ambience intensities, inspect m_CurrentValues (EnumArray) to see per-GroupAmbienceType computed values (22 entries in code).