Godot音频系统专家指南：混音架构、空间音频与性能优化最佳实践

godot-audio-systems by thedivergentai/gd-agentic-skills

112 周安装量

74 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/thedivergentai/gd-agentic-skills --skill godot-audio-systems

音频处理游戏性能优化

🇨🇳中文介绍

音频系统

关于 Godot 音频引擎与混音架构的专家级指导。

绝对禁止事项（专家音频规则）

混音与音频总线

绝对禁止使用线性值设置总线音量 — set_bus_volume_db() 是对数函数。为滑块使用 linear_to_db()，否则在最后 5% 之前所有声音都会听起来太响。
绝对禁止跳过“总线路由” — 在 'SFX' 总线上播放音乐会使音量菜单失效。严格将每个播放器路由到其专用的子总线（音乐、音效、用户界面、语音）。
绝对禁止将‘主总线’用于游戏音效 — 将主总线专用于最终限幅。将所有游戏音效路由到子分组，以便你可以静音/闪避音效类别。

定位与空间音频

绝对禁止在没有衰减模型的情况下使用 3D 播放器 — 默认值是 NONE。如果不将其设置为 Inverse Distance，地图另一端的耳语声也会是全局音量。
绝对禁止在监听器正上方播放 3D 声音 — 会导致“声像抖动”，即声音在左右扬声器之间突然切换。偏移 0.1 个单位。
绝对禁止忘记为高速物体设置多普勒效应 — 一辆飞驰而过的汽车如果没有 DOPPLER_TRACKING_PHYSICS_STEP，会感觉平淡且静止。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

AudioStreamPlayer 变体

AudioStreamPlayer（全局/用户界面）

# 无空间定位，各处音量相同
# 适用于：音乐、用户界面音效、旁白

@onready var music := AudioStreamPlayer.new()

func _ready() -> void:
    music.stream = load("res://audio/music_main.ogg")
    music.volume_db = -10  # 更安静
    music.autoplay = false
    music.bus = "Music"  # 路由到音乐总线
    add_child(music)
    music.play()

AudioStreamPlayer2D（定位）

# 基于与摄像机距离的 2D 声像定位
# 适用于：2D 游戏、俯视角音频提示

extends Area2D

@onready var footstep := AudioStreamPlayer2D.new()

func _ready() -> void:
    footstep.stream = load("res://audio/footstep.ogg")
    footstep.max_distance = 500  # 可听范围（像素）
    footstep.attenuation = 2.0  # 衰减曲线（值越高，淡出越快）
    add_child(footstep)

func play_footstep() -> void:
    if not footstep.playing:
        footstep.play()

AudioStreamPlayer3D（空间）

# 具备多普勒效应、混响发送的 3D 空间音频
# 适用于：3D 游戏、逼真的声音定位

extends Node3D

@onready var explosion := AudioStreamPlayer3D.new()

func _ready() -> void:
    explosion.stream = load("res://audio/explosion.ogg")
    explosion.unit_size = 10.0  # 声源大小
    explosion.max_distance = 100.0  # 范围
    explosion.attenuation_model = AudioStreamPlayer3D.ATTENUATION_INVERSE_DISTANCE
    explosion.doppler_tracking = AudioStreamPlayer3D.DOPPLER_TRACKING_PHYSICS_STEP
    add_child(explosion)
    
    explosion.play()

总线设置（项目设置）

Master (始终存在)
  ├─ Music
  │   └─ Effects: Compressor, EQ
  ├─ SFX
  │   └─ Effects: Reverb (for environment)
  └─ Ambient
      └─ Effects: LowPassFilter (muffled ambience)

音量控制（分贝）

# ❌ 错误做法：线性音量（无效）
AudioServer.set_bus_volume_db(music_bus_idx, 0.5)  # 错误！

# ✅ 正确做法：使用分贝
var music_bus := AudioServer.get_bus_index("Music")
AudioServer.set_bus_volume_db(music_bus, -10)  # -10 分贝（更安静）

