音效

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

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

当前仅支持 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_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 仅对你在客户端本地启动的声音有效。

变化（推荐用于频繁触发的音效）

如果你频繁播放相同的声音（脚步、拾取），添加细微变化：

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