声音与触觉反馈

播放音效和本地冲击反馈。

使用 SFX API 播放短音效（UI 点击、脚步声、撞击声）和简单的循环音频（环境循环、音乐）。

目前仅支持 PCM 编码的 .wav 文件。如果你有一个 .wav 无法导入/播放的文件，请使用 Audacity（或类似工具）将其转换为 PCM。

快速开始（播放声音）

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

开发期间请检查资源路径。缺失的资源会产生空句柄； 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.play_impact 会在本地设备上触发撞击反馈。仅为本地玩家调用它：

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

        Haptics.play_impact(.MEDIUM);
    }
}

选择 .LIGHT, .MEDIUM或 .HEAVY. 触觉反馈目前在 iOS 上可用。在 Android、Web、Windows 和服务器上的调用都不会执行任何操作。

触觉反馈不会同步、不会定向，也不会去重。请在本地交互点触发它们，而不是从全场景的游戏玩法代码中触发。