# 将线性值（0.0-1.0）转换为分贝：
var linear_volume := 0.5  # 50%
var db := linear_to_db(linear_volume)  # 约 -6 分贝
AudioServer.set_bus_volume_db(music_bus, db)

# 将分贝转换为线性值：
var current_db := AudioServer.get_bus_volume_db(music_bus)
var linear := db_to_linear(current_db)
print("当前音量：%d%%" % int(linear * 100))

func toggle_mute(bus_name: String) -> void:
    var bus_idx := AudioServer.get_bus_index(bus_name)
    var is_muted := AudioServer.is_bus_mute(bus_idx)
    AudioServer.set_bus_mute(bus_idx, not is_muted)

音频池化（性能）

问题：每帧都创建播放器

# ❌ 错误做法：在 60 FPS 下每秒创建 60 个新节点
func play_footstep() -> void:
    var player := AudioStreamPlayer.new()
    add_child(player)
    player.stream = load("res://audio/footstep.ogg")
    player.finished.connect(player.queue_free)
    player.play()
    # 结果：1 分钟内创建了 3600 个节点！

解决方案：音频池

# audio_pool.gd (自动加载)
extends Node

const POOL_SIZE = 10
var pool: Array[AudioStreamPlayer] = []
var pool_index := 0

func _ready() -> void:
    # 预创建播放器
    for i in range(POOL_SIZE):
        var player := AudioStreamPlayer.new()
        player.bus = "SFX"
        add_child(player)
        pool.append(player)

func play_sound(stream: AudioStream, volume_db := 0.0) -> void:
    var player := pool[pool_index]
    pool_index = (pool_index + 1) % POOL_SIZE  # 循环轮转
    
    # 如果之前的音效仍在播放，则停止它
    if player.playing:
        player.stop()
    
    player.stream = stream
    player.volume_db = volume_db
    player.play()

# 用法：
AudioPool.play_sound(load("res://audio/coin.ogg"), -5.0)

音轨间的淡入淡出

# music_manager.gd (自动加载)
extends Node

@onready var track_a := AudioStreamPlayer.new()
@onready var track_b := AudioStreamPlayer.new()

var current_track: AudioStreamPlayer
var fade_duration := 2.0

func _ready() -> void:
    track_a.bus = "Music"
    track_b.bus = "Music"
    add_child(track_a)
    add_child(track_b)
    current_track = track_a

func crossfade_to(new_stream: AudioStream) -> void:
    var next_track := track_b if current_track == track_a else track_a
    
    # 以 0 分贝开始新音轨
    next_track.stream = new_stream
    next_track.volume_db = -80  # 静音
    next_track.play()
    
    # 淡出当前音轨，淡入下一个音轨
    var tween := create_tween().set_parallel(true)
    tween.tween_property(current_track, "volume_db", -80, fade_duration)
    tween.tween_property(next_track, "volume_db", 0, fade_duration)
    
    await tween.finished
    
    # 停止旧音轨
    current_track.stop()
    current_track = next_track

# 在节拍边界进行过渡
var bpm := 120.0  # 每分钟节拍数
var beat_duration := 60.0 / bpm  # 每拍 0.5 秒

func queue_transition_on_beat(new_stream: AudioStream) -> void:
    # 等待下一个节拍
    var current_time := current_track.get_playback_position()
    var time_to_next_beat := beat_duration - fmod(current_time, beat_duration)
    
    await get_tree().create_timer(time_to_next_beat).timeout
    crossfade_to(new_stream)

在运行时添加效果

# 为音效总线添加混响
var sfx_bus := AudioServer.get_bus_index("SFX")
var reverb := AudioEffectReverb.new()
reverb.room_size = 0.8  # 大房间
reverb.damping = 0.5
reverb.wet = 0.3  # 30% 效果，70% 干声
AudioServer.add_bus_effect(sfx_bus, reverb)

