Audio Manager

Status: Designed Author: user + game-designer Last Updated: 2026-03-28 System Index: #20 — Alpha, Polish Layer

Overview

The Audio Manager handles SFX playback and background music across all scenes. It listens for game events (card played, damage dealt, enemy death, phase transitions) and plays corresponding sounds. Music tracks loop per scene with crossfade on transitions. Audio is managed through Godot's AudioBus system with separate buses for SFX, Music, and UI sounds.

Player Fantasy

"The game feels alive." Card slaps, impact sounds, and tense boss music elevate the experience from "functional prototype" to "game I want to play again." Audio is the cheapest way to add juice.

Detailed Design

Core Rules

Audio Manager is an autoloaded singleton — persists across scenes.
Three audio buses: Music, SFX, UI. Each independently volume-controlled.
SFX triggered by game event signals. No direct calls from gameplay systems.
Music per scene — crossfade on scene transitions.
SFX are non-positional (2D game, no spatial audio needed).

Audio Buses

Bus	Purpose	Default Volume
Master	Overall volume	100%
Music	Background music	70%
SFX	Gameplay sounds (card, combat, enemy)	100%
UI	Menu clicks, button hovers	80%

SFX Event Map

Event	Sound	Bus
Card played (Attack)	Sword swing / impact	SFX
Card played (Skill)	Shield raise / buff sound	SFX
Card played (Power)	Magical charge-up	SFX
Card played (Assist)	Gentle chime / heal	SFX
Card played (Chain)	Chain link / combo sound	SFX
Damage dealt to enemy	Hit impact, varies by damage amount	SFX
Damage dealt to player	Pain thud, screen feedback	SFX
Block absorbed damage	Shield clang	SFX
Enemy death	Defeat sound	SFX
Player death	Somber tone	SFX
Status effect applied	Debuff: dark tone, Buff: bright tone	SFX
Turn ended	Click / confirmation	UI
Phase transition	Whoosh / tension shift	SFX
Victory	Fanfare	SFX
Defeat	Low, somber stinger	SFX
Button click	Click	UI
Button hover	Soft tick	UI
Card hover	Paper rustle	UI
Rally added	Coin / energy charge	SFX
Rally spent	Energy release	SFX

Dice Game SFX Events

Event	Sound	Bus	Notes
Dice roll	Wooden clack, satisfying	SFX	Player clicks Roll
Dice lock	Quick click/snap	SFX	Locking a die
Dice unlock	Soft click	SFX	Unlocking a die
Dice reroll	Whoosh + settle	SFX	Using reroll
Dice flip	Flip sound	SFX	Enemy flips all dice
Score/Confirm	Chime, satisfying	SFX	Confirming hand
Enemy hit	Impact thud	SFX	Damage to enemy
Enemy hit (heavy)	Heavy impact	SFX	Big damage
Enemy death	Defeat crash	SFX	Enemy dies
Player damage	Pain thud	SFX	Taking damage
Block absorb	Shield clang	SFX	Block stops damage
Enemy: Steal Reroll	Sneering sound	SFX	Reroll stolen
Enemy: Lock Hold	Lock clicking	SFX	Holds locked
Enemy: Burn Dice	Fire sizzle	SFX	Dice destroyed
Enemy: Flip All	Magic whoosh	SFX	All dice flipped
Enemy: Snipe	Sniper shot	SFX	Highest die halved
Enemy: Gravity	Gravity crush	SFX	Dice become 1-3
Enemy: Chaos	Magic swirl	SFX	Dice shuffled
Turn start	Tension builder	SFX	New turn begins
Combat win	Victory fanfare	SFX	Battle won
Combat lose	Defeat stinger	SFX	Battle lost

Music Tracks

Scene	Track Style	Loop
Main Menu	Calm, inviting	Yes
Lobby	Light, anticipatory	Yes
Map	Adventurous, medium tempo	Yes
Combat (basic)	Energetic, medium intensity	Yes
Combat (elite)	Higher intensity variant	Yes
Combat (boss)	Epic, high intensity	Yes
Reward	Brief triumphant, then calm	Yes
Victory	Triumphant fanfare (5-10s), then calm loop	Stinger + loop
Game Over	Somber (5-10s stinger)	Stinger only

Music Crossfade

transition_to_track(new_track, duration=1.0):
    tween current_music volume to 0 over duration/2
    swap track
    tween new_music volume to target over duration/2

Interactions with Other Systems

System	Direction	Interface
Combat System	Listens	Combat events (card played, damage, phase change, victory/defeat)
Game State Manager	Listens	Scene transitions for music changes
Settings System	Reads	Volume levels per bus
All UI	Listens	Button interactions for UI sounds

Formulas

Damage Sound Scaling

# Bigger hits = louder/more impactful sound variant
if damage >= 15: play("hit_heavy")
elif damage >= 8: play("hit_medium")
else: play("hit_light")

Edge Cases

Case	Resolution
Multiple SFX simultaneously	Godot handles polyphony natively. Allow up to 8 simultaneous SFX.
Music track missing	Log warning, continue without music. Don't crash.
Scene change during SFX playback	SFX finish playing (short, <1s). Music crossfades.
Volume set to 0	Still process events, just no audible output. No CPU waste.
Web export audio restrictions	Browsers require user interaction before audio. Resume AudioServer on first click.

Dependencies

Upstream

System	Dependency Type	Interface
Combat System	Hard	Event signals for SFX triggers
Game State Manager	Hard	Scene transitions for music
Settings System	Soft	Volume preferences

Downstream

None — output only.

Tuning Knobs

Knob	Default	Safe Range	Affects
`master_volume`	1.0	0.0-1.0	Overall volume
`music_volume`	0.7	0.0-1.0	Music loudness
`sfx_volume`	1.0	0.0-1.0	SFX loudness
`ui_volume`	0.8	0.0-1.0	UI sound loudness
`crossfade_duration`	1.0s	0.5-3.0s	Music transition smoothness
`max_simultaneous_sfx`	8	4-16	Polyphony limit

Acceptance Criteria

#	Criterion	Verification
1	Card play triggers appropriate SFX	Audio test: play Strike, assert sword sound plays
2	Music plays per scene and loops	Audio test: enter combat, assert combat music loops
3	Music crossfades on scene transition	Audio test: combat → reward, assert smooth transition
4	Volume sliders affect correct buses	Integration test: set SFX to 0, assert SFX silent, music audible
5	Web export handles audio unlock	Integration test: web build, first click enables audio