Звуковые эффекты

Воспроизводите одноразовые и позиционные звуковые эффекты (а также простое зацикленное аудио).

Используйте SFX API для воспроизведения коротких звуковых эффектов (клики UI, шаги, удары) и простого зацикленного аудио (фоновые петли, музыка).

В настоящее время только PCM-кодированные .wav файлы поддерживаются. Если у вас есть .wav который не импортируется/не воспроизводится, конвертируйте его в PCM с помощью Audacity (или аналогичного инструмента).

Быстрый старт (воспроизведение звука)

click := get_asset(SFX_Asset, "sfx/click.wav");

desc := SFX.default_sfx_desc();
SFX.play(click, desc);

Справочник по SFX API

SFX_Asset :: class : Asset {}

SFX_Channel :: enum {
    SFX;
    MUSIC;
}

SFX_Desc :: struct {
    positional:       bool;
    position:         v2 #read_only;
    delay:            float;
    volume:           float;
    speed:            float;
    volume_perturb:   float;
    speed_perturb:    float;
    range_multiplier: float;
    loop_timeout:     float;
    entity_to_follow: u64;
    loop:             bool;
    channel:          SFX_Channel;

    set_position :: method(p: v2);
}

SFX :: struct {
    play            :: proc(asset: SFX_Asset, desc: SFX_Desc) -> u64;
    stop            :: proc(id: u64);
    default_sfx_desc :: proc() -> SFX_Desc;
}

Получение SFX_Asset

Звуковые эффекты находятся в папке res вашей игры (часто в res/sfx/).

• Перетаскивайте звуки из Каталог ресурсов (редактор загружает их в res/)

• Или добавьте свой собственный .wav файл в res/ с вашего локального компьютера

Затем обращайтесь к ним по пути:

pickup := get_asset(SFX_Asset, "sfx/pickup.wav");

Убедитесь, что путь корректен. Если вы вызовете get_asset с неверным путём и затем воспроизведёте его, приложение может аварийно завершиться.

К некоторым встроенным платформенным ресурсам обращаются через $AO/... пути. Например: get_asset(SFX_Asset, "$AO/click.wav").

Позиционные звуки (примерно 3D)

По умолчанию SFX воспроизводится как непозиционный звук “2D”. Чтобы сделать его позиционным, задайте позицию:

play_hit_sfx :: proc(world_pos: v2) {
    hit := get_asset(SFX_Asset, "sfx/hit.wav");

    desc := SFX.default_sfx_desc();
    desc->set_position(world_pos);
    desc.range_multiplier = 1.5;

    SFX.play(hit, desc);
}

Отслеживание сущности (движущийся источник звука)

Если звук должен двигаться вместе с сущностью (гул двигателя, жужжащий снаряд и т. д.), задайте entity_to_follow:

start_engine_loop :: proc(entity: Entity) -> u64 {
    engine := get_asset(SFX_Asset, "sfx/engine_loop.wav");

    desc := SFX.default_sfx_desc();
    desc.entity_to_follow = entity.id;
    desc.loop = true;
    desc.channel = .MUSIC; // необязательно: обрабатывать как музыку/фон, а не как SFX

    // Возвращает ID на клиентах (см. примечание о сервере ниже)
    return SFX.play(engine, desc);
}

Если entity_to_follow установлено, обычно не нужно также вызывать set_position (это нормально, если вы всё же это делаете).

Зацикливание + остановка

SFX.play возвращает ID, который можно остановить позже:

sound_id := 0.(u64);

start_loop :: proc() {
    loop := get_asset(SFX_Asset, "sfx/ambience.wav");

    desc := SFX.default_sfx_desc();
    desc.loop = true;
    desc.volume = 0.6;
    desc.loop_timeout = 60; // защита: автоостановка примерно через 60 с, если вы забудете

    sound_id = SFX.play(loop, desc);
}

stop_loop :: proc() {
    if sound_id != 0 {
        SFX.stop(sound_id);
        sound_id = 0;
    }
}

SFX.play возвращает 0 на сервере (и в headless), поэтому SFX.stop работает только для звуков, которые вы запустили локально на клиенте.

Вариативность (рекомендуется для часто повторяющихся SFX)

Если вы часто воспроизводите один и тот же звук (шаги, подбираемые предметы), добавьте небольшую вариативность:

desc := SFX.default_sfx_desc();
desc.volume_perturb = 0.2;
desc.speed_perturb  = 0.15;
SFX.play(get_asset(SFX_Asset, "sfx/footstep.wav"), desc);

Держите volume_perturb / speed_perturb в пределах небольшой величины. Значения выше ~0.3 обычно звучат неправильно.

Сервер vs клиент (сеть + предсказание)

SFX можно воспроизводить с любой стороны, в зависимости от цели:

• Авторитетные игровые события (это должны услышать все): воспроизводите на сервере

• Локальная/интерфейсная обратная связь (только локальный игрок): воспроизводите на клиенте

Пример: авторитетный позиционный SFX:

play_round_victory :: proc(pos: v2) {
    if Game.is_server() {
        desc := SFX.default_sfx_desc();
        desc->set_position(pos);
        SFX.play(get_asset(SFX_Asset, "sfx/round_victory.wav"), desc);
    }
}