func set_underwater(enabled: bool) -> void:
    var sfx_bus := AudioServer.get_bus_index("SFX")
    
    if enabled:
        # 添加低通滤波器（声音模糊）
        var lowpass := AudioEffectLowPassFilter.new()
        lowpass.cutoff_hz = 500  # 切除 500 Hz 以上的频率
        AudioServer.add_bus_effect(sfx_bus, lowpass)
    else:
        # 移除所有效果
        for i in range(AudioServer.get_bus_effect_count(sfx_bus)):
            AudioServer.remove_bus_effect(sfx_bus, 0)

# 生成简单的正弦波
func create_beep(frequency: float, duration: float) -> AudioStreamGenerator:
    var stream := AudioStreamGenerator.new()
    stream.mix_rate = 44100  # 采样率
    
    var playback := stream.instantiate_playback()
    
    var increment := frequency / stream.mix_rate
    var phase := 0.0
    
    for i in range(int(stream.mix_rate * duration)):
        var sample := sin(phase * TAU)
        playback.push_frame(Vector2(sample, sample))  # 立体声
        phase += increment
        phase = fmod(phase, 1.0)
    
    return stream

# 用法：
var beep_stream := create_beep(440.0, 0.1)  # 440 赫兹 (A4)，0.1 秒
$AudioStreamPlayer.stream = beep_stream
$AudioStreamPlayer.play()

音频闪避（对话时降低音乐音量）

# auto_duck.gd (位于对话 AudioStreamPlayer 上)
extends AudioStreamPlayer

func _ready() -> void:
    playing.connect(_on_playing)
    finished.connect(_on_finished)

func _on_playing() -> void:
    # 将音乐闪避到 -15 分贝
    var music_bus := AudioServer.get_bus_index("Music")
    var tween := create_tween()
    tween.tween_method(set_music_volume, 0.0, -15.0, 0.5)

func _on_finished() -> void:
    # 将音乐恢复到 0 分贝
    var tween := create_tween()
    tween.tween_method(set_music_volume, -15.0, 0.0, 0.5)

func set_music_volume(db: float) -> void:
    var music_bus := AudioServer.get_bus_index("Music")
    AudioServer.set_bus_volume_db(music_bus, db)

随机化音高以产生变化

# 防止声音完全相同（脚步声、枪声）
func play_varied_sound(stream: AudioStream) -> void:
    $AudioStreamPlayer.stream = stream
    $AudioStreamPlayer.pitch_scale = randf_range(0.9, 1.1)  # ±10% 音高变化
    $AudioStreamPlayer.play()

分层音乐（自适应）

# 基于强度的音乐分层（从安静开始，随着强度增加添加层）
# 示例：和平探索 → 战斗

@onready var layer_drums := $Music/Drums
@onready var layer_bass := $Music/Bass
@onready var layer_melody := $Music/Melody

var intensity := 0.0  # 0.0 = 平静，1.0 = 激烈

func _ready() -> void:
    # 同步开始所有层
    layer_drums.play()
    layer_bass.play()
    layer_melody.play()
    
    # 静音高强度层
    layer_bass.volume_db = -80
    layer_melody.volume_db = -80

func set_music_intensity(new_intensity: float) -> void:
    intensity = clamp(new_intensity, 0.0, 1.0)
    
    # 根据强度淡入各层
    var tween := create_tween().set_parallel(true)
    
    # 第 1 层（鼓）：始终可听
    tween.tween_property(layer_drums, "volume_db", 0, 1.0)
    
    # 第 2 层（贝斯）：在 33% 强度时淡入
    var bass_db := -80 if intensity < 0.33 else lerp(-80.0, 0.0, (intensity - 0.33) / 0.67)
    tween.tween_property(layer_bass, "volume_db", bass_db, 1.0)
    
    # 第 3 层（旋律）：在 66% 强度时淡入
    var melody_db := -80 if intensity < 0.66 else lerp(-80.0, 0.0, (intensity - 0.66) / 0.34)
    tween.tween_property(layer_melody, "volume_db", melody_db, 1.0)

