Benutzerdefinierte Sounds in FiveM abspielen: NUI Audio, Lautstärke nach Distanz, Formate

Du hast eine Sounddatei, wie z.B. eine Türklingel, eine Sirene oder eine Benachrichtigung, und möchtest sie von einem Script abspielen. FiveM hat keinen einfachen Native für benutzerdefinierte Audiodateien, also ist die übliche Antwort NUI: eine versteckte Webseite in deiner Ressource, die die Datei abspielt, wenn ein Client-Script sie auffordert. So funktionieren Ressourcen im Stil von interact-sound. Unten findest du den Code, die Distanzlautstärke, die Formate und die anderen Optionen.

#Wie es funktioniert

1. Die Ressource hat eine HTML-Seite (ui_page) mit einem kleinen Script.
2. Das Client-Script sendet eine Nachricht an die Seite mit SendNUIMessage.
3. Die Seite erstellt ein Audio Objekt mit der Datei und spielt sie ab.

Die Seite kann unsichtbar bleiben und benötigt keinen Mausfocus.

#Die Ressource

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'

Die Sound-Dateien müssen sich in files befinden, sonst können sie nicht von der Seite geladen werden.

#Die HTML-Seite

<!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 liegt zwischen 0,0 und 1,0. Werte außerhalb dieses Bereichs verursachen einen Fehler, daher begrenzt der Code ihn.

#Das Client-Script

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)

Jetzt kann ein anderes Client-Script exports.my_sounds:PlaySound('doorbell', 0.6) aufrufen, und der Server kann TriggerClientEvent('my_sounds:play', source, 'doorbell', 0.6) an einen Spieler senden, oder -1 für alle.

Tipp: Für einen Sound, den ein Spieler immer hören soll (eine Benachrichtigung, ein Telefon-Klingelton), ist das alles, was du brauchst. Für einen Sound, der zu einem bestimmten Ort gehört, verwende die Distanz-Version unten.

#Distanzbasierte Lautstärke

Für einen Sound an einem bestimmten Punkt, wie z.B. einen Alarm auf einem Gebäude, sendet der Server die Koordinaten, und jeder Client entscheidet, wie laut er ist:

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

Dies überprüft die Entfernung einmal, wenn der Sound startet. Für einen langen Sound, bei dem sich der Spieler bewegt, sende die Position in regelmäßigen Abständen erneut, oder behalte das Audio-Objekt auf der Seite und aktualisiere seine Lautstärke, wenn der Client neue Werte sendet. Ein Sound, der ein bewegendes Fahrzeug folgen muss, ist dort, wo eine vorgefertigte Bibliothek hilft, wie im nächsten Abschnitt.

Behalte die Kontrolle des Servers, wer was auslöst. Wenn du Clients erlaubst, ein „für alle abspielen" Event zu senden, kann jeder Cheater Sounds an den ganzen Server spammen. Siehe Server-Events und Sicherheit.

#Dateiformate und Größe

• OGG: die beste Standardeinstellung, klein und gute Qualität.
• MP3: auch in Ordnung und leicht zu finden.
• WAV: funktioniert, aber ist groß. Verwende es nur für sehr kurze Effekte.

Jede Datei in files wird von jedem Spieler heruntergeladen, also halten sie kurz, Mono für Effekte und komprimiert. Trimme die Stille am Anfang der Datei: eine Verzögerung, die du im Spiel hörst, kommt oft daher. Wenn die Gesamtsumme groß ist, gilt die gleiche Warnung wie für andere Assets: siehe zu große Assets.

#xsound und andere Bibliotheken

Anstatt die Seite selbst zu schreiben, kannst du eine Sound-Bibliothek wie xsound verwenden. Sie spielt Audio aus einer Datei oder einer URL an einer Position oder auf einer Entity ab und kann die Lautstärke und die Position später ändern, was sich für Musik in einer Bar oder einen Boom Box, der einem Spieler folgt, eignet. Lese ihre README für ihre genauen Exports, da diese sich zwischen Versionen unterscheiden. Die Idee ist die gleiche: eine versteckte NUI-Seite spielt das Audio ab, und ein Client-Script steuert es.

#Native Sounds und Audio-Banken

Die eigenen Sounds des Spiels sind eine andere Option. Sie werden mit Natives wie PlaySoundFrontend oder PlaySoundFromCoord abgespielt, mit dem Namen und dem Set des Sounds, und benötigen keine Dateien von dir. Das Hinzufügen deiner eigenen Sounds zum Audio-System des Spiels ist auch möglich, mit Audio-Bank-Dateien und data_file Zeilen für Audio, aber es ist eine Spezialaufgabe mit seinen eigenen Werkzeugen und es ist leicht, es zu brechen. Für die meisten Server ist NUI-Audio einfacher und ausreichend.

#Häufige Probleme

• Kein Sound überhaupt. Überprüfe den Dateinamen und dass die Datei in files ist. Öffne die NUI in den Entwicklertools des Spiels, wenn du sie hast, und lese die Konsole auf einen 404.
• Sound wird nur einmal abgespielt. Erstelle jedes Mal ein neues Audio Objekt, wie im obigen Code, oder setze currentTime auf einem behaltenen zurück.
• Zu laut oder zu leise. Halten Sie die Lautstärke zwischen 0,0 und 1,0 und stellen Sie sie standardmäßig niedrig ein.
• Der Sound wird unterbrochen, wenn die Ressource neu startet. Die Seite wird mit der Ressource neu geladen. Das ist zu erwarten.
• Ein Script, das interact-sound verwendet, schlägt fehl. Ressourcen, die diesen Namen erwarten, benötigen eine Ressource mit dem gleichen Namen und Exports. Überprüfe, was das Script will, bevor du das deine umbenennen.

#Checkliste