音效

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

使用 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_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/).

• 从 资源目录（Asset Catalog） 拖入声音（编辑器会把它们下载到 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; // 保险：如果忘记，会在 ~60s 后自动停止

    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.volume_perturb = 0.2;

desc := SFX.default_sfx_desc();
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);
    }
}