ZeroDev Sound Doku

ZeroDev-Sound-Developer-API

ZeroDev Sound hat eine offene API für andere Resources: lesen, was gerade spielt, aus deinem eigenen Menü ein Lautsprechersystem oder eine Auto-Stereoanlage für einen Spieler steuern, Änderungen verfolgen, eigene Lautsprecher und Einbauhallen platzieren und Lichter vom echten Bass steuern. Alles hier stammt aus ZeroDev Sound 3.0.5. Die API-Dateien sind nicht per Escrow geschützt, daher kannst du den Vertrag selbst lesen: server/devapi.lua und client/devapi.lua.

Für ZeroDev Sound 3.0.66 Min. LesezeitAktualisiert am

ZeroDev Sound prüft jeden Wert, den es bekommt, und läuft weiter, wenn deine Resource fehlt, gestoppt oder defekt ist. Ruhezeiten, Stummschaltung durch die Polizei und die Lautstärkegrenze des Besitzers gelten für alles, was abgespielt wird.

Die Resource finden

Die Resource trägt die Manifest-Markierung audio_extensions 'v1'. Finde sie daran, nicht am Ordnernamen, denn Server können den Ordner umbenennen:

Lua
local function soundResource()
    for i = 0, GetNumResources() - 1 do
        local res = GetResourceByFindIndex(i)
        if res and GetResourceState(res) == 'started' and GetResourceMetadata(res, 'audio_extensions', 0) == 'v1' then return res end
    end
end

Rufe sie mit exports[res]:... auf. Event-Namen beginnen mit dem Resource-Namen: res .. ':session'.

Eine Session ist ein Song-Stream: eine Gruppe verbundener Lautsprecher in der Welt (kind = 'speakers') oder die Stereoanlage eines Autos (kind = 'car', Schlüssel car:<plate>). Ein Song wird über eine Referenz gewählt: library:<n> (ein Song in Config.Library), file:<name> (eine Datei in web/library) oder request:<n> (ein Songwunsch, den der Besitzer hinzugefügt hat).

Server-Exports

Export Rückgabe
GetSessions() jede Session auf dem Server
GetSession(key) eine Session, oder nil
GetCarSession(vehicle) die Session eines Fahrzeugs (Entity oder Kennzeichen-Text), oder nil
Targets(src) was dieser Spieler gerade steuern darf: { key, kind, label, canPlay, why }
Control(src, key, action, data) ok, reason
Ready() true, sobald Sound geladen ist
ApiVersion() 2

Control führt eine Aktion mit denselben Regeln wie die eigene Fernbedienung von Sound aus: Jeder im Auto steuert dessen Stereoanlage; ein aufgestelltes System folgt seinem Besitzer und seiner Party- oder Öffentlich-Einstellung, und der Spieler muss in Reichweite sein. Übergib src = 0, um mit der Autorität deines eigenen Scripts zu handeln, nachdem dein Script entschieden hat, wer darf.

Aktion Daten
play { text = reference } (ohne text: fortsetzen)
queue { text = reference }
resume, pause, next, previous, stop keine
volume { value = 0.0 - 1.0 }
seek { at = seconds }
mode { value = 'studio' } oder bass, club, vocal, concert, night, chipeo
eq { low, mid, high } in dB, -12 bis 12
repeatMode { value = 'off' } oder one, all

Wenn ok false ist, ist reason eines von no_session, bad_action, no_player, not_inside, out_of_range, not_allowed, mixer_alone, no_text, catalogue_only oder error.

Beispiel: Die Club-Lautsprecher spielen den House-Song, wenn sich der DJ einstempelt.

Lua
RegisterNetEvent('myclub:clockIn', function()
    local src = source
    for _, t in ipairs(exports[res]:Targets(src)) do
        if t.kind == 'speakers' then
            exports[res]:Control(src, t.key, 'play', { text = 'library:3' })
            exports[res]:Control(src, t.key, 'mode', { value = 'club' })
        end
    end
end)

Feste Lautsprecher und Einbauhallen

Ein Shop-, Club- oder Garagen-Script kann eigene Lautsprecher und eine Einbauhalle in sein Gebäude setzen. Sie haben keinen Besitzer und kein Item, werden nie gespeichert und verschwinden, wenn deine Resource stoppt. Spieler können sie weder verschieben noch einpacken; die Polizei kann sie weiterhin stummschalten.

