Sound Effects

Play one-shot and positional sound effects (and simple looping audio).

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

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

Make sure the path is valid. If you call get_asset with a bad path and then play it, you can crash.

Some built-in platform assets are referenced via $AO/... paths. For example: get_asset(SFX_Asset, "$AO/click.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 on clients (see server note below)
    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).

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

SFX.play returns 0 on the server (and in headless), so SFX.stop only works for sounds you started locally on the client.

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.

Server vs client (networking + prediction)

SFX can be played from either side, depending on intent:

• Authoritative gameplay events (everyone should hear it): play on the server

• Local/UI feedback (only the local player): play on the client

Example: authoritative positional 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);
    }
}