# 用法（战斗系统）：
func _on_enemy_spotted() -> void:
    MusicManager.set_music_intensity(1.0)  # 全强度

func _on_all_enemies_defeated() -> void:
    MusicManager.set_music_intensity(0.0)  # 恢复平静

# 不播放玩家听不到的声音
extends AudioStreamPlayer3D

func _process(delta: float) -> void:
    var listener := get_viewport().get_camera_3d()
    if not listener:
        return
    
    var distance := global_position.distance_to(listener.global_position)
    
    if distance > max_distance * 1.5:  # 1.5 倍最大范围
        if playing:
            stop()

# 检查：
# 1. 是否分配了音频流？
if not $AudioStreamPlayer.stream:
    push_error("未分配音频流！")

# 2. 总线是否静音？
var bus_idx := AudioServer.get_bus_index($AudioStreamPlayer.bus)
if AudioServer.is_bus_mute(bus_idx):
    print("总线已静音！")

# 3. 音量是否太低？
if $AudioStreamPlayer.volume_db < -60:
    print("音量太安静（< -60 分贝）")

决策矩阵：选择哪个 AudioStreamPlayer？

功能	AudioStreamPlayer	AudioStreamPlayer2D	AudioStreamPlayer3D
空间性	❌ 全局	✅ 2D 声像定位	✅ 3D 定位
多普勒效应	❌	❌	✅
衰减	❌	✅ 基于距离	✅ 3D 衰减
混响发送	❌	❌	✅
适用于	音乐、用户界面	2D 游戏	3D 游戏
性能	最快	中等	最慢

主技能：godot-master

2026 年 2 月 10 日

🇺🇸English

Audio Systems

Expert guidance for Godot's audio engine and mixing architecture.

NEVER Do (Expert Audio Rules)

Mixing & Buses

NEVER set bus volume with linear values — set_bus_volume_db() is logarithmic. Use linear_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.1 units.
NEVER forget Doppler for high-speed objects — A car flying by without DOPPLER_TRACKING_PHYSICS_STEP feels 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 Tween to bridge tracks.

Available Scripts

MANDATORY : Read the appropriate script before implementing the corresponding pattern.

audio_voice_pool_manager.gd

Expert high-performance voice pooler with priority-based 'voice stealing' logic.

audio_occlusion_raycast.gd

Professional Raycast-based audio occlusion for dynamic muffling behind walls.

audio_adaptive_music_player.gd

BPM-synced horizontal re-sequencer for seamless musical transitions.

audio_reactive_visualizer_component.gd

Expert FFT spectrum analysis component for driving logic-to-data visuals.

audio_bus_ducker_logic.gd

Professional sidechain-style bus ducking (Dialogue-over-Music).

audio_procedural_generator_synth.gd

Expert real-time synthesizer for procedural hums, engines, and signals.

audio_environmental_reverb_zone.gd

Dynamic reverb/bus effect management via Area3D trigger zones.

audio_voice_limiter_manager.gd

Concurrency manager that prevents 'Ear Bleed' by capping identical SFX instances.

audio_linear_volume_interpolator.gd

Expert helper for smooth, musically-accurate UI volume slider mapping.

audio_footstep_surface_selector.gd

Physics-driven surface detection and sound-bank selector for footsteps.

AudioStreamPlayer Variants

AudioStreamPlayer (Global/UI)

# No spatial positioning, same volume everywhere
# Use for: Music, UI sounds, voiceovers

@onready var music := AudioStreamPlayer.new()

func _ready() -> void:
    music.stream = load("res://audio/music_main.ogg")
    music.volume_db = -10  # Quieter
    music.autoplay = false
    music.bus = "Music"  # Route to Music bus
    add_child(music)
    music.play()

AudioStreamPlayer2D (Positional)

