[Audio] Replace synthesized audio with mastered SFX (UI-AUD-1,2)

[niyazmft]

Description

Context:
Emberfall currently utilizes placeholder synthesized .wav files for UI interactions, tactical ability executions, and combat events. While sufficient for early functional testing and prototyping, these basic synthesized sounds lack the acoustic richness, dynamic range, and professional polish required for a premium tactical grid combat experience.

Problem Statement:
The existing placeholder audio assets suffer from flat frequency responses, inconsistent volume normalization, and a lack of dedicated audio bus routing. Furthermore, combat events trigger these raw sound files without dynamic modulation or proper concurrency management, leading to audio clutter, phasing, and an unpolished user experience during intense tactical encounters.

Technical Rationale:
Replacing the synthesized audio with high-fidelity, mastered sound effects (SFX) establishes an immersive, premium acoustic landscape. By structuring the audio architecture around Godot 4's advanced AudioStreamPlayer bus routing and connecting directly to the central EventBus autoload, we maintain strict separation of concerns (keeping visual/audio presentation decoupled from core deterministic entity data/logic). Mastered assets combined with proper bus grouping (Master, SFX, UI, Combat) enable granular volume control, consistent loudness normalization (EBU R128 standard at -23 LUFS), and clean mix dynamics.

Functional Requirements

• Audio Asset Organization:

  • Import all high-fidelity mastered audio files into the assets/audio/ directory structure, categorizing them into dedicated subdirectories: assets/audio/ui/, assets/audio/combat/, assets/audio/environment/, and assets/audio/abilities/.
  • Ensure all imported audio resources are configured with appropriate Godot import presets (e.g., OGG Vorbis for longer sound effects / ambiances, WAV with IMA-ADPCM compression for short, punchy UI/combat sounds).

• Audio Bus Configuration & Routing:

  • Configure the main default_bus_layout.tres to establish dedicated hierarchical audio buses: Master -> SFX -> UI and Master -> SFX -> Combat.
  • Apply appropriate standard Godot audio effects to the buses if required (e.g., a hard limiter on the Combat bus to prevent master bus clipping).
  • Explicitly route all AudioStreamPlayer and AudioStreamPlayer2D nodes to their designated buses (UI or Combat).

• Volume Normalization & Playback Management:

  • Verify and enforce that all mastered sound files are normalized to a consistent loudness standard (-23 LUFS for ambient/combat streams, -18 LUFS for critical UI feedback) to prevent jarring volume leaps between events.
  • Implement dynamic pitch and volume randomization variation (e.g., pitch_scale ranging randomly between 0.92 and 1.08, volume_db ±1.5 dB) on repetitive combat impact and ability sounds to prevent acoustic ear fatigue.

• EventBus Integration & Decoupled Playback:

  • Connect a centralized audio manager singleton or dedicated scene audio controllers to the EventBus autoload signals (e.g., EventBus.combat_started, EventBus.entity_died, EventBus.ability_executed, EventBus.ui_button_pressed).
  • Maintain strict separation of concerns by ensuring that game entities (e.g., Keeper, BaseEnemy) do not directly instantiate or manage audio streams; audio must be triggered entirely via decoupled EventBus signals.
  • Use strictly-typed GDScript for all audio handling scripts, adhering to project CI standards.

Acceptance Criteria (DoD)

• Asset Integration Verification: All synthesized placeholder audio files are fully removed from the project and replaced with mastered SFX assets in assets/audio/.
• Bus Routing Compliance: Inspection of all active AudioStreamPlayer and AudioStreamPlayer2D instances confirms 100% routing to either the UI or Combat audio buses (no direct routing to Master).
• Decoupling Verification: Static code analysis confirms that core entity data and lifecycle scripts do not contain direct audio playback logic; all audio triggers occur through EventBus signal subscriptions.
• Strict Typing & Style Compliance: All newly added or modified GDScript files utilize strict static typing for all variables, parameters, and return types.
• Automated Pre-push & CI Verification: Running bash tools/pre_push_check.sh completes with a 100% clean run, passing all gdformat, gdlint, markdownlint, math validation, Godot headless editor scans, and GdUnit4 test suites with zero errors or warnings.

Edge Cases

Given a multi-target tactical ability is executed, triggering simultaneous impact events on multiple entities within the same animation frame,
When the EventBus emits multiple identical ability impact signals concurrently to the audio playback controller,
Then the audio playback controller must intercept the concurrent requests, cull or throttle duplicate streams exceeding the maximum concurrency threshold (e.g., max 2 simultaneous instances of the same sound), and apply a slight micro-delay (e.g., 15-25ms) along with minor pitch shifting to the remaining instances to prevent audio clipping, phase cancellation, and flanging artifacts.