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.

Pentru ZeroDev Sound 3.0.66 min de cititActualizat

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:

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

Apeleaz-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.

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)

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.

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

Adaugă-le când pornește resursa ta și din nou la <res>:ready, în caz că Sound pornește după tine.

Evenimente de server

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

Acestea 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.

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)

Exemple de configurare

Setările sunt în zerodev-sound/config/config.lua, iar fiecare poate fi schimbată în joc în /soundadmin.

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 }

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 în Control sau verifică tu permisiunea înainte să folosești src = 0.
  • Citește GetBass cel 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.

Tradus din engleză. Dacă ceva de aici nu se potrivește cu pagina în engleză, pagina în engleză are dreptate. English