# 2D panning based on distance from camera
# Use for: 2D games, top-down audio cues

extends Area2D

@onready var footstep := AudioStreamPlayer2D.new()

func _ready() -> void:
    footstep.stream = load("res://audio/footstep.ogg")
    footstep.max_distance = 500  # Audible range (pixels)
    footstep.attenuation = 2.0  # Falloff curve (higher = faster fadeout)
    add_child(footstep)

func play_footstep() -> void:
    if not footstep.playing:
        footstep.play()

AudioStreamPlayer3D (Spatial)

# 3D spatial audio with doppler, reverb send
# Use for: 3D games, realistic sound positioning

extends Node3D

@onready var explosion := AudioStreamPlayer3D.new()

func _ready() -> void:
    explosion.stream = load("res://audio/explosion.ogg")
    explosion.unit_size = 10.0  # Size of sound source
    explosion.max_distance = 100.0  # Range
    explosion.attenuation_model = AudioStreamPlayer3D.ATTENUATION_INVERSE_DISTANCE
    explosion.doppler_tracking = AudioStreamPlayer3D.DOPPLER_TRACKING_PHYSICS_STEP
    add_child(explosion)
    
    explosion.play()

AudioBus Architecture

Bus Setup (Project Settings)

Master (always exists)
  ├─ Music
  │   └─ Effects: Compressor, EQ
  ├─ SFX
  │   └─ Effects: Reverb (for environment)
  └─ Ambient
      └─ Effects: LowPassFilter (muffled ambience)

Volume Control (Decibels)

# ❌ BAD: Linear volume (doesn't work)
AudioServer.set_bus_volume_db(music_bus_idx, 0.5)  # WRONG!

# ✅ GOOD: Use decibels
var music_bus := AudioServer.get_bus_index("Music")
AudioServer.set_bus_volume_db(music_bus, -10)  # -10 dB (quieter)

# Convert linear (0.0-1.0) to dB:
var linear_volume := 0.5  # 50%
var db := linear_to_db(linear_volume)  # ~-6 dB
AudioServer.set_bus_volume_db(music_bus, db)

# Convert dB to linear:
var current_db := AudioServer.get_bus_volume_db(music_bus)
var linear := db_to_linear(current_db)
print("Current volume: %d%%" % int(linear * 100))

Mute Bus

func toggle_mute(bus_name: String) -> void:
    var bus_idx := AudioServer.get_bus_index(bus_name)
    var is_muted := AudioServer.is_bus_mute(bus_idx)
    AudioServer.set_bus_mute(bus_idx, not is_muted)

Audio Pooling (Performance)

Problem: Creating Players Every Frame

# ❌ BAD: Creates 60 new nodes/second at 60 FPS
func play_footstep() -> void:
    var player := AudioStreamPlayer.new()
    add_child(player)
    player.stream = load("res://audio/footstep.ogg")
    player.finished.connect(player.queue_free)
    player.play()
    # Result: 3600 nodes created in 1 minute!

Solution: Audio Pool

# audio_pool.gd (AutoLoad)
extends Node

const POOL_SIZE = 10
var pool: Array[AudioStreamPlayer] = []
var pool_index := 0

func _ready() -> void:
    # Pre-create players
    for i in range(POOL_SIZE):
        var player := AudioStreamPlayer.new()
        player.bus = "SFX"
        add_child(player)
        pool.append(player)

func play_sound(stream: AudioStream, volume_db := 0.0) -> void:
    var player := pool[pool_index]
    pool_index = (pool_index + 1) % POOL_SIZE  # Round-robin
    
    # Stop previous sound if still playing
    if player.playing:
        player.stop()
    
    player.stream = stream
    player.volume_db = volume_db
    player.play()

# Usage:
AudioPool.play_sound(load("res://audio/coin.ogg"), -5.0)

Music Transitions

Crossfade Between Tracks

# music_manager.gd (AutoLoad)
extends Node

