[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6KR6VC2R8HPYS7X56QT06SA":3,"skill-same:01M6KR6VC2R8HPYS7X56QT06SA":83},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":37,"linkOnly":38,"markdownContent":39,"markdownBody":40,"frontMatter":41,"refName":42,"commitSha":43,"skillDirectory":44,"forksCount":45,"repositoryHtmlUrl":46,"repositoryHomepageUrl":6,"ownerHtmlUrl":47,"ownerBlogUrl":48,"ownerDescription":49,"updatedAt":50,"install":51,"resources":64},"01M6KR6VC2R8HPYS7X56QT06SA","audio-system",null,"Use when implementing audio — audio buses, AudioStreamPlayer, spatial audio, music management, SFX pooling, and dynamic mixing","jame581\u002FGodotPrompter","jame581","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F21112138?v=4","01M6KR3KEQ9Z30WVJRR2E2ZVXE","Jan Mesarč","01M6KR3KJVRMPDSMASQPBCBVK3",964,"MIT","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Faudio-system\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000016","图像与多媒体","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36],"Audio","system","audio system","music","management","use","Spatial","implementing","buses","mixing","pooling","sfx","when","2026-11-10 10:12:30",false,"---\nname: audio-system\ndescription: Use when implementing audio — audio buses, AudioStreamPlayer, spatial audio, music management, SFX pooling, and dynamic mixing\n---\n\n# Audio System in Godot 4.3+\n\nAll examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.\n\n> **Related skills:** **event-bus** for decoupled audio triggers, **save-load** for persisting audio settings, **resource-pattern** for audio data containers.\n\n---\n\n## 1. Core Concepts\n\n### Audio Node Types\n\n| Node                   | Dimensions | Use For                                       |\n|------------------------|------------|-----------------------------------------------|\n| `AudioStreamPlayer`    | Non-positional | Music, UI sounds, global SFX              |\n| `AudioStreamPlayer2D`  | 2D positional  | Footsteps, gunfire, environmental sounds  |\n| `AudioStreamPlayer3D`  | 3D positional  | Same as 2D but in 3D space                |\n\n### Audio Bus Architecture\n\nGodot routes all audio through **buses** (like a mixing console).\n\n```\nMaster (always exists)\n├── Music          → volume, effects for background music\n├── SFX            → volume, effects for sound effects\n│   ├── Footsteps  → sub-bus for fine-tuning\n│   └── Weapons    → sub-bus for fine-tuning\n└── UI             → volume for menu sounds\n```\n\n**Setup:** Bottom panel → Audio tab → Add buses, set names, route outputs.\n\nEvery AudioStreamPlayer has a `bus` property — set it to the target bus name (e.g., `\"SFX\"`, `\"Music\"`).\n\n---\n\n## 2. Basic Audio Playback\n\n### GDScript\n\n```gdscript\nextends Node2D\n\n@onready var sfx_player: AudioStreamPlayer2D = $AudioStreamPlayer2D\n@onready var music_player: AudioStreamPlayer = $MusicPlayer\n\nfunc _ready() -> void:\n    # Play background music (looping is set on the AudioStream resource)\n    music_player.play()\n\nfunc play_jump_sound() -> void:\n    sfx_player.stream = preload(\"res:\u002F\u002Faudio\u002Fsfx\u002Fjump.wav\")\n    sfx_player.play()\n```\n\n### C#\n\n```csharp\nusing Godot;\n\npublic partial class AudioExample : Node2D\n{\n    private AudioStreamPlayer2D _sfxPlayer;\n    private AudioStreamPlayer _musicPlayer;\n\n    public override void _Ready()\n    {\n        _sfxPlayer = GetNode\u003CAudioStreamPlayer2D>(\"AudioStreamPlayer2D\");\n        _musicPlayer = GetNode\u003CAudioStreamPlayer>(\"MusicPlayer\");\n        _musicPlayer.Play();\n    }\n\n    public void PlayJumpSound()\n    {\n        _sfxPlayer.Stream = GD.Load\u003CAudioStream>(\"res:\u002F\u002Faudio\u002Fsfx\u002Fjump.wav\");\n        _sfxPlayer.Play();\n    }\n}\n```\n\n### Looping Audio\n\nLooping is configured on the **AudioStream resource**, not the player node:\n\n- **WAV:** Import tab → Loop Mode → Forward (or Ping-Pong)\n- **OGG:** Import tab → Loop → On, set Loop Offset\n- **MP3:** Import tab → Loop → On\n\n> Always use OGG Vorbis for music (smaller files, good quality). Use WAV for short SFX (PCM or QOA, cheap to decode). Avoid MP3 for SFX — depending on the encoder it can start with padding silence.\n\n---\n\n## 3. Audio Bus Management\n\n### Setting Volume from Code\n\nGodot uses **decibels (dB)** for volume. Linear-to-dB conversion is required for sliders.\n\n#### GDScript\n\n```gdscript\n# Get bus index by name\nvar bus_index: int = AudioServer.get_bus_index(\"SFX\")\n\n# Set volume in dB directly\nAudioServer.set_bus_volume_db(bus_index, -6.0)  # -6 dB ≈ half amplitude (db_to_linear(-6.0) ≈ 0.5)\n\n# Convert linear (0.0–1.0) to dB — use for UI sliders\nfunc set_bus_volume_linear(bus_name: String, linear: float) -> void:\n    var index := AudioServer.get_bus_index(bus_name)\n    AudioServer.set_bus_volume_db(index, linear_to_db(linear))\n\n# Mute \u002F unmute a bus\nAudioServer.set_bus_mute(bus_index, true)\n\n# Read current volume as linear (for displaying on a slider)\nfunc get_bus_volume_linear(bus_name: String) -> float:\n    var index := AudioServer.get_bus_index(bus_name)\n    return db_to_linear(AudioServer.get_bus_volume_db(index))\n```\n\n#### C#\n\n```csharp\nint busIndex = AudioServer.GetBusIndex(\"SFX\");\n\n\u002F\u002F Set volume in dB\nAudioServer.SetBusVolumeDb(busIndex, -6.0f);\n\n\u002F\u002F Linear to dB conversion for UI sliders\npublic void SetBusVolumeLinear(string busName, float linear)\n{\n    int index = AudioServer.GetBusIndex(busName);\n    AudioServer.SetBusVolumeDb(index, Mathf.LinearToDb(linear));\n}\n\n\u002F\u002F Mute \u002F unmute\nAudioServer.SetBusMute(busIndex, true);\n\n\u002F\u002F Read current volume as linear\npublic float GetBusVolumeLinear(string busName)\n{\n    int index = AudioServer.GetBusIndex(busName);\n    return Mathf.DbToLinear(AudioServer.GetBusVolumeDb(index));\n}\n```\n\n### Audio Bus Effects\n\nAdd effects to buses in the Audio panel (bottom dock). Common effects:\n\n| Effect          | Use For                                     |\n|-----------------|---------------------------------------------|\n| `Reverb`        | Cave, cathedral, bathroom ambience           |\n| `Delay`         | Echo effects                                 |\n| `Compressor`    | Normalize loud\u002Fquiet sounds (master bus)     |\n| `HardLimiter`   | Prevent clipping on master bus (`Limiter` is deprecated) |\n| `LowPassFilter` | Muffled sounds (underwater, behind walls)    |\n| `HighPassFilter` | Thin\u002Ftinny sound (radio, phone)             |\n| `Chorus`        | Thicken sounds                               |\n| `Distortion`    | Gritty\u002Foverdrive effects                     |\n| `EQ`            | Fine-tune frequency bands                    |\n\n### Dynamic Effect Toggle\n\n```gdscript\n# Enable\u002Fdisable an effect on a bus at runtime\nvar bus_index := AudioServer.get_bus_index(\"SFX\")\nvar effect_index := 0  # First effect on the bus\nAudioServer.set_bus_effect_enabled(bus_index, effect_index, true)\n\n# Apply low-pass filter for \"underwater\" feel\nfunc set_underwater(enabled: bool) -> void:\n    var index := AudioServer.get_bus_index(\"SFX\")\n    # Assumes a LowPassFilter is the first effect on the SFX bus\n    AudioServer.set_bus_effect_enabled(index, 0, enabled)\n```\n\n---\n\n## 4. Spatial Audio (2D & 3D)\n\n### AudioStreamPlayer2D\n\nAutomatically adjusts volume and panning based on distance to the current `AudioListener2D` (or the centre of the screen if none is current).\n\n```\nEnemy (CharacterBody2D)\n├── Sprite2D\n└── AudioStreamPlayer2D   ← positioned at enemy's location\n    bus = \"SFX\"\n    max_distance = 1000.0\n    attenuation = 1.0\n```\n\nKey properties:\n\n| Property        | Description                                   | Default  |\n|-----------------|-----------------------------------------------|----------|\n| `max_distance`  | Beyond this distance, sound is silent          | 2000.0   |\n| `attenuation`   | Volume falloff curve (1.0 = linear, higher = sharper) | 1.0 |\n| `max_polyphony` | Max simultaneous instances of this player      | 1        |\n| `panning_strength` | How much the sound pans left\u002Fright          | 1.0      |\n\n### AudioStreamPlayer3D\n\nSame concept but in 3D. Works with `AudioListener3D` (or the Camera3D).\n\nKey additional properties:\n\n| Property            | Description                                 |\n|---------------------|---------------------------------------------|\n| `unit_size`         | Distance at which volume is 0 dB            |\n| `max_db`            | Maximum volume cap                          |\n| `attenuation_model` | Inverse, InverseSquare, Logarithmic, Disabled |\n| `doppler_tracking`  | Enable Doppler effect for moving sources    |\n\n### AudioListener\n\n```gdscript\n# Make a specific camera the audio listener\n# 2D: add AudioListener2D as child of Camera2D, call make_current()\n# 3D: add AudioListener3D as child of Camera3D, call make_current()\n\n# By default, the current Camera2D\u002F3D acts as the listener.\n# Only add an explicit AudioListener if you need a different listening position.\n```\n\n```csharp\n\u002F\u002F 2D spatial player\npublic partial class Footsteps : AudioStreamPlayer2D\n{\n    public override void _Ready()\n    {\n        Bus = \"SFX\";\n        MaxDistance = 1000.0f;     \u002F\u002F Pixels at which volume reaches zero\n        Attenuation = 1.0f;         \u002F\u002F Linear falloff (higher = sharper)\n        MaxPolyphony = 4;           \u002F\u002F Allow overlapping footstep sounds\n    }\n\n    public void PlayStep() => Play();\n}\n\n\u002F\u002F 3D spatial player\npublic partial class EngineHum : AudioStreamPlayer3D\n{\n    public override void _Ready()\n    {\n        Bus = \"SFX\";\n        UnitSize = 4.0f;            \u002F\u002F Meters at which volume is 0 dB\n        MaxDistance = 50.0f;\n        AttenuationModel = AttenuationModelEnum.InverseDistance;\n    }\n}\n\n\u002F\u002F Custom listener — overrides the default Camera2D \u002F Camera3D listener.\npublic partial class FollowCamListener : AudioListener3D\n{\n    public override void _Ready() => MakeCurrent();\n}\n```\n\n> ⚠️ **Changed in Godot 4.7:** The default `area_mask` on `AudioStreamPlayer2D`\u002F`AudioStreamPlayer3D` changed from `1` to `0` (disabled) — the `audio_bus_override` feature on `Area2D`\u002F`Area3D` (e.g. an underwater bus) stops working for players left at the default. Set `area_mask` back to layer 1 to restore it; masks explicitly set to anything other than layer 1 keep working. (The migration guide says \"AudioStreamPlayer\", but `area_mask` only exists on the 2D\u002F3D variants.) See the [4.7 migration guide](https:\u002F\u002Fdocs.godotengine.org\u002Fen\u002Flatest\u002Ftutorials\u002Fmigrating\u002Fupgrading_to_godot_4.7.html).\n\n---\n\n## 5. Music Manager (Autoload)\n\nCrossfade between background tracks via a singleton autoload that manages two `AudioStreamPlayer` nodes and tweens their volume_db. Wire a `Music` audio bus so the settings menu can adjust music separately.\n\n> See [references\u002Fmusic-manager.md](references\u002Fmusic-manager.md) for the full GDScript and C# autoload (crossfade, fade-out stop, music bus volume).\n\n---\n\n## 6. SFX Pool\n\nPre-instantiate a fixed pool of `AudioStreamPlayer` nodes; `play_sfx(stream)` finds the next free player and plays. Avoids per-shot instancing churn for high-volume effects (gunshots, footsteps, hits).\n\n> See [references\u002Fsfx-pooling.md](references\u002Fsfx-pooling.md) for the GDScript + C# pooled player and a 2D positional variant (pool of `AudioStreamPlayer2D` nodes that follow a target).\n\n---\n\n## 7. Audio Settings Integration\n\nWire HSliders in the settings menu to bus volumes via `AudioServer.set_bus_volume_db(bus_idx, linear_to_db(value))`. Persist with `ConfigFile`. Use the `linear_to_db` \u002F `db_to_linear` helpers — never log-base by hand.\n\n> See [references\u002Faudio-settings.md](references\u002Faudio-settings.md) for the full settings menu wiring with persistence (GDScript + C#).\n\n---\n\n## 8. Interactive & Adaptive Music (Godot 4.3+)\n\nThree stream types for adaptive music: `AudioStreamPlaylist` (sequenced or shuffled tracks), `AudioStreamSynchronized` (multiple stems played in sync — vertical layering for combat intensity), `AudioStreamInteractive` (clip transitions on triggers — state-driven music). Godot 4.4+ adds `AudioStreamWAV.load_from_file()` for runtime WAV loading.\n\n> **Godot 4.7+:** `AudioStreamInteractive` now exposes `TRANSITION_TO_TIME_PREVIOUS_POSITION` (`TransitionToTime` enum) to scripts — the destination clip resumes from its last played position if there was a previous transition from that clip, otherwise it plays from its start. Ideal for exploration ↔ combat music that picks up where it left off.\n\n> See [references\u002Finteractive-music.md](references\u002Finteractive-music.md) for the stream-type comparison, GDScript recipes, the 4.7+ resume-position transition, and the 4.4+ runtime-load example.\n\n---\n\n## 9. Audio Import Best Practices\n\n| Format    | Use For        | File Size | Decode Latency | Loop Support  |\n|-----------|----------------|-----------|----------------|---------------|\n| **WAV**   | Short SFX      | Large     | None (PCM) \u002F light (QOA, 4.4+ default) | Via import    |\n| **OGG**   | Music, long SFX| Small     | Minimal        | Via import    |\n| **MP3**   | Music (fallback)| Small    | Has padding    | Via import    |\n\n### Import Settings\n\nIn the Import dock (select an audio file):\n\n- **Loop:** Enable for music and ambient loops\n- **BPM \u002F Beat Count \u002F Bar Beats:** Set for rhythm-synced games\n- **Force Mono** (WAV only): Enable for 3D positional audio (stereo doesn't spatialize well); export OGG\u002FMP3 as mono from your audio editor\n\n> **Tip:** Keep SFX as 16-bit WAV at 44.1kHz. Set the WAV import **Compress > Mode** to PCM (Uncompressed) for zero decode overhead — 4.4+ defaults to QOA (4.3 defaults to PCM, labelled Disabled). For music, OGG Vorbis at quality 6–8 is a good balance.\n\n---\n\n## 11. Common Pitfalls\n\n| Symptom                            | Cause                                          | Fix                                                               |\n|------------------------------------|-------------------------------------------------|-------------------------------------------------------------------|\n| Sound doesn't play                 | Player not in the scene tree                    | Ensure the AudioStreamPlayer is `add_child()`'d before `play()`  |\n| Sound plays but no audio heard     | Bus muted or turned down                        | Check the bus in the Audio panel; a misspelled `bus` name falls back to `Master` (bypassing your bus) |\n| Music restarts on scene change     | Player is part of the scene, not an autoload    | Move music player to an autoload (MusicManager)                   |\n| 3D positional audio is silent      | No current Camera3D or AudioListener3D (2D uses the screen centre) | Add an AudioListener3D or ensure a Camera3D is current |\n| Sound clicks or pops               | Audio file has no fade-in\u002Ffade-out              | Add a tiny fade (2–5ms) at start\u002Fend of WAV in audio editor      |\n| Too many sounds playing at once    | No polyphony limit                              | Set `max_polyphony` on players or use an SFX pool                 |\n| Volume slider feels non-linear     | Using dB directly instead of linear conversion  | Use `linear_to_db()` \u002F `db_to_linear()` for slider values        |\n| 3D audio sounds mono\u002Fflat          | Stereo source file                              | Use mono files (WAV: Force Mono in Import tab) for 3D spatialization |\n| MP3 has silence at start           | Encoder padding in the file                     | Use WAV for timing-critical SFX, OGG for music                   |\n\n---\n\n## 12. Implementation Checklist\n\n- [ ] Audio buses are set up: Master, Music, SFX (minimum)\n- [ ] All AudioStreamPlayer nodes have the correct `bus` property assigned\n- [ ] Music uses OGG Vorbis format; short SFX uses WAV\n- [ ] Music player is in an autoload (survives scene changes)\n- [ ] Music crossfading is implemented for smooth transitions\n- [ ] SFX pool is used instead of creating new AudioStreamPlayer nodes dynamically\n- [ ] Volume sliders use `linear_to_db()` \u002F `db_to_linear()` conversion\n- [ ] Near-zero slider values mute the bus (avoid `linear_to_db(0.0)` = `-inf`)\n- [ ] 3D audio sources use mono audio files for proper spatialization\n- [ ] Audio settings are saved and restored on game launch (ConfigFile or similar)\n- [ ] Looping is configured on the AudioStream resource, not in code\n- [ ] Interactive\u002Fadaptive music uses `AudioStreamPlaylist`, `AudioStreamSynchronized`, or `AudioStreamInteractive` (Godot 4.3+) instead of manual track-switching code\n","# Audio System in Godot 4.3+\n\nAll examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.\n\n> **Related skills:** **event-bus** for decoupled audio triggers, **save-load** for persisting audio settings, **resource-pattern** for audio data containers.\n\n---\n\n## 1. Core Concepts\n\n### Audio Node Types\n\n| Node                   | Dimensions | Use For                                       |\n|------------------------|------------|-----------------------------------------------|\n| `AudioStreamPlayer`    | Non-positional | Music, UI sounds, global SFX              |\n| `AudioStreamPlayer2D`  | 2D positional  | Footsteps, gunfire, environmental sounds  |\n| `AudioStreamPlayer3D`  | 3D positional  | Same as 2D but in 3D space                |\n\n### Audio Bus Architecture\n\nGodot routes all audio through **buses** (like a mixing console).\n\n```\nMaster (always exists)\n├── Music          → volume, effects for background music\n├── SFX            → volume, effects for sound effects\n│   ├── Footsteps  → sub-bus for fine-tuning\n│   └── Weapons    → sub-bus for fine-tuning\n└── UI             → volume for menu sounds\n```\n\n**Setup:** Bottom panel → Audio tab → Add buses, set names, route outputs.\n\nEvery AudioStreamPlayer has a `bus` property — set it to the target bus name (e.g., `\"SFX\"`, `\"Music\"`).\n\n---\n\n## 2. Basic Audio Playback\n\n### GDScript\n\n```gdscript\nextends Node2D\n\n@onready var sfx_player: AudioStreamPlayer2D = $AudioStreamPlayer2D\n@onready var music_player: AudioStreamPlayer = $MusicPlayer\n\nfunc _ready() -> void:\n    # Play background music (looping is set on the AudioStream resource)\n    music_player.play()\n\nfunc play_jump_sound() -> void:\n    sfx_player.stream = preload(\"res:\u002F\u002Faudio\u002Fsfx\u002Fjump.wav\")\n    sfx_player.play()\n```\n\n### C#\n\n```csharp\nusing Godot;\n\npublic partial class AudioExample : Node2D\n{\n    private AudioStreamPlayer2D _sfxPlayer;\n    private AudioStreamPlayer _musicPlayer;\n\n    public override void _Ready()\n    {\n        _sfxPlayer = GetNode\u003CAudioStreamPlayer2D>(\"AudioStreamPlayer2D\");\n        _musicPlayer = GetNode\u003CAudioStreamPlayer>(\"MusicPlayer\");\n        _musicPlayer.Play();\n    }\n\n    public void PlayJumpSound()\n    {\n        _sfxPlayer.Stream = GD.Load\u003CAudioStream>(\"res:\u002F\u002Faudio\u002Fsfx\u002Fjump.wav\");\n        _sfxPlayer.Play();\n    }\n}\n```\n\n### Looping Audio\n\nLooping is configured on the **AudioStream resource**, not the player node:\n\n- **WAV:** Import tab → Loop Mode → Forward (or Ping-Pong)\n- **OGG:** Import tab → Loop → On, set Loop Offset\n- **MP3:** Import tab → Loop → On\n\n> Always use OGG Vorbis for music (smaller files, good quality). Use WAV for short SFX (PCM or QOA, cheap to decode). Avoid MP3 for SFX — depending on the encoder it can start with padding silence.\n\n---\n\n## 3. Audio Bus Management\n\n### Setting Volume from Code\n\nGodot uses **decibels (dB)** for volume. Linear-to-dB conversion is required for sliders.\n\n#### GDScript\n\n```gdscript\n# Get bus index by name\nvar bus_index: int = AudioServer.get_bus_index(\"SFX\")\n\n# Set volume in dB directly\nAudioServer.set_bus_volume_db(bus_index, -6.0)  # -6 dB ≈ half amplitude (db_to_linear(-6.0) ≈ 0.5)\n\n# Convert linear (0.0–1.0) to dB — use for UI sliders\nfunc set_bus_volume_linear(bus_name: String, linear: float) -> void:\n    var index := AudioServer.get_bus_index(bus_name)\n    AudioServer.set_bus_volume_db(index, linear_to_db(linear))\n\n# Mute \u002F unmute a bus\nAudioServer.set_bus_mute(bus_index, true)\n\n# Read current volume as linear (for displaying on a slider)\nfunc get_bus_volume_linear(bus_name: String) -> float:\n    var index := AudioServer.get_bus_index(bus_name)\n    return db_to_linear(AudioServer.get_bus_volume_db(index))\n```\n\n#### C#\n\n```csharp\nint busIndex = AudioServer.GetBusIndex(\"SFX\");\n\n\u002F\u002F Set volume in dB\nAudioServer.SetBusVolumeDb(busIndex, -6.0f);\n\n\u002F\u002F Linear to dB conversion for UI sliders\npublic void SetBusVolumeLinear(string busName, float linear)\n{\n    int index = AudioServer.GetBusIndex(busName);\n    AudioServer.SetBusVolumeDb(index, Mathf.LinearToDb(linear));\n}\n\n\u002F\u002F Mute \u002F unmute\nAudioServer.SetBusMute(busIndex, true);\n\n\u002F\u002F Read current volume as linear\npublic float GetBusVolumeLinear(string busName)\n{\n    int index = AudioServer.GetBusIndex(busName);\n    return Mathf.DbToLinear(AudioServer.GetBusVolumeDb(index));\n}\n```\n\n### Audio Bus Effects\n\nAdd effects to buses in the Audio panel (bottom dock). Common effects:\n\n| Effect          | Use For                                     |\n|-----------------|---------------------------------------------|\n| `Reverb`        | Cave, cathedral, bathroom ambience           |\n| `Delay`         | Echo effects                                 |\n| `Compressor`    | Normalize loud\u002Fquiet sounds (master bus)     |\n| `HardLimiter`   | Prevent clipping on master bus (`Limiter` is deprecated) |\n| `LowPassFilter` | Muffled sounds (underwater, behind walls)    |\n| `HighPassFilter` | Thin\u002Ftinny sound (radio, phone)             |\n| `Chorus`        | Thicken sounds                               |\n| `Distortion`    | Gritty\u002Foverdrive effects                     |\n| `EQ`            | Fine-tune frequency bands                    |\n\n### Dynamic Effect Toggle\n\n```gdscript\n# Enable\u002Fdisable an effect on a bus at runtime\nvar bus_index := AudioServer.get_bus_index(\"SFX\")\nvar effect_index := 0  # First effect on the bus\nAudioServer.set_bus_effect_enabled(bus_index, effect_index, true)\n\n# Apply low-pass filter for \"underwater\" feel\nfunc set_underwater(enabled: bool) -> void:\n    var index := AudioServer.get_bus_index(\"SFX\")\n    # Assumes a LowPassFilter is the first effect on the SFX bus\n    AudioServer.set_bus_effect_enabled(index, 0, enabled)\n```\n\n---\n\n## 4. Spatial Audio (2D & 3D)\n\n### AudioStreamPlayer2D\n\nAutomatically adjusts volume and panning based on distance to the current `AudioListener2D` (or the centre of the screen if none is current).\n\n```\nEnemy (CharacterBody2D)\n├── Sprite2D\n└── AudioStreamPlayer2D   ← positioned at enemy's location\n    bus = \"SFX\"\n    max_distance = 1000.0\n    attenuation = 1.0\n```\n\nKey properties:\n\n| Property        | Description                                   | Default  |\n|-----------------|-----------------------------------------------|----------|\n| `max_distance`  | Beyond this distance, sound is silent          | 2000.0   |\n| `attenuation`   | Volume falloff curve (1.0 = linear, higher = sharper) | 1.0 |\n| `max_polyphony` | Max simultaneous instances of this player      | 1        |\n| `panning_strength` | How much the sound pans left\u002Fright          | 1.0      |\n\n### AudioStreamPlayer3D\n\nSame concept but in 3D. Works with `AudioListener3D` (or the Camera3D).\n\nKey additional properties:\n\n| Property            | Description                                 |\n|---------------------|---------------------------------------------|\n| `unit_size`         | Distance at which volume is 0 dB            |\n| `max_db`            | Maximum volume cap                          |\n| `attenuation_model` | Inverse, InverseSquare, Logarithmic, Disabled |\n| `doppler_tracking`  | Enable Doppler effect for moving sources    |\n\n### AudioListener\n\n```gdscript\n# Make a specific camera the audio listener\n# 2D: add AudioListener2D as child of Camera2D, call make_current()\n# 3D: add AudioListener3D as child of Camera3D, call make_current()\n\n# By default, the current Camera2D\u002F3D acts as the listener.\n# Only add an explicit AudioListener if you need a different listening position.\n```\n\n```csharp\n\u002F\u002F 2D spatial player\npublic partial class Footsteps : AudioStreamPlayer2D\n{\n    public override void _Ready()\n    {\n        Bus = \"SFX\";\n        MaxDistance = 1000.0f;     \u002F\u002F Pixels at which volume reaches zero\n        Attenuation = 1.0f;         \u002F\u002F Linear falloff (higher = sharper)\n        MaxPolyphony = 4;           \u002F\u002F Allow overlapping footstep sounds\n    }\n\n    public void PlayStep() => Play();\n}\n\n\u002F\u002F 3D spatial player\npublic partial class EngineHum : AudioStreamPlayer3D\n{\n    public override void _Ready()\n    {\n        Bus = \"SFX\";\n        UnitSize = 4.0f;            \u002F\u002F Meters at which volume is 0 dB\n        MaxDistance = 50.0f;\n        AttenuationModel = AttenuationModelEnum.InverseDistance;\n    }\n}\n\n\u002F\u002F Custom listener — overrides the default Camera2D \u002F Camera3D listener.\npublic partial class FollowCamListener : AudioListener3D\n{\n    public override void _Ready() => MakeCurrent();\n}\n```\n\n> ⚠️ **Changed in Godot 4.7:** The default `area_mask` on `AudioStreamPlayer2D`\u002F`AudioStreamPlayer3D` changed from `1` to `0` (disabled) — the `audio_bus_override` feature on `Area2D`\u002F`Area3D` (e.g. an underwater bus) stops working for players left at the default. Set `area_mask` back to layer 1 to restore it; masks explicitly set to anything other than layer 1 keep working. (The migration guide says \"AudioStreamPlayer\", but `area_mask` only exists on the 2D\u002F3D variants.) See the [4.7 migration guide](https:\u002F\u002Fdocs.godotengine.org\u002Fen\u002Flatest\u002Ftutorials\u002Fmigrating\u002Fupgrading_to_godot_4.7.html).\n\n---\n\n## 5. Music Manager (Autoload)\n\nCrossfade between background tracks via a singleton autoload that manages two `AudioStreamPlayer` nodes and tweens their volume_db. Wire a `Music` audio bus so the settings menu can adjust music separately.\n\n> See [references\u002Fmusic-manager.md](references\u002Fmusic-manager.md) for the full GDScript and C# autoload (crossfade, fade-out stop, music bus volume).\n\n---\n\n## 6. SFX Pool\n\nPre-instantiate a fixed pool of `AudioStreamPlayer` nodes; `play_sfx(stream)` finds the next free player and plays. Avoids per-shot instancing churn for high-volume effects (gunshots, footsteps, hits).\n\n> See [references\u002Fsfx-pooling.md](references\u002Fsfx-pooling.md) for the GDScript + C# pooled player and a 2D positional variant (pool of `AudioStreamPlayer2D` nodes that follow a target).\n\n---\n\n## 7. Audio Settings Integration\n\nWire HSliders in the settings menu to bus volumes via `AudioServer.set_bus_volume_db(bus_idx, linear_to_db(value))`. Persist with `ConfigFile`. Use the `linear_to_db` \u002F `db_to_linear` helpers — never log-base by hand.\n\n> See [references\u002Faudio-settings.md](references\u002Faudio-settings.md) for the full settings menu wiring with persistence (GDScript + C#).\n\n---\n\n## 8. Interactive & Adaptive Music (Godot 4.3+)\n\nThree stream types for adaptive music: `AudioStreamPlaylist` (sequenced or shuffled tracks), `AudioStreamSynchronized` (multiple stems played in sync — vertical layering for combat intensity), `AudioStreamInteractive` (clip transitions on triggers — state-driven music). Godot 4.4+ adds `AudioStreamWAV.load_from_file()` for runtime WAV loading.\n\n> **Godot 4.7+:** `AudioStreamInteractive` now exposes `TRANSITION_TO_TIME_PREVIOUS_POSITION` (`TransitionToTime` enum) to scripts — the destination clip resumes from its last played position if there was a previous transition from that clip, otherwise it plays from its start. Ideal for exploration ↔ combat music that picks up where it left off.\n\n> See [references\u002Finteractive-music.md](references\u002Finteractive-music.md) for the stream-type comparison, GDScript recipes, the 4.7+ resume-position transition, and the 4.4+ runtime-load example.\n\n---\n\n## 9. Audio Import Best Practices\n\n| Format    | Use For        | File Size | Decode Latency | Loop Support  |\n|-----------|----------------|-----------|----------------|---------------|\n| **WAV**   | Short SFX      | Large     | None (PCM) \u002F light (QOA, 4.4+ default) | Via import    |\n| **OGG**   | Music, long SFX| Small     | Minimal        | Via import    |\n| **MP3**   | Music (fallback)| Small    | Has padding    | Via import    |\n\n### Import Settings\n\nIn the Import dock (select an audio file):\n\n- **Loop:** Enable for music and ambient loops\n- **BPM \u002F Beat Count \u002F Bar Beats:** Set for rhythm-synced games\n- **Force Mono** (WAV only): Enable for 3D positional audio (stereo doesn't spatialize well); export OGG\u002FMP3 as mono from your audio editor\n\n> **Tip:** Keep SFX as 16-bit WAV at 44.1kHz. Set the WAV import **Compress > Mode** to PCM (Uncompressed) for zero decode overhead — 4.4+ defaults to QOA (4.3 defaults to PCM, labelled Disabled). For music, OGG Vorbis at quality 6–8 is a good balance.\n\n---\n\n## 11. Common Pitfalls\n\n| Symptom                            | Cause                                          | Fix                                                               |\n|------------------------------------|-------------------------------------------------|-------------------------------------------------------------------|\n| Sound doesn't play                 | Player not in the scene tree                    | Ensure the AudioStreamPlayer is `add_child()`'d before `play()`  |\n| Sound plays but no audio heard     | Bus muted or turned down                        | Check the bus in the Audio panel; a misspelled `bus` name falls back to `Master` (bypassing your bus) |\n| Music restarts on scene change     | Player is part of the scene, not an autoload    | Move music player to an autoload (MusicManager)                   |\n| 3D positional audio is silent      | No current Camera3D or AudioListener3D (2D uses the screen centre) | Add an AudioListener3D or ensure a Camera3D is current |\n| Sound clicks or pops               | Audio file has no fade-in\u002Ffade-out              | Add a tiny fade (2–5ms) at start\u002Fend of WAV in audio editor      |\n| Too many sounds playing at once    | No polyphony limit                              | Set `max_polyphony` on players or use an SFX pool                 |\n| Volume slider feels non-linear     | Using dB directly instead of linear conversion  | Use `linear_to_db()` \u002F `db_to_linear()` for slider values        |\n| 3D audio sounds mono\u002Fflat          | Stereo source file                              | Use mono files (WAV: Force Mono in Import tab) for 3D spatialization |\n| MP3 has silence at start           | Encoder padding in the file                     | Use WAV for timing-critical SFX, OGG for music                   |\n\n---\n\n## 12. Implementation Checklist\n\n- [ ] Audio buses are set up: Master, Music, SFX (minimum)\n- [ ] All AudioStreamPlayer nodes have the correct `bus` property assigned\n- [ ] Music uses OGG Vorbis format; short SFX uses WAV\n- [ ] Music player is in an autoload (survives scene changes)\n- [ ] Music crossfading is implemented for smooth transitions\n- [ ] SFX pool is used instead of creating new AudioStreamPlayer nodes dynamically\n- [ ] Volume sliders use `linear_to_db()` \u002F `db_to_linear()` conversion\n- [ ] Near-zero slider values mute the bus (avoid `linear_to_db(0.0)` = `-inf`)\n- [ ] 3D audio sources use mono audio files for proper spatialization\n- [ ] Audio settings are saved and restored on game launch (ConfigFile or similar)\n- [ ] Looping is configured on the AudioStream resource, not in code\n- [ ] Interactive\u002Fadaptive music uses `AudioStreamPlaylist`, `AudioStreamSynchronized`, or `AudioStreamInteractive` (Godot 4.3+) instead of manual track-switching code\n",{"name":5,"description":7},"master","d7b26cdb5fae14d4ef7b713c5bf259395e75c3c6","skills\u002Faudio-system",63,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter","https:\u002F\u002Fgithub.com\u002Fjame581","https:\u002F\u002Fjanmesarc.online\u002F","Software engineer. My biggest passion is game development.","2026-11-14 20:45:49",{"source":8,"skillName":5,"commands":52,"prompt":62,"zipAvailable":63},[53,56,59],{"tool":54,"command":55},"npx","npx skills add jame581\u002FGodotPrompter --skill audio-system",{"tool":57,"command":58},"bunx","bunx skills add jame581\u002FGodotPrompter --skill audio-system",{"tool":60,"command":61},"pnpm","pnpm dlx skills add jame581\u002FGodotPrompter --skill audio-system","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Faudio-system\u002FSKILL.md",true,[65,71,75,79],{"path":66,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":69,"sourceHtmlUrl":70},"references\u002Faudio-settings.md","REFERENCE","参考文档",3635,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Faudio-system\u002Freferences\u002Faudio-settings.md",{"path":72,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":73,"sourceHtmlUrl":74},"references\u002Finteractive-music.md",6907,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Faudio-system\u002Freferences\u002Finteractive-music.md",{"path":76,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":77,"sourceHtmlUrl":78},"references\u002Fmusic-manager.md",3670,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Faudio-system\u002Freferences\u002Fmusic-manager.md",{"path":80,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":81,"sourceHtmlUrl":82},"references\u002Fsfx-pooling.md",4469,"https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Faudio-system\u002Freferences\u002Fsfx-pooling.md",[84,104,125,150,174,191],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":37},"01M6KRFE5BR2PSD08ZKDAS66R7","xr-development","Use when building VR\u002FAR\u002FXR applications — OpenXR setup, XROrigin3D, hand tracking, controllers, passthrough, and Meta Quest deployment in Godot 4.3+","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fxr-development\u002FSKILL.md",[],[91,92,36,93,94,95,96,97,98,99,100,29,101,102,103],"xr development","development","deployment","godot","vr","setup","tracking","godot 4","ar","hand","Meta","applications","quest",{"skillNo":105,"name":106,"nameZh":6,"description":107,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":37},"01M6KRF8GZTG1TAS506MFBSGFC","web-services","Use when a Godot game calls a web server — HTTPRequest, downloads, REST\u002FJSON APIs, auth headers, WebSocketPeer clients, TLS, retries, and keeping secrets out of the build. Not for game networking\u002FRPCs (multiplayer-basics) or browser export (web-export)","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fweb-services\u002FSKILL.md",[],[111,112,113,114,115,116,117,118,29,36,94,119,120,121,122,123,124],"web services","web","services","tls","retries","calling","auth","downloads","clients","headers","secrets","json","build","REST",{"skillNo":126,"name":127,"nameZh":6,"description":128,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":129,"categories":130,"keywords":132,"publishedAt":37},"01M6KRF38Q4WSKAYFS56PG87T0","web-export","Use when shipping a Godot game to the browser — Web export preset options, threads vs no-threads and COOP\u002FCOEP headers, hosting on itch.io or your own server, PWA, JavaScriptBridge, user:\u002F\u002F persistence, audio and input limits, and load size","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fweb-export\u002FSKILL.md",[131],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[112,133,134,135,136,137,138,139,120,140,141,36,142,143,144,145,146,147,29,148,24,149],"export","web export","threads","limits","shipping","size","options","hosting","input","Coop","preset","browser","game","io","load","pwa","server",{"skillNo":151,"name":152,"nameZh":6,"description":153,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":154,"categories":155,"keywords":164,"publishedAt":37},"01M6KREYFETEBH62ZTN6EZH2X3","using-godot-prompter","Bootstrap skill — establishes how to find and use GodotPrompter skills, with platform-specific tool mapping","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fusing-godot-prompter\u002FSKILL.md",[156,159],{"categoryNo":157,"categoryName":158,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":160,"categoryName":161,"taxonomyType":162,"taxonomyTypeDesc":163},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[94,165,166,167,168,29,169,170,171,172,173],"using godot prompter","find","with","bootstrap","tool","platform","mapping","how","how to",{"skillNo":175,"name":176,"nameZh":6,"description":177,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":178,"categories":179,"keywords":180,"publishedAt":37},"01M6KRER5G7EQWKGAFN8QJKQ69","tween-animation","Use when implementing tweens — property animation, method tweening, chaining, parallel sequences, easing, and common UI\u002Fgameplay motion recipes","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Ftween-animation\u002FSKILL.md",[],[181,182,29,183,184,185,186,187,188,189,31,36,190],"tween animation","Animation","motion","parallel","gameplay","chaining","ui","recipes","common","sequences",{"skillNo":192,"name":193,"nameZh":6,"description":194,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":195,"categories":196,"keywords":197,"publishedAt":37},"01M6KREKGCQMVDV8WX7HWX8BZG","state-machine","Use when building a state machine or refactoring logic into one — enum, node, and resource-based FSM patterns with trade-offs. Not for adding states to an existing one","https:\u002F\u002Fgithub.com\u002Fjame581\u002FGodotPrompter\u002Fblob\u002Fmaster\u002Fskills\u002Fstate-machine\u002FSKILL.md",[],[198,199,200,94,36,201,202,203,204,205,167,29,31,206],"state","state machine","machine","patterns","node","fsm","state machines","trade","trade-offs"]