Docs van ZeroDev Sound

ZeroDev Sound developer-API

ZeroDev Sound heeft een open API voor andere resources: lees wat er speelt, laat een speakersysteem of autoradio draaien voor een speler vanuit je eigen menu, volg wijzigingen, plaats eigen speakers en inbouwplekken en stuur lichten aan met de echte bas. Alles hier komt uit ZeroDev Sound 3.0.5. De API-bestanden zijn niet escrowed, dus je kunt het contract zelf lezen: server/devapi.lua en client/devapi.lua.

Voor ZeroDev Sound 3.0.66 min leestijdBijgewerkt

ZeroDev Sound controleert elke waarde die het krijgt en blijft werken wanneer je resource ontbreekt, gestopt of kapot is. Stille uren, het zwijgen opleggen door de politie en de volumelimiet van de eigenaar gelden voor alles wat afspeelt.

De resource vinden

De resource draagt de manifestmarkering audio_extensions 'v1'. Zoek hem daarop, niet op zijn mapnaam, want servers kunnen de map hernoemen:

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

Roep het aan met exports[res]:.... Eventnamen beginnen met de resourcenaam: res .. ':session'.

Een sessie is één songstream: een groep gekoppelde speakers in de wereld (kind = 'speakers') of de stereo van één auto (kind = 'car', sleutel car:<plate>). Een song wordt gekozen met een verwijzing: library:<n> (een song in Config.Library), file:<name> (een bestand in web/library) of request:<n> (een songverzoek dat de eigenaar heeft toegevoegd).

Server-exports

Export Geeft terug
GetSessions() elke sessie op de server
GetSession(key) één sessie, of nil
GetCarSession(vehicle) de sessie van een voertuig (entity of kentekentekst), of nil
Targets(src) wat deze speler nu mag bedienen: { key, kind, label, canPlay, why }
Control(src, key, action, data) ok, reason
Ready() true zodra Sound is geladen
ApiVersion() 2

Control voert een actie uit met dezelfde regels als de eigen afstandsbediening van Sound: iedereen in de auto bedient de stereo; een geplaatst systeem volgt zijn eigenaar en zijn instelling voor groep of openbaar, en de speler moet binnen bereik zijn. Geef src = 0 mee om te handelen met de eigen autoriteit van je script, nadat je script heeft bepaald wie dat mag.

Actie Data
play { text = reference } (zonder text: hervatten)
queue { text = reference }
resume, pause, next, previous, stop geen
volume { value = 0.0 - 1.0 }
seek { at = seconds }
mode { value = 'studio' }, of bass, club, vocal, concert, night, chipeo
eq { low, mid, high } in dB, -12 tot 12
repeatMode { value = 'off' }, of one, all

Als ok false is, is reason een van no_session, bad_action, no_player, not_inside, out_of_range, not_allowed, mixer_alone, no_text, catalogue_only of error.

Voorbeeld: de clubspeakers spelen de housesong wanneer de dj inklokt.

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)

Vaste speakers en inbouwplekken

Een winkel-, club- of garagescript kan eigen speakers en een inbouwplek in zijn gebouw zetten. Ze hebben geen eigenaar en geen item, worden nooit opgeslagen en verdwijnen wanneer je resource stopt. Spelers kunnen ze niet verplaatsen of inpakken; de politie kan ze nog wel het zwijgen opleggen.

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

Voeg ze toe wanneer je resource start en nog een keer bij <res>:ready, voor het geval Sound na jou start.

Serverevents

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

Dit zijn server-lokale events, nooit door een client verstuurd, dus een client kan ze niet vervalsen.

Client-exports (alleen lezen)

Export Geeft terug
GetSessions() de sessies die deze client kent: in de buurt en zijn eigen
GetCarSession(vehicle) de sessie van de auto, of nil
GetBass(key) 0.0 tot 1.0: de bas van de echte song in dit frame, 0 bij stilte
CarAudioState(vehicle) de status van de head unit, voor autoschermen

Voorbeeld: underglow die pulseert met de subs van de auto.

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)

Configvoorbeelden

De instellingen staan in zerodev-sound/config/config.lua en elke instelling kan in het spel worden gewijzigd in /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 }

Regels voor integraties

  • Wijzig de bestanden van ZeroDev Sound niet; gebruik de API. Een gewijzigd escrowed bestand voorkomt dat de resource laadt.
  • Geef de echte source mee aan Control, of controleer zelf de permissie voordat je src = 0 gebruikt.
  • Lees GetBass hooguit één keer per frame en laat je script slapen wanneer er niets speelt.
  • De API heeft versies (audio_extensions 'v1', ApiVersion() 2). Een brekende wijziging krijgt een nieuwe versie en een regel in de changelog.

Veelgestelde vragen

Hoe vind ik ZeroDev Sound vanuit mijn script?

Zoek de resource waarvan de manifest audio_extensions 'v1' heeft, zoals in het eerste voorbeeld. De map kan op sommige servers een andere naam hebben.

Kan mijn script muziek afspelen op de speakers van een speler?

Ja, met Control(src, key, 'play', { text = 'library:1' }). Dezelfde regels als bij de eigen afstandsbediening van Sound gelden: de speler moet dat systeem mogen bedienen en binnen bereik zijn.

Kunnen lichten of props de muziek volgen?

Ja. De client-export GetBass(key) geeft elk frame de bas van de song die speelt, van 0 tot 1.

Vertaald uit het Engels. Als iets hier afwijkt van de Engelse pagina, dan heeft de Engelse pagina gelijk. English