@onready var track_a := AudioStreamPlayer.new()
@onready var track_b := AudioStreamPlayer.new()

var current_track: AudioStreamPlayer
var fade_duration := 2.0

func _ready() -> void:
    track_a.bus = "Music"
    track_b.bus = "Music"
    add_child(track_a)
    add_child(track_b)
    current_track = track_a

func crossfade_to(new_stream: AudioStream) -> void:
    var next_track := track_b if current_track == track_a else track_a
    
    # Start new track at 0 dB
    next_track.stream = new_stream
    next_track.volume_db = -80  # Silent
    next_track.play()
    
    # Fade out current, fade in next
    var tween := create_tween().set_parallel(true)
    tween.tween_property(current_track, "volume_db", -80, fade_duration)
    tween.tween_property(next_track, "volume_db", 0, fade_duration)
    
    await tween.finished
    
    # Stop old track
    current_track.stop()
    current_track = next_track

BPM-Synced Transitions

# Transition on beat boundary
var bpm := 120.0  # Beats per minute
var beat_duration := 60.0 / bpm  # 0.5s per beat

func queue_transition_on_beat(new_stream: AudioStream) -> void:
    # Wait for next beat
    var current_time := current_track.get_playback_position()
    var time_to_next_beat := beat_duration - fmod(current_time, beat_duration)
    
    await get_tree().create_timer(time_to_next_beat).timeout
    crossfade_to(new_stream)

Dynamic Audio Effects

Add Effect at Runtime

# Add reverb to SFX bus
var sfx_bus := AudioServer.get_bus_index("SFX")
var reverb := AudioEffectReverb.new()
reverb.room_size = 0.8  # Large room
reverb.damping = 0.5
reverb.wet = 0.3  # 30% effect, 70% dry
AudioServer.add_bus_effect(sfx_bus, reverb)

Underwater Effect

func set_underwater(enabled: bool) -> void:
    var sfx_bus := AudioServer.get_bus_index("SFX")
    
    if enabled:
        # Add low-pass filter (muffled sound)
        var lowpass := AudioEffectLowPassFilter.new()
        lowpass.cutoff_hz = 500  # Cut frequencies above 500 Hz
        AudioServer.add_bus_effect(sfx_bus, lowpass)
    else:
        # Remove all effects
        for i in range(AudioServer.get_bus_effect_count(sfx_bus)):
            AudioServer.remove_bus_effect(sfx_bus, 0)

Procedural Audio

Synthesize Beep

# Generate simple sine wave
func create_beep(frequency: float, duration: float) -> AudioStreamGenerator:
    var stream := AudioStreamGenerator.new()
    stream.mix_rate = 44100  # Sample rate
    
    var playback := stream.instantiate_playback()
    
    var increment := frequency / stream.mix_rate
    var phase := 0.0
    
    for i in range(int(stream.mix_rate * duration)):
        var sample := sin(phase * TAU)
        playback.push_frame(Vector2(sample, sample))  # Stereo
        phase += increment
        phase = fmod(phase, 1.0)
    
    return stream

# Usage:
var beep_stream := create_beep(440.0, 0.1)  # 440 Hz (A4), 0.1s
$AudioStreamPlayer.stream = beep_stream
$AudioStreamPlayer.play()

Advanced Patterns

Audio Ducking (Lower Music During Dialogue)

# auto_duck.gd (on Dialogue AudioStreamPlayer)
extends AudioStreamPlayer

func _ready() -> void:
    playing.connect(_on_playing)
    finished.connect(_on_finished)

func _on_playing() -> void:
    # Duck music to -15 dB
    var music_bus := AudioServer.get_bus_index("Music")
    var tween := create_tween()
    tween.tween_method(set_music_volume, 0.0, -15.0, 0.5)

func _on_finished() -> void:
    # Restore music to 0 dB
    var tween := create_tween()
    tween.tween_method(set_music_volume, -15.0, 0.0, 0.5)

