Riproduci suoni personalizzati in FiveM: audio NUI, volume per distanza, formati

Hai un file audio, come un campanello, una sirena o una notifica, e vuoi riprodurlo da uno script. FiveM non ha un semplice nativo per file audio personalizzati, quindi la soluzione solita è NUI: una pagina web nascosta nella tua risorsa che riproduce il file quando uno script client lo chiede. Ecco come funzionano risorse nello stile di interact-sound. Sotto troverai il codice, il volume per distanza, i formati e le altre opzioni.

#Come funziona

1. La risorsa ha una pagina HTML (ui_page) con un piccolo script.
2. Lo script client invia un messaggio alla pagina con SendNUIMessage.
3. La pagina crea un oggetto Audio con il file e lo riproduce.

La pagina può rimanere invisibile e non ha bisogno di focus del mouse.

#La risorsa

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'

I file audio devono essere in files, altrimenti la pagina non può caricarli.

#La pagina 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 da 0.0 a 1.0. Valori al di fuori di questo intervallo causano un errore, quindi il codice li limita.

#Lo script client

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)

Ora un altro script client può chiamare exports.my_sounds:PlaySound('doorbell', 0.6), e il server può inviare TriggerClientEvent('my_sounds:play', source, 'doorbell', 0.6) a un giocatore, o -1 per tutti loro.

Suggerimento: per un suono che un giocatore dovrebbe sentire tutto il tempo (una notifica, una suoneria del telefono), questo è tutto quello che ti serve. Per un suono che appartiene a un posto, usa la versione per distanza qui sotto.

#Volume basato sulla distanza

Per un suono in un punto, come un allarme su un edificio, il server invia le coordinate e ogni client decide quanto sia forte:

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

Questo controlla la distanza una volta, quando il suono inizia. Per un suono lungo dove il giocatore si muove, invia la posizione di nuovo a intervalli, o tieni l'oggetto audio nella pagina e aggiorna il suo volume mentre il client invia nuovi valori. Un suono che deve seguire un veicolo in movimento è dove una libreria già pronta aiuta, come nella prossima sezione.

Tieni il server in controllo di chi attiva cosa. Se lasci ai client inviare un evento play per tutti, qualsiasi cheater può spammare suoni all'intero server. Vedi eventi server e sicurezza.

#Formati di file e dimensione

• OGG: il miglior default, piccoli e di buona qualità.
• MP3: anche bene, e facile da trovare.
• WAV: funziona, ma è grande. Usalo solo per effetti molto brevi.

Ogni file in files è scaricato da ogni giocatore, quindi mantienilo breve, mono per gli effetti, e compresso. Togli il silenzio all'inizio del file: un ritardo che senti in gioco spesso viene da quello. Se il totale è grande, lo stesso avvertimento si applica come per altri asset: vedi asset sovradimensionati.

#xsound e altre librerie

Invece di scrivere la pagina tu stesso, puoi usare una libreria audio come xsound. Riproduce audio da un file o un URL a una posizione o su un'entità, e può cambiare il volume e la posizione dopo, che si adatta alla musica in un bar o un boombox che segue un giocatore. Leggi il suo README per i suoi esatti export, poiché differiscono tra le versioni. L'idea è la stessa: una pagina NUI nascosta riproduce l'audio, e uno script client la controlla.

#Suoni nativi e audio bank

I suoni stessi del gioco sono un'altra opzione. Vengono riprodotti con nativi come PlaySoundFrontend o PlaySoundFromCoord, con il nome e il set del suono, e non hanno bisogno di file da te. Aggiungere i tuoi suoni al sistema audio del gioco è anche possibile, con file audio bank e linee data_file per l'audio, ma è un lavoro specialistico con i suoi propri strumenti ed è facile rompere. Per la maggior parte dei server, l'audio NUI è più semplice e sufficiente.

#Problemi comuni

• Nessun suono affatto. Controlla il nome del file e che il file sia in files. Apri l'NUI negli strumenti di sviluppo del gioco se li hai, e leggi la console per un 404.
• Il suono si riproduce solo una volta. Crea un nuovo oggetto Audio ogni volta, come nel codice sopra, o reimposta currentTime su uno mantenuto.
• Troppo forte o troppo debole. Mantieni il volume da 0.0 a 1.0, e impostalo basso per default.
• Il suono viene tagliato quando la risorsa riavvia. La pagina è ricaricata con la risorsa. Questo è previsto.
• Uno script che usa interact-sound fallisce. Risorse che si aspettano quel nome hanno bisogno di una risorsa con lo stesso nome ed export. Controlla cosa lo script vuole prima di rinominare il tuo.

#Checklist