Documentația ZeroDev Sound
API pentru dezvoltatori ZeroDev Sound
ZeroDev Sound are un API deschis pentru alte resurse: citești ce se redă, pornești un sistem de boxe sau un player auto pentru un jucător din propriul meniu, urmărești schimbările, plasezi boxe și ateliere de instalare proprii și comanzi lumini după basul real. Tot ce este aici provine din ZeroDev Sound 3.0.5. Fișierele API nu sunt protejate cu escrow, așa că poți citi contractul chiar tu: server/devapi.lua și client/devapi.lua.
ZeroDev Sound verifică fiecare valoare primită și continuă să funcționeze când resursa ta lipsește, este oprită sau defectă. Orele de liniște, reducerea la tăcere de către poliție și plafonul de volum al proprietarului se aplică la tot ce se redă.
Găsirea resursei
Resursa poartă marcajul de manifest audio_extensions 'v1'. Găsește-o după el, nu după numele folderului, pentru că serverele pot redenumi folderul:
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
endApeleaz-o cu exports[res]:.... Numele evenimentelor încep cu numele resursei: res .. ':session'.
sesiune este un flux de melodie: un grup de boxe legate din lume (kind = 'speakers') sau playerul auto al unei mașini (kind = 'car', cheia car:<plate>). O melodie este aleasă printr-o referință: library:<n> (o melodie din
Config.Library), file:<name> (un fișier din web/library) sau request:<n> (o cerere de melodie adăugată de proprietar).
Exporturi de server
| Export | Returnează |
|---|---|
GetSessions() |
toate sesiunile de pe server |
GetSession(key) |
o sesiune sau nil |
GetCarSession(vehicle) |
sesiunea unui vehicul (entitate sau text de număr de înmatriculare) sau nil |
Targets(src) |
ce poate porni acest jucător chiar acum: { key, kind, label, canPlay, why } |
Control(src, key, action, data) |
ok, reason |
Ready() |
true după ce Sound s-a încărcat |
ApiVersion() |
2 |
Control rulează o acțiune cu aceleași reguli ca telecomanda proprie a lui Sound: oricine din mașină își comandă player-ul; un sistem plasat urmează proprietarul și setarea lui de petrecere sau public, iar jucătorul trebuie să fie în rază. Transmite src = 0
pentru a acționa cu autoritatea proprie a scriptului tău, după ce scriptul tău a decis cine are voie.
| Acțiune | Date |
|---|---|
play |
{ text = reference } (fără text: reia) |
queue |
{ text = reference } |
resume, pause, next, previous, stop |
nimic |
volume |
{ value = 0.0 - 1.0 } |
seek |
{ at = seconds } |
mode |
{ value = 'studio' } sau bass, club, vocal, concert, night, chipeo |
eq |
{ low, mid, high } în dB, de la -12 la 12 |
repeatMode |
{ value = 'off' } sau one, all |
Când ok este false, reason este unul dintre no_session, bad_action, no_player, not_inside, out_of_range,
not_allowed, mixer_alone, no_text, catalogue_only sau error.
Exemplu: boxele clubului redau melodia house când DJ-ul își începe tura.
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)Boxe fixe și ateliere de instalare
Un script de magazin, club sau garaj își poate pune propriile boxe și un atelier de instalare în clădire. Nu au proprietar sau item, nu sunt salvate niciodată și dispar când resursa ta se oprește. Jucătorii nu le pot muta sau strânge; poliția le poate totuși reduce la tăcere.
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 mAdaugă-le când pornește resursa ta și din nou la <res>:ready, în caz că Sound pornește după tine.
Evenimente de server
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 loadedAcestea sunt evenimente locale de server, niciodată trimise de la un client, deci un client nu le poate falsifica.
Exporturi de client (doar citire)
| Export | Returnează |
|---|---|
GetSessions() |
sesiunile pe care le cunoaște acest client: cele din apropiere și a lui |
GetCarSession(vehicle) |
sesiunea mașinii sau nil |
GetBass(key) |
de la 0.0 la 1.0: basul melodiei reale în acest cadru, 0 când este liniște |
CarAudioState(vehicle) |
starea player-ului auto, pentru ecranele mașinii |
Exemplu: iluminare sub caroserie care pulsează odată cu subwoofer-ele mașinii.
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)Exemple de configurare
Setările sunt în zerodev-sound/config/config.lua, iar fiecare poate fi schimbată în joc în /soundadmin.
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 }Reguli pentru integrări
- Nu modifica fișierele ZeroDev Sound; folosește API-ul. Un fișier modificat protejat cu escrow oprește încărcarea resursei.
- Transmite adevăratul
sourceînControlsau verifică tu permisiunea înainte să foloseștisrc = 0. - Citește
GetBasscel mult o dată pe cadru și dormi când nu se redă nimic. - API-ul are versiuni (
audio_extensions 'v1',ApiVersion()2). O schimbare care strică compatibilitatea primește o versiune nouă și o linie în changelog.
Întrebări frecvente
Cum găsesc ZeroDev Sound din scriptul meu?
Caută resursa al cărei manifest are audio_extensions 'v1', ca în primul exemplu. Folderul poate avea alt nume pe unele servere.
Poate scriptul meu să redea muzică pe boxele unui jucător?
Da, cu Control(src, key, 'play', { text = 'library:1' }). Se aplică aceleași reguli ca la telecomanda proprie a lui Sound: jucătorul trebuie să aibă voie să pornească acel sistem și să fie în rază.
Pot luminile sau obiectele să urmeze muzica?
Da. Exportul de client GetBass(key) dă basul melodiei care se redă, la fiecare cadru, de la 0 la 1.