Звук и тактильная отдача

Воспроизводите звуковые эффекты и локальную тактильную обратную связь.

Используйте 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_Channel :: enum {
    SFX;
    MUSIC;
}

SFX_Desc :: struct {
    specific_to_player: Player;
    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);
    fade_out_and_stop :: proc(id: u64, fade_time: float);
    default_sfx_desc :: proc() -> SFX_Desc;
}

Получение SFX_Asset

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

• Перетащите звуки из Каталог ресурсов (редактор загружает их в res/)
• Или добавьте свой собственный .wav файл в res/ с локального компьютера

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

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

Проверяйте пути к ассетам во время разработки. Отсутствующий ассет приводит к null-объекту; SFX.play выводит предупреждение и возвращает 0.

Некоторые встроенные платформенные ассеты используют пути $AO/... Например: get_asset(SFX_Asset, "$AO/sfx/FUI Hologram Ping Tone Echoed.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 (хотя это допустимо).

Звуки, привязанные к игроку

Установите specific_to_player если сервер должен отслеживать звук, но услышать его должен только один клиент:

play_private_ping :: proc(player: Player) {
    click := get_asset(SFX_Asset, "sfx/click.wav");

    desc := SFX.default_sfx_desc();
    desc.specific_to_player = player;
    desc.volume = 0.7;

    SFX.play(click, desc);
}

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

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)

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

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.play в Game.is_server() или player.is_local().

play_round_victory :: proc(position: v2) {
    desc := SFX.default_sfx_desc();
    desc.set_position(position);
    SFX.play(get_asset(SFX_Asset, "sfx/round_victory.wav"), desc);
}

Для звука, который должен услышать только один игрок, установите desc.specific_to_player. Это сохраняет событие в общем игровом коде, но направляет воспроизведение клиенту этого игрока.

Haptics

Haptics.play_impact вызывает тактильную отдачу на локальном устройстве. Вызывайте это только для локального игрока:

My_Player :: class : Player_Base {
    play_local_impact :: method() {
        if !is_local() return;

        Haptics.play_impact(.MEDIUM);
    }
}

Выберите .LIGHT, .MEDIUM, или .HEAVY. Haptics currently work on iOS. Calls on Android, web, Windows, and servers do nothing.

Haptics не синхронизируются, не таргетируются и не дедуплицируются. Вызывайте их в точке локального взаимодействия, а не из игрового кода, охватывающего всю сцену.