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.
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:
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
endRufe 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.
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.
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 mFüge sie hinzu, wenn deine Resource startet, und noch einmal bei <res>:ready, falls Sound nach dir startet.
Server-Events
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 loadedDas 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.
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.
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
sourceanControloder prüfe die Berechtigung selbst, bevor dusrc = 0nutzt. - Lies
GetBasshö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.