Reproducir sonidos personalizados en FiveM: audio NUI, volumen por distancia, formatos

Tienes un archivo de sonido, como un timbre, una sirena o una notificación, y quieres reproducirlo desde un script. FiveM no tiene un nativo simple para archivos de audio personalizados, así que la respuesta habitual es NUI: una página web oculta en tu recurso que reproduce el archivo cuando un script de cliente lo solicita. Así es como funcionan los recursos al estilo de interact-sound. A continuación encontrarás el código, el volumen por distancia, los formatos y las otras opciones.

#Cómo funciona

1. El recurso tiene una página HTML (ui_page) con un pequeño script.
2. El script de cliente envía un mensaje a la página con SendNUIMessage.
3. La página crea un objeto Audio con el archivo y lo reproduce.

La página puede permanecer invisible y no necesita foco del ratón.

#El recurso

resources/[mic]/my_sounds/
  fxmanifest.lua
  client.lua
  html/
    index.html
    sounds/
      doorbell.ogg
      alarm.ogg

-- fxmanifest.lua
fx_version 'cerulean'
game 'gta5'

ui_page 'html/index.html'

files {
    'html/index.html',
    'html/sounds/*.ogg',
}

client_script 'client.lua'

Los archivos de sonido deben estar en files, o la página no podrá cargarlos.

#La página HTML

<!DOCTYPE html>
<html>
<body>
<script>
  window.addEventListener('message', (event) => {
    const data = event.data
    if (data.action !== 'play') return

    const audio = new Audio('./sounds/' + data.file + '.ogg')
    audio.volume = Math.min(Math.max(data.volume ?? 1.0, 0), 1)
    audio.play().catch((err) => console.log('sound error', err))
  })
</script>
</body>
</html>

audio.volume va de 0.0 a 1.0. Los valores fuera de ese rango causan un error, así que el código los limita.

#El script de cliente

local function playSound(file, volume)
    SendNUIMessage({
        action = 'play',
        file = file,
        volume = volume or 1.0,
    })
end

RegisterNetEvent('my_sounds:play', function(file, volume)
    playSound(file, volume)
end)

exports('PlaySound', playSound)

Ahora otro script de cliente puede llamar a exports.my_sounds:PlaySound('doorbell', 0.6), y el servidor puede enviar TriggerClientEvent('my_sounds:play', source, 'doorbell', 0.6) a un jugador, o -1 a todos ellos.

Consejo: para un sonido que un jugador debe escuchar todo el tiempo (una notificación, un timbre de teléfono), esto es todo lo que necesitas. Para un sonido que pertenece a un lugar, usa la versión por distancia a continuación.

#Volumen basado en distancia

Para un sonido en un punto, como una alarma en un edificio, el servidor envía las coordenadas y cada cliente decide qué tan fuerte es:

-- client.lua
RegisterNetEvent('my_sounds:playAt', function(file, coords, maxDistance, baseVolume)
    local pos = GetEntityCoords(PlayerPedId())
    local dist = #(pos - vec3(coords.x, coords.y, coords.z))

    if dist >= maxDistance then return end

    local volume = (1.0 - dist / maxDistance) * (baseVolume or 1.0)
    playSound(file, volume)
end)

-- server.lua: everyone gets it, only players in range hear it
TriggerClientEvent('my_sounds:playAt', -1, 'alarm', vec3(120.0, -1300.0, 29.0), 40.0, 1.0)

Esto comprueba la distancia una vez, cuando comienza el sonido. Para un sonido largo donde el jugador se mueve, envía la posición nuevamente a intervalos, o mantén el objeto de audio en la página y actualiza su volumen mientras el cliente envía nuevos valores. Un sonido que debe seguir a un vehículo en movimiento es donde una biblioteca lista para usar ayuda, como en la siguiente sección.

Mantén el servidor en control de quién activa qué. Si permites que los clientes envíen un evento reproducir para todos, cualquier tramposo puede enviar spam de sonidos a todo el servidor. Consulta eventos de servidor y seguridad.

#Formatos de archivo y tamaño

• OGG: la mejor opción predeterminada, pequeña y buena calidad.
• MP3: también funciona bien y es fácil de encontrar.
• WAV: funciona, pero es grande. Úsalo solo para efectos muy cortos.

Cada archivo en files es descargado por cada jugador, así que mantenlo corto, mono para efectos, y comprimido. Corta el silencio al principio del archivo: un retraso que escuchas en el juego a menudo viene de eso. Si el total es grande, se aplica la misma advertencia que para otros activos: consulta activos de gran tamaño.

#xsound y otras bibliotecas

En lugar de escribir la página tú mismo, puedes usar una biblioteca de sonido como xsound. Reproduce audio desde un archivo o una URL en una posición o en una entidad, y puede cambiar el volumen y la posición más adelante, lo que se adapta a la música en un bar o un boombox que sigue a un jugador. Lee su README para sus exportaciones exactas, ya que difieren entre versiones. La idea es la misma: una página NUI oculta reproduce el audio y un script de cliente la controla.

#Sonidos nativos y bancos de audio

Los sonidos propios del juego son otra opción. Se reproducen con nativos como PlaySoundFrontend o PlaySoundFromCoord, con el nombre y conjunto del sonido, y no necesitan archivos de ti. Añadir tus propios sonidos al sistema de audio del juego también es posible, con archivos de banco de audio y líneas data_file para audio, pero es un trabajo especializado con sus propias herramientas y es fácil romperlo. Para la mayoría de servidores, el audio NUI es más simple y suficiente.

#Problemas comunes

• Sin sonido en absoluto. Comprueba el nombre del archivo y que el archivo esté en files. Abre la NUI en las herramientas de desarrollador del juego si las tienes, y lee la consola para un 404.
• El sonido se reproduce solo una vez. Crea un nuevo objeto Audio cada vez, como en el código anterior, o reinicia currentTime en uno mantenido.
• Demasiado fuerte o demasiado silencioso. Mantén el volumen de 0.0 a 1.0, y establécelo bajo por defecto.
• El sonido se corta cuando el recurso se reinicia. La página se recarga con el recurso. Eso es lo esperado.
• Un script que usa interact-sound falla. Los recursos que esperan ese nombre necesitan un recurso con el mismo nombre y exportaciones. Comprueba qué necesita el script antes de renombrar el tuyo.

#Lista de verificación