Sound and Haptics

Play sound effects and local impact feedback.

Use the SFX API to play short sound effects (UI clicks, footsteps, impacts) and simple looping audio (ambient loops, music).

Currently only PCM-encoded .wav files are supported. If you have a .wav that won’t import/play, convert it to PCM using Audacity (or a similar tool).

Quick start (play a sound)

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

desc := SFX.default_sfx_desc();
SFX.play(click, desc);

SFX API reference

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

Getting an SFX_Asset

Sound effects live in your game’s res folder (often under res/sfx/).

• Drag sounds in from the Asset Catalog (editor downloads them into res/)
• Or add your own .wav file into res/ from your local machine

Then reference them by path:

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

Check asset paths during development. A missing asset produces a null handle; SFX.play logs a warning and returns 0.

Some built-in platform assets use $AO/... paths. For example: get_asset(SFX_Asset, "$AO/sfx/FUI Hologram Ping Tone Echoed.wav").

Positional (3D-ish) sounds

By default, SFX plays as a non-positional “2D” sound. To make it positional, set a position:

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

Following an entity (moving sound source)

If a sound should move with an entity (engine hum, buzzing projectile, etc), set 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; // optional: treat as music/ambient instead of SFX

    // Returns an ID that can be used to update or stop the sound.
    return SFX.play(engine, desc);
}

If entity_to_follow is set, you usually don’t need to also call set_position (it’s fine if you do).

Player-targeted sounds

Set specific_to_player when the server should track the sound but only one client should actually hear it:

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

Looping + stopping

SFX.play returns an ID you can stop later:

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; // safety: auto-stop after ~60s if you forget

    sound_id = SFX.play(loop, desc);
}

stop_loop :: proc() {
    if sound_id != 0 {
        SFX.stop(sound_id);
        sound_id = 0;
    }
}

Variation (recommended for spammy SFX)

If you play the same sound frequently (footsteps, pickups), add subtle variation:

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

Keep volume_perturb / speed_perturb subtle. Values above ~0.3 usually sound wrong.

Prediction and targeting

Call gameplay sounds from the same shared predicted path as the event that caused them. The sound system reconciles a client's predicted sound with the server result, so do not wrap SFX.play in Game.is_server() or 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);
}

For a sound that only one player should hear, set desc.specific_to_player. This keeps the event in shared gameplay code while targeting playback to that player's client.

Haptics

Haptics.play_impact triggers impact feedback on the local device. Call it only for the local player:

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

        Haptics.play_impact(.MEDIUM);
    }
}

Choose .LIGHT, .MEDIUM, or .HEAVY. Haptics currently work on iOS. Calls on Android, web, Windows, and servers do nothing.

Haptics are not synchronized, targeted, or deduplicated. Trigger them at the local interaction point rather than from scene-wide gameplay code.