Efectos de Sonido

Reproduce efectos de sonido puntuales y posicionales (y audio simple en bucle).

Usa la API SFX para reproducir efectos de sonido cortos (clics de la interfaz, pasos, impactos) y audio simple en bucle (bucles ambientales, música).

Actualmente solo codificado en PCM .wav archivos son compatibles. Si tienes un .wav que no se importa/reproduce, conviértelo a PCM usando Audacity (o una herramienta similar).

Inicio rápido (reproducir un sonido)

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

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

Referencia de la API SFX

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

Obteniendo un SFX_Asset

Los efectos de sonido viven en el res de tu juego (a menudo bajo res/sfx/).

• Arrastra sonidos desde el Catálogo de activos (el editor los descarga en res/)

• O añade tu propio .wav archivo en res/ desde tu máquina local

Luego refiérete a ellos por ruta:

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

Asegúrate de que la ruta sea válida. Si llamas a get_asset con una ruta incorrecta y luego lo reproduces, puedes causar un bloqueo.

Algunos activos integrados de la plataforma se referencian mediante $AO/... rutas. Por ejemplo: get_asset(SFX_Asset, "$AO/click.wav").

Sonidos posicionales (tipo 3D)

Por defecto, SFX se reproduce como un sonido “2D” no posicional. Para hacerlo posicional, establece una posición:

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

Seguir una entidad (fuente de sonido en movimiento)

Si un sonido debe moverse con una entidad (zumbido del motor, proyectil zumbante, etc.), establece 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; // opcional: tratar como música/ambiental en lugar de SFX

    // Devuelve un ID en los clientes (ver nota del servidor abajo)
    return SFX.play(engine, desc);
}

Si entity_to_follow está establecido, normalmente no necesitas también llamar a set_position (está bien si lo haces).

Bucle + detención

SFX.play devuelve un ID que puedes detener más tarde:

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; // seguridad: detención automática después de ~60s si lo olvidas

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

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

SFX.play devuelve 0 en el servidor (y en modo sin interfaz), así que SFX.stop solo funciona para sonidos que iniciaste localmente en el cliente.

Variación (recomendado para SFX repetitivos)

Si reproduces el mismo sonido con frecuencia (pasos, recogidas), añade variación sutil:

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

Mantén volume_perturb / speed_perturb sutiles. Valores por encima de ~0.3 por lo general suenan mal.

Servidor vs cliente (red + predicción)

SFX puede reproducirse desde cualquiera de los dos lados, dependiendo de la intención:

• Eventos de juego autoritativos (todo el mundo debería escucharlo): reproducir en el servidor

• Retroalimentación local/GUI (solo el jugador local): reproducir en el cliente

Ejemplo: SFX posicional autoritativo:

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