audio-system
Use when implementing audio — audio buses, AudioStreamPlayer, spatial audio, music management, SFX pooling, and dynamic mixing
jame581 · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add jame581/GodotPrompter --skill audio-system技能说明
name: audio-system description: Use when implementing audio — audio buses, AudioStreamPlayer, spatial audio, music management, SFX pooling, and dynamic mixing
Audio System in Godot 4.3+
All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.
Related skills: event-bus for decoupled audio triggers, save-load for persisting audio settings, resource-pattern for audio data containers.
1. Core Concepts
Audio Node Types
| Node | Dimensions | Use For |
|---|---|---|
AudioStreamPlayer | Non-positional | Music, UI sounds, global SFX |
AudioStreamPlayer2D | 2D positional | Footsteps, gunfire, environmental sounds |
AudioStreamPlayer3D | 3D positional | Same as 2D but in 3D space |
Audio Bus Architecture
Godot routes all audio through buses (like a mixing console).
Master (always exists)
├── Music → volume, effects for background music
├── SFX → volume, effects for sound effects
│ ├── Footsteps → sub-bus for fine-tuning
│ └── Weapons → sub-bus for fine-tuning
└── UI → volume for menu sounds
Setup: Bottom panel → Audio tab → Add buses, set names, route outputs.
Every AudioStreamPlayer has a bus property — set it to the target bus name (e.g., "SFX", "Music").
2. Basic Audio Playback
GDScript
extends Node2D
@onready var sfx_player: AudioStreamPlayer2D = $AudioStreamPlayer2D
@onready var music_player: AudioStreamPlayer = $MusicPlayer
func _ready() -> void:
# Play background music (looping is set on the AudioStream resource)
music_player.play()
func play_jump_sound() -> void:
sfx_player.stream = preload("res://audio/sfx/jump.wav")
sfx_player.play()
C#
using Godot;
public partial class AudioExample : Node2D
{
private AudioStreamPlayer2D _sfxPlayer;
private AudioStreamPlayer _musicPlayer;
public override void _Ready()
{
_sfxPlayer = GetNode<AudioStreamPlayer2D>("AudioStreamPlayer2D");
_musicPlayer = GetNode<AudioStreamPlayer>("MusicPlayer");
_musicPlayer.Play();
}
public void PlayJumpSound()
{
_sfxPlayer.Stream = GD.Load<AudioStream>("res://audio/sfx/jump.wav");
_sfxPlayer.Play();
}
}
Looping Audio
Looping is configured on the AudioStream resource, not the player node:
- WAV: Import tab → Loop Mode → Forward (or Ping-Pong)
- OGG: Import tab → Loop → On, set Loop Offset
- MP3: Import tab → Loop → On
Always use OGG Vorbis for music (smaller files, good quality). Use WAV for short SFX (no decoding latency). Avoid MP3 for SFX — it adds silence at the start.
3. Audio Bus Management
Setting Volume from Code
Godot uses decibels (dB) for volume. Linear-to-dB conversion is required for sliders.
GDScript
# Get bus index by name
var bus_index: int = AudioServer.get_bus_index("SFX")
# Set volume in dB directly
AudioServer.set_bus_volume_db(bus_index, -6.0) # -6 dB = ~50% perceived volume
# Convert linear (0.0–1.0) to dB — use for UI sliders
func set_bus_volume_linear(bus_name: String, linear: float) -> void:
var index := AudioServer.get_bus_index(bus_name)
AudioServer.set_bus_volume_db(index, linear_to_db(linear))
# Mute / unmute a bus
AudioServer.set_bus_mute(bus_index, true)
# Read current volume as linear (for displaying on a slider)
func get_bus_volume_linear(bus_name: String) -> float:
var index := AudioServer.get_bus_index(bus_name)
return db_to_linear(AudioServer.get_bus_volume_db(index))
C#
int busIndex = AudioServer.GetBusIndex("SFX");
// Set volume in dB
AudioServer.SetBusVolumeDb(busIndex, -6.0f);
// Linear to dB conversion for UI sliders
public void SetBusVolumeLinear(string busName, float linear)
{
int index = AudioServer.GetBusIndex(busName);
AudioServer.SetBusVolumeDb(index, Mathf.LinearToDb(linear));
}
// Mute / unmute
AudioServer.SetBusMute(busIndex, true);
// Read current volume as linear
public float GetBusVolumeLinear(string busName)
{
int index = AudioServer.GetBusIndex(busName);
return Mathf.DbToLinear(AudioServer.GetBusVolumeDb(index));
}
Audio Bus Effects
Add effects to buses in the Audio panel (bottom dock). Common effects:
| Effect | Use For |
|---|---|
Reverb | Cave, cathedral, bathroom ambience |
Delay | Echo effects |
Compressor | Normalize loud/quiet sounds (master bus) |
Limiter | Prevent clipping on master bus |
LowPassFilter | Muffled sounds (underwater, behind walls) |
HighPassFilter | Thin/tinny sound (radio, phone) |
Chorus | Thicken sounds |
Distortion | Gritty/overdrive effects |
EQ | Fine-tune frequency bands |
Dynamic Effect Toggle
# Enable/disable an effect on a bus at runtime
var bus_index := AudioServer.get_bus_index("SFX")
var effect_index := 0 # First effect on the bus
AudioServer.set_bus_effect_enabled(bus_index, effect_index, true)
# Apply low-pass filter for "underwater" feel
func set_underwater(enabled: bool) -> void:
var index := AudioServer.get_bus_index("SFX")
# Assumes a LowPassFilter is the first effect on the SFX bus
AudioServer.set_bus_effect_enabled(index, 0, enabled)
4. Spatial Audio (2D & 3D)
AudioStreamPlayer2D
Automatically adjusts volume and panning based on distance to the nearest AudioListener2D (or the Camera2D if no listener exists).
Enemy (CharacterBody2D)
├── Sprite2D
└── Aud
阅读完整来源 ↗