func set_music_volume(db: float) -> void:
    var music_bus := AudioServer.get_bus_index("Music")
    AudioServer.set_bus_volume_db(music_bus, db)

Randomize Pitch for Variation

# Prevent identical sounds (footsteps, gunshots)
func play_varied_sound(stream: AudioStream) -> void:
    $AudioStreamPlayer.stream = stream
    $AudioStreamPlayer.pitch_scale = randf_range(0.9, 1.1)  # ±10% pitch
    $AudioStreamPlayer.play()

Layered Music (Adaptive)

# Intensity-based music layers (start quiet, add layers as intensity increases)
# Example: Peaceful exploration → Combat

@onready var layer_drums := $Music/Drums
@onready var layer_bass := $Music/Bass
@onready var layer_melody := $Music/Melody

var intensity := 0.0  # 0.0 = calm, 1.0 = intense

func _ready() -> void:
    # Start all layers in sync
    layer_drums.play()
    layer_bass.play()
    layer_melody.play()
    
    # Mute high-intensity layers
    layer_bass.volume_db = -80
    layer_melody.volume_db = -80

func set_music_intensity(new_intensity: float) -> void:
    intensity = clamp(new_intensity, 0.0, 1.0)
    
    # Fade in layers based on intensity
    var tween := create_tween().set_parallel(true)
    
    # Layer 1 (drums): always audible
    tween.tween_property(layer_drums, "volume_db", 0, 1.0)
    
    # Layer 2 (bass): fade in at 33% intensity
    var bass_db := -80 if intensity < 0.33 else lerp(-80.0, 0.0, (intensity - 0.33) / 0.67)
    tween.tween_property(layer_bass, "volume_db", bass_db, 1.0)
    
    # Layer 3 (melody): fade in at 66% intensity
    var melody_db := -80 if intensity < 0.66 else lerp(-80.0, 0.0, (intensity - 0.66) / 0.34)
    tween.tween_property(layer_melody, "volume_db", melody_db, 1.0)

# Usage (combat system):
func _on_enemy_spotted() -> void:
    MusicManager.set_music_intensity(1.0)  # Full intensity

func _on_all_enemies_defeated() -> void:
    MusicManager.set_music_intensity(0.0)  # Back to calm

Performance Optimization

Disable Far Audio

# Don't play sounds the player can't hear
extends AudioStreamPlayer3D

func _process(delta: float) -> void:
    var listener := get_viewport().get_camera_3d()
    if not listener:
        return
    
    var distance := global_position.distance_to(listener.global_position)
    
    if distance > max_distance * 1.5:  # 1.5x max range
        if playing:
            stop()

Edge Cases

Audio Doesn't Play

# Check:
# 1. Is stream assigned?
if not $AudioStreamPlayer.stream:
    push_error("No audio stream assigned!")

# 2. Is bus muted?
var bus_idx := AudioServer.get_bus_index($AudioStreamPlayer.bus)
if AudioServer.is_bus_mute(bus_idx):
    print("Bus is muted!")

# 3. Is volume too low?
if $AudioStreamPlayer.volume_db < -60:
    print("Volume too quiet (< -60 dB)")

Decision Matrix: Which AudioStreamPlayer?

Feature	AudioStreamPlayer	AudioStreamPlayer2D	AudioStreamPlayer3D
Spatial	❌ Global	✅ 2D panning	✅ 3D positioning
Doppler	❌	❌	✅
Attenuation	❌	✅ Distance-based	✅ 3D falloff
Reverb send	❌	❌	✅
Use for	Music, UI	2D games	3D games
Performance	Fastest	Medium	Slowest

Reference

Master Skill: godot-master

Weekly Installs

Repository

thedivergentai/…c-skills

GitHub Stars

First Seen

Feb 10, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

gemini-cli92

opencode92

codex92

kimi-cli90

amp90

github-copilot90

AI播客创作工具 - 使用inference.sh CLI快速生成AI驱动播客和音频内容

7,800 周安装