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

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

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

В настоящее время только 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_Desc_Flags :: enum {
    POSITIONAL :: 1 << 0;
}

SFX_Channel :: enum {
    SFX;
    MUSIC;
}

SFX_Desc :: struct {
    flags:            SFX_Desc_Flags;
    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 на сервере (и в безголовом режиме), поэтому 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 обычно звучат неправильно.

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

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);
    }
}