3D-аудио и AudioBus

В Godot аудио — отдельный сервер (AudioServer) с маршрутизацией через AudioBus. У сцены — несколько узлов-плееров, у проекта — единый микшер.

Узлы воспроизведения

Три варианта:

• AudioStreamPlayer — без позиционирования. Музыка, UI-звуки, диалоги.
• AudioStreamPlayer2D — позиционный для 2D-сцен (громкость по дистанции к слушателю).
• AudioStreamPlayer3D — 3D-позиционный с attenuation, Doppler, area reverb.

@onready var step_player: AudioStreamPlayer3D = $StepPlayer

func _ready() -> void:
    step_player.stream = preload("res://audio/step.ogg")

func play_step() -> void:
    step_player.pitch_scale = randf_range(0.9, 1.1)  # вариация для естественности
    step_player.play()

Главные свойства AudioStreamPlayer3D:

• stream — AudioStream-ресурс (AudioStreamOggVorbis, AudioStreamMP3, AudioStreamWAV).
• volume_db — громкость в децибелах. 0 — оригинал, -10 — тише, -80 — почти тишина.
• pitch_scale — множитель скорости/высоты.
• unit_size — фактор затухания (default 10.0). Чем больше значение — тем дальше звук слышен. Конкретная формула зависит от attenuation_model. Не “расстояние половинной громкости”, а параметр кривой.
• max_distance — на каком расстоянии звук затихнет полностью (0 = без ограничения).
• attenuation_model — INVERSE_DISTANCE, INVERSE_SQUARE_DISTANCE, LOGARITHMIC, DISABLED.
• doppler_tracking — Doppler эффект (IDLE_STEP / PHYSICS_STEP / DISABLED).
• area_mask — битмаска слоёв Area3D, на которые этот плеер реагирует (Area3D с reverb/bus override на соответствующих слоях переопределит обработку звука этого плеера, например “underwater”-эффект в зоне воды).

AudioBus — микшер

Открывается в нижней панели: вкладка Audio. Структура:

Master (главный, есть всегда)
├── Music
├── SFX
│   ├── Voice
│   └── Ambience
└── UI

Каждый bus:

• Volume — слайдер.
• Solo / Mute / Bypass.
• Effects — стек эффектов: Reverb, EQ, Compressor, Limiter, Chorus, Phaser, Distortion, Delay, Pitch Shift, Filter, Stereo Enhance, Spectrum Analyzer.

На AudioStreamPlayer задаёте bus = "SFX/Voice", и звук маршрутизируется туда. Удобно глушить SFX отдельно от музыки или применить low-pass к Master при паузе.

# Настройка громкости из настроек игрока (UI-слайдер)
var music_idx = AudioServer.get_bus_index("Music")
AudioServer.set_bus_volume_db(music_idx, linear_to_db(music_volume_0_to_1))

linear_to_db(linear) — встроенная функция конвертации линейной громкости (0..1) в децибелы (-80..0).

2D / 3D Spatial Blend

В отличие от Unity AudioSource (где slider 2D↔3D), в Godot сам выбор узла определяет позиционность:

• AudioStreamPlayer — никогда не позиционный.
• AudioStreamPlayer2D/3D — всегда позиционный.

Если нужен звук, который в начале 3D, потом 2D (например, диктор-нарратор приближается и становится UI) — это два разных узла, переключение в коде.

Listener

В отличие от Unity (где AudioListener — отдельный компонент), в Godot слушатель — это активная Camera3D. По умолчанию. Если нужно сместить слушателя относительно камеры — есть узел AudioListener3D:

Camera3D (current)
└── AudioListener3D (current = true)  ← теперь слушатель здесь

Полезно для third-person: камера далеко, но слушать хочется с уровня головы персонажа.

AudioStreamInteractive — динамическая музыка

Введён в 4.3. Это специальный AudioStream, в котором описаны клипы (части) и переходы между ними с правилами:

• Кросс-фейд через N тактов.
• Match по beat / bar / next-marker.
• Условные переходы (на основе параметра).

Пример: спокойная тема (clip A) переходит в боевую (clip B) через 2 такта при set_clip("Battle"). Это аналог FMOD/Wwise состояний, но встроенно.

AudioStreamPolyphonic — наслаивающиеся звуки

Если играете много коротких звуков (выстрелы, удары) на одном источнике, обычный AudioStreamPlayer прерывает предыдущий. AudioStreamPolyphonic решает это: один плейер, несколько слоёв.

var poly_stream = AudioStreamPolyphonic.new()
poly_stream.polyphony = 8  # до 8 одновременно
$Player.stream = poly_stream

var playback: AudioStreamPlaybackPolyphonic = $Player.get_stream_playback()
playback.play_stream(preload("res://gunshot.ogg"))
playback.play_stream(preload("res://shell_drop.ogg"))

AudioStreamGenerator — процедурное аудио

Если хочется генерировать звук программно (синтезатор, retro-bleeps, реактивная музыка), есть AudioStreamGenerator. Это spezialized AudioStream, в который вы пушите PCM-фреймы из кода.

extends AudioStreamPlayer

@onready var playback: AudioStreamGeneratorPlayback

var phase: float = 0.0
var frequency: float = 440.0  # A4
var sample_rate: float = 44100.0

func _ready() -> void:
    var gen := AudioStreamGenerator.new()
    gen.mix_rate = sample_rate
    gen.buffer_length = 0.1  # 100 мс буфер
    stream = gen
    play()
    playback = get_stream_playback()

func _process(_delta: float) -> void:
    var frames_to_fill := playback.get_frames_available()
    var increment := frequency * TAU / sample_rate
    for i in frames_to_fill:
        var sample := sin(phase) * 0.3
        playback.push_frame(Vector2(sample, sample))  # stereo
        phase += increment
        if phase > TAU:
            phase -= TAU

Это синусоидальный генератор тона. На практике:

• 8-bit chiptune-синтез — square/triangle/noise через простые алгоритмы.
• Реактивная музыка — pitch/timbre, реагирующие на gameplay (низкое здоровье → диссонанс).
• Voice synthesis — формантный синтез для процедурных NPC-голосов.
• Audio-visualizers и spectrum analyzers — обратная задача через AudioEffectSpectrumAnalyzer на bus’е.

Импорт и форматы

Поддерживаются: OGG Vorbis, MP3, WAV. Рекомендации:

• Музыка — OGG (Vorbis) с loop-points. MP3 хуже по точности loop-точек.
• Короткие SFX — WAV (без потерь) или короткие OGG.
• Voice — OGG c bitrate 96–128 kbps.

В Import-доке для каждого аудио настраиваются:

• Loop — зацикливать ли.
• Loop Offset / Length — точки цикла (для seamless music).
• BPM / Beat Count / Bar Beats — для AudioStreamInteractive.

В следующей главе — UI и Control-узлы.