Audio

Audio System

AudioStreamPlayer (Non-positional)

Basic Playback

extends Node

@onready var audio_player = $AudioStreamPlayer

func _ready():
    audio_player.play()
    audio_player.play(0.5)  # Start at 0.5 seconds
    audio_player.volume_db = -10
    audio_player.pitch_scale = 1.2

func play_sfx():
    audio_player.play()

func stop_sfx():
    audio_player.stop()

One-Shot Sound Effects

extends Node

var sfx_scene = preload("res://audio/sfx_player.tscn")

func play_sfx(stream: AudioStream, volume: float = 0.0):
    var player = sfx_scene.instantiate()
    player.stream = stream
    player.volume_db = volume
    add_child(player)
    player.play()
    player.finished.connect(player.queue_free)

AudioStreamPlayer2D (2D Positional)

extends Node2D

@onready var audio = $AudioStreamPlayer2D

func _ready():
    audio.max_distance = 500
    audio.attenuation = 2.0
    audio.play()

AudioStreamPlayer3D (3D Positional)

extends Node3D

@onready var audio = $AudioStreamPlayer3D

func _ready():
    audio.max_distance = 20.0
    audio.attenuation_model = AudioStreamPlayer3D.ATTENUATION_INVERSE_DISTANCE
    audio.play()

Audio Bus Management

Setup in Code

extends Node

func _ready():
    var music_bus = AudioServer.get_bus_index("Music")
    var sfx_bus = AudioServer.get_bus_index("SFX")

    AudioServer.set_bus_volume_db(music_bus, linear_to_db(0.8))
    AudioServer.set_bus_volume_db(sfx_bus, linear_to_db(1.0))
    AudioServer.set_bus_mute(music_bus, true)

Adding Effects

func add_reverb_to_bus(bus_name: String):
    var bus_idx = AudioServer.get_bus_index(bus_name)
    var reverb = AudioEffectReverb.new()
    reverb.room_size = 0.8
    reverb.damping = 0.5
    reverb.wet = 0.3
    AudioServer.add_bus_effect(bus_idx, reverb)

Music System

extends Node

@onready var music_player = $AudioStreamPlayer
@onready var ambient_player = $AudioStreamPlayer2

var current_track: String = ""

func play_music(track_path: String, fade_time: float = 1.0):
    if current_track == track_path:
        return

    current_track = track_path
    var tween = create_tween()
    tween.tween_property(music_player, "volume_db", -80.0, fade_time)
    await tween.finished

    music_player.stream = load(track_path)
    music_player.volume_db = -80.0
    music_player.play()

    tween = create_tween()
    tween.tween_property(music_player, "volume_db", 0.0, fade_time)

func crossfade_music(new_track: String, duration: float = 2.0):
    var new_player = AudioStreamPlayer.new()
    new_player.stream = load(new_track)
    new_player.volume_db = -80.0
    add_child(new_player)
    new_player.play()

    var tween = create_tween()
    tween.set_parallel(true)
    tween.tween_property(music_player, "volume_db", -80.0, duration)
    tween.tween_property(new_player, "volume_db", 0.0, duration)

    await tween.finished
    music_player.stop()
    music_player = new_player
    current_track = new_track

Dynamic Audio

extends Node

@onready var engine_sound = $AudioStreamPlayer

func _process(delta):
    var speed_ratio = current_speed / max_speed
    engine_sound.pitch_scale = lerp(0.8, 2.0, speed_ratio)
    engine_sound.volume_db = lerp(-20, 0, speed_ratio)

Audio Pooling

extends Node

var pool_size = 10
var audio_pool: Array[AudioStreamPlayer] = []

func _ready():
    for i in pool_size:
        var player = AudioStreamPlayer.new()
        add_child(player)
        audio_pool.append(player)

func play_sound(stream: AudioStream) -> AudioStreamPlayer:
    for player in audio_pool:
        if not player.playing:
            player.stream = stream
            player.play()
            return player

    var player = audio_pool[0]
    player.stream = stream
    player.play()
    return player

Best Practices

1. Use audio buses: Organize Music, SFX, Voice
2. Pool audio players: Reuse for performance
3. Fade transitions: Smooth music changes
4. Positional audio: Use 2D/3D players for spatial sound
5. Compression: Use OGG for music, WAV for short SFX
6. Volume normalization: Consistent levels across sounds

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LeeX852
• Source: LeeX852/skills
• License: MIT

Install and usage instructions live in the source repository linked above.