Sonido y háptica

Reproduce efectos de sonido y retroalimentación háptica local.

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

Actualmente solo codificados en PCM .wav se admiten archivos. Si tienes un .wav que no se importe/reproduzca, 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 {
    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;
}

Obtener un SFX_Asset

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

• Arrastra sonidos desde el Catálogo de recursos (el editor los descarga en res/)
• O añade tu propio .wav archivo en res/ desde tu máquina local

Luego refiérelos por ruta:

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

Comprueba las rutas de los activos durante el desarrollo. Un activo faltante produce un identificador nulo; SFX.play registra una advertencia y devuelve 0.

Algunos activos integrados de la plataforma usan $AO/... rutas. Por ejemplo: get_asset(SFX_Asset, "$AO/sfx/FUI Hologram Ping Tone Echoed.wav").

Sonidos posicionales (algo 3D)

De forma predeterminada, 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 a 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: trátalo como música/ambiental en lugar de SFX

    // Devuelve un ID que se puede usar para actualizar o detener el sonido.
    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).

Sonidos dirigidos a un jugador

Establece specific_to_player cuando el servidor deba seguir el sonido, pero solo un cliente deba oírlo realmente:

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

Reproducción en 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: se detiene automáticamente después de ~60 s si se te olvida

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

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

Variación (recomendada para SFX repetitivos)

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.

Predicción y direccionamiento

Llama a los sonidos de jugabilidad desde la misma ruta predicha compartida que el evento que los causó. El sistema de sonido reconcilia el sonido predicho de un cliente con el resultado del servidor, así que no envuelvas SFX.play en Game.is_server() o 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);
}

Para un sonido que solo un jugador debe oír, establece desc.specific_to_player. Esto mantiene el evento en el código de jugabilidad compartido mientras dirige la reproducción al cliente de ese jugador.

Hápticos

Haptics.play_impact activa la respuesta háptica de impacto en el dispositivo local. Llámala solo para el jugador local:

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

        Haptics.play_impact(.MEDIUM);
    }
}

Elige .LIGHT, .MEDIUM, o .HEAVY. Los hápticos actualmente funcionan en iOS. Las llamadas en Android, web, Windows y servidores no hacen nada.

Los hápticos no se sincronizan, no se dirigen ni se deduplican. Actívalos en el punto de interacción local, en lugar de hacerlo desde código de jugabilidad a nivel de escena.