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.
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:
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
endRoep 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.
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.
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 mVoeg ze toe wanneer je resource start en nog een keer bij <res>:ready, voor het geval Sound na jou start.
Serverevents
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 loadedDit 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.
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.
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
sourcemee aanControl, of controleer zelf de permissie voordat jesrc = 0gebruikt. - Lees
GetBasshooguit éé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.