Efectos de sonido

Reproduce efectos de sonido de un solo uso y posicionales (y audio en bucle simple).

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

Actualmente solo codificados en PCM .wav se admiten archivos. 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 de SFX

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

Obtener un SFX_Asset

Los efectos de sonido viven en la carpeta res de tu juego (a menudo dentro de 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 provocar un fallo.

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 de 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 llamar también a set_position (no pasa nada 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: detener automáticamente después de ~60 s 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 que se repiten mucho)

Si reproduces el mismo sonido con frecuencia (pasos, recogidas), añade una 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 normalmente suenan mal.

Servidor vs cliente (red + predicción)

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

• Eventos de juego autoritativos (todos deberían escucharlo): reproducir en el servidor

• Retroalimentación local/de interfaz (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);
    }
}