音效

播放一次性和位置音效（以及简单的循环音频）。

使用 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 {
    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 服务器 上返回 （以及在无头模式下），因此 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 可以从任一端播放：

• 权威性游戏事件 （所有人都应该听到）：在 上返回

• 本地/UI 反馈 （仅本地玩家）：在 客户端

示例：权威性的定向 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);
    }
}