godot-audio-systems
Expert patterns for Godot audio including AudioStreamPlayer variants (2D positional, 3D spatial), AudioBus mixing architecture, dynamic effects (reverb, EQ,compression), audio pooling for performance, music transitions (crossfade, bpm-sync), and procedural audio generation. Use for music systems, sound effects, spatial audio, or audio-reactive gameplay. Trigger keywords: AudioStreamPlayer, AudioStreamPlayer2D, AudioStreamPlayer3D, AudioBus, AudioServer, AudioEffect, music_crossfade, audio_pool, positional_audio, reverb, bus_volume.
thedivergentai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add thedivergentai/GD-Agentic-Skills --skill godot-audio-systems技能说明
name: godot-audio-systems description: "Expert patterns for Godot audio including AudioStreamPlayer variants (2D positional, 3D spatial), AudioBus mixing architecture, dynamic effects (reverb, EQ,compression), audio pooling for performance, music transitions (crossfade, bpm-sync), and procedural audio generation. Use for music systems, sound effects, spatial audio, or audio-reactive gameplay. Trigger keywords: AudioStreamPlayer, AudioStreamPlayer2D, AudioStreamPlayer3D, AudioBus, AudioServer, AudioEffect, music_crossfade, audio_pool, positional_audio, reverb, bus_volume."
Audio Systems
Expert mixing, spatial, pooling, and interactive-music patterns for Godot's audio engine.
NEVER Do (Expert Audio Rules)
Mixing & Buses
- NEVER set bus volume with linear values —
set_bus_volume_db()is logarithmic. Uselinear_to_db()for sliders OR everything will sound too loud until the last 5%. - NEVER skip 'Bus Routing' — Playing music on the 'SFX' bus makes volume menus useless. Strictly route every player to its dedicated sub-bus (Music, SFX, UI, Voice).
- NEVER use 'Master' for gameplay sounds — Dedicate Master to final limiting. Route all gameplay to sub-groups so you can mute/duck categories.
Positional & Spatial
- NEVER use 3D players without an Attenuation Model — Default is NONE. If you don't set it to
Inverse Distance, a whisper on the other side of the map will be global volume. - NEVER play 3D sounds exactly on top of the listener — Causes "Panning Jitter" where the sound snaps between Left/Right speakers. Offset by
0.1units. - NEVER forget Doppler for high-speed objects — A car flying by without
DOPPLER_TRACKING_PHYSICS_STEPfeels flat and static.
Performance & Polish
- NEVER spam same-frame sounds — Playing 50 explosions at once causes constructive interference (clipping/distortion). Use a
Limiter(audio_voice_limiter_manager.gd). - NEVER instantiate nodes for one-shots — Creating a node, playing a 0.5s clap, and
queue_free()ing causes frame-time spikes. Use a Pool. - NEVER skip Crossfades/Transitions — Abrupt music cuts break immersion. Always use a 0.5s-1.0s
Tweento bridge tracks.
Decision Matrix: Which AudioStreamPlayer?
| Feature | AudioStreamPlayer | AudioStreamPlayer2D | AudioStreamPlayer3D |
|---|---|---|---|
| Spatial | Global | 2D panning | 3D positioning |
| Doppler | No | No | Yes |
| Attenuation | No | Distance-based | 3D falloff |
| Reverb send | No | No | Yes |
| Use for | Music, UI, VO | 2D games | 3D games |
| Performance | Fastest | Medium | Slowest |
Golden Path → Scripts
MANDATORY — open only the script that matches the row. Do not reinvent pools, duckers, or interactive graphs from memory.
Do NOT Load every script below for one mix task.
| Need | Script |
|---|---|
| One-shot SFX spam / voice steal | MANDATORY audio_voice_pool_manager.gd |
| Cap identical SFX (ear-bleed) | MANDATORY audio_voice_limiter_manager.gd |
| Dialogue over music | MANDATORY audio_bus_ducker_logic.gd |
| Bus layout / runtime mute | audio_bus_manager.gd |
| Linear UI slider → dB | audio_linear_volume_interpolator.gd |
| Wall muffling | MANDATORY audio_occlusion_raycast.gd |
| Room reverb zones | audio_environmental_reverb_zone.gd |
| Vertical intensity stems | MANDATORY audio_interactive_music_manager.gd |
| Horizontal clip graph | interactive_music_graph.gd + references/interactive-music-deep-dive.md |
| Bus / pool WHY | references/audio-pooling-and-buses.md |
| Crossfade / BPM / duck | references/music-transitions.md |
| Adaptive music player wrapper | audio_adaptive_music_player.gd |
| Autoload SFX entry | audio_manager.gd |
| Footstep surface banks | audio_footstep_surface_selector.gd |
| Procedural hum / engine | audio_procedural_generator_synth.gd |
| Spectrum → gameplay / VFX | audio_reactive_visualizer_component.gd, audio_visualizer.gd |
| Dialogue subtitle sync | subtitle_sync_system.gd |
Available Scripts (catalog)
audio_voice_pool_manager.gd
Priority voice pool with steal of lowest-priority oldest voice (hero voices protected).
audio_voice_limiter_manager.gd
Concurrency cap for identical SFX instances.
audio_bus_ducker_logic.gd
Sidechain-style dialogue-over-music ducking.
audio_bus_manager.gd
Runtime bus volume/mute helpers for Music/SFX/UI/Voice groups.
audio_manager.gd
Autoload entry for play-one-shot routing onto the pool.
audio_linear_volume_interpolator.gd
Musically-correct linear↔dB UI slider mapping.
audio_occlusion_raycast.gd
Raycast muffling via attenuation filter cutoff.
audio_environmental_reverb_zone.gd
Area3D-driven reverb/bus override zones.
audio_interactive_music_manager.gd
AudioStreamSynchronized