Lua
local id, key = exports[res]:AddFixedSpeaker({
    id = 'radio_1',              -- yours to name; adding the same id again moves it
    item = 'zds_room_ceiling',   -- any placed Sound speaker item
    coords = vector3(x, y, z), heading = 90.0,
    pitch = -90.0,               -- on a ceiling, grille down; 0 on a floor or wall
    label = 'Store radio',
    group = 'store',             -- same group = one system
})
exports[res]:RemoveFixedSpeaker('radio_1')
exports[res]:GetFixedSpeakers()  -- { { id, speaker, key } } of your resource

exports[res]:AddBay({ id = 'garage', label = 'Garage audio bay', coords = vector3(x, y, z), radius = 6.0, blip = true })
exports[res]:RemoveBay('garage') -- up to 8 bays per resource, radius 3 to 15 m

Füge sie hinzu, wenn deine Resource startet, und noch einmal bei <res>:ready, falls Sound nach dir startet.

Server-Events

Lua
AddEventHandler(res .. ':session', function(key, session) end)   -- any change: song, pause, volume, mode, queue
AddEventHandler(res .. ':songStarted', function(session) end)    -- a different song started
AddEventHandler(res .. ':sessionRemoved', function(key) end)     -- speakers packed up, a car session ended
AddEventHandler(res .. ':ready', function() end)                 -- Sound started and loaded

Das sind serverlokale Events, die nie von einem Client gesendet werden, daher kann ein Client sie nicht fälschen.

Client-Exports (nur lesend)

Export Rückgabe
GetSessions() die Sessions, die dieser Client kennt: in der Nähe und seine eigene
GetCarSession(vehicle) die Session des Autos, oder nil
GetBass(key) 0.0 bis 1.0: der Bass des echten Songs in diesem Frame, 0 bei Stille
CarAudioState(vehicle) der Zustand des Autoradios, für Auto-Displays

Beispiel: Unterboden-Beleuchtung, die mit den Subwoofern des Autos pulsiert.

Lua
CreateThread(function()
    while true do
        local veh = GetVehiclePedIsIn(PlayerPedId(), false)
        local s = veh ~= 0 and exports[res]:GetCarSession(veh)
        if s and s.title and not s.paused then
            SetVehicleNeonLightsColour(veh, 255, math.floor(40 + 200 * exports[res]:GetBass(s.key)), 255)
            Wait(0)
        else
            Wait(500)
        end
    end
end)

Config-Beispiele

Die Einstellungen liegen in zerodev-sound/config/config.lua, und jede lässt sich im Spiel unter /soundadmin ändern.

Lua
Config.Framework = 'auto'        -- or 'esx', 'qb', 'qbox', 'standalone'
Config.Inventory = 'auto'        -- or 'ox', 'qb', 'qs', 'codem', 'core', 'origen', 'tgiann', 'esx', 'none'
Config.MaxPlacedPerPlayer = 8
Config.QuietHours = { enabled = true, from = 23, to = 7, maxVolume = 0.35 }

Regeln für Integrationen

  • Ändere keine Dateien von ZeroDev Sound; nutze die API. Eine geänderte Escrow-Datei verhindert, dass die Resource lädt.
  • Übergib den echten source an Control oder prüfe die Berechtigung selbst, bevor du src = 0 nutzt.
  • Lies GetBass höchstens einmal pro Frame und pausiere, wenn nichts spielt.
  • Die API ist versioniert (audio_extensions 'v1', ApiVersion() 2). Eine inkompatible Änderung bekommt eine neue Version und eine Zeile im Changelog.

Häufig gestellte Fragen

Wie finde ich ZeroDev Sound aus meinem Script?

Suche die Resource, deren Manifest audio_extensions 'v1' enthält, wie im ersten Beispiel. Der Ordner kann auf manchen Servern anders heißen.

Kann mein Script Musik auf den Lautsprechern eines Spielers abspielen?

Ja, mit Control(src, key, 'play', { text = 'library:1' }). Es gelten dieselben Regeln wie bei der eigenen Fernbedienung von Sound: Der Spieler muss dieses System steuern dürfen und in Reichweite sein.

Können Lichter oder Props der Musik folgen?

Ja. Der Client-Export GetBass(key) liefert in jedem Frame den Bass des laufenden Songs, von 0 bis 1.

Aus dem Englischen übersetzt. Wenn etwas hier von der englischen Seite abweicht, gilt die englische Seite. English