Documentazione di ZeroDev Sound
API per sviluppatori di ZeroDev Sound
ZeroDev Sound ha un'API aperta per le altre resource: leggere cosa sta suonando, gestire un impianto di casse o un'autoradio per un giocatore dal tuo menu, seguire i cambiamenti, installare casse e baie di installazione tue e comandare le luci con i veri bassi. Tutto ciò che c'è qui è preso da ZeroDev Sound 3.0.5. I file dell'API non sono in escrow, quindi puoi leggere il contratto da solo: server/devapi.lua e client/devapi.lua.
ZeroDev Sound controlla ogni valore che riceve e continua a funzionare quando la tua resource manca, è ferma o è rotta. Orari di silenzio, silenziamento della polizia e limite di volume del proprietario valgono per tutto ciò che viene riprodotto.
Trovare la resource
La resource porta il marcatore di manifest audio_extensions 'v1'. Trovala da quello, non dal nome della cartella, perché i server possono rinominare la cartella:
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
endChiamala con exports[res]:.... I nomi degli eventi iniziano con il nome della resource: res .. ':session'.
Una sessione è un flusso di una canzone: un gruppo di casse collegate nel mondo (kind = 'speakers') o l'autoradio di una singola auto (kind = 'car', chiave car:<plate>). Una canzone si sceglie con un riferimento: library:<n> (una canzone in Config.Library), file:<name> (un file in web/library) o request:<n> (una richiesta di canzone aggiunta dal proprietario).
Export server
| Export | Restituisce |
|---|---|
GetSessions() |
ogni sessione sul server |
GetSession(key) |
una sessione, o nil |
GetCarSession(vehicle) |
la sessione di un veicolo (entità o testo della targa), o nil |
Targets(src) |
ciò che questo giocatore può gestire adesso: { key, kind, label, canPlay, why } |
Control(src, key, action, data) |
ok, reason |
Ready() |
true quando Sound è stato caricato |
ApiVersion() |
2 |
Control esegue un'azione con le stesse regole del telecomando di Sound: chiunque sia nell'auto ne gestisce l'autoradio; un impianto posato segue il suo proprietario e la sua impostazione di gruppo o pubblico, e il giocatore deve essere a portata. Passa src = 0 per agire con l'autorità del tuo script, dopo che il tuo script ha deciso chi può.
| Azione | Dati |
|---|---|
play |
{ text = reference } (senza text: riprendi) |
queue |
{ text = reference } |
resume, pause, next, previous, stop |
nessuno |
volume |
{ value = 0.0 - 1.0 } |
seek |
{ at = seconds } |
mode |
{ value = 'studio' }, oppure bass, club, vocal, concert, night, chipeo |
eq |
{ low, mid, high } in dB, da -12 a 12 |
repeatMode |
{ value = 'off' }, oppure one, all |
Quando ok è false, reason è uno tra no_session, bad_action, no_player, not_inside, out_of_range, not_allowed, mixer_alone, no_text, catalogue_only o error.
Esempio: le casse del club suonano la canzone house quando il DJ timbra l'ingresso.
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)Casse fisse e baie di installazione
Uno script di negozio, club o garage può mettere casse e una baia di installazione proprie nel suo edificio. Non hanno proprietario né oggetto, non vengono mai salvate e spariscono quando la tua resource si ferma. I giocatori non possono spostarle né imballarle; la polizia può comunque silenziarle.
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 mAggiungile all'avvio della tua resource e di nuovo su <res>:ready, nel caso Sound parta dopo di te.
Eventi 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 loadedSono eventi locali al server, mai inviati da un client, quindi un client non può falsificarli.
Export client (sola lettura)
| Export | Restituisce |
|---|---|
GetSessions() |
le sessioni che questo client conosce: vicine e la propria |
GetCarSession(vehicle) |
la sessione dell'auto, o nil |
GetBass(key) |
da 0.0 a 1.0: i bassi della canzone reale in questo frame, 0 quando è silenzio |
CarAudioState(vehicle) |
lo stato dell'autoradio, per gli schermi auto |
Esempio: underglow che pulsa con i sub dell'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)Esempi di configurazione
Le impostazioni sono in zerodev-sound/config/config.lua e ognuna si può cambiare in gioco 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 }Regole per le integrazioni
- Non modificare i file di ZeroDev Sound; usa l'API. Un file in escrow modificato impedisce il caricamento della resource.
- Passa il vero
sourceaControl, oppure controlla tu i permessi prima di usaresrc = 0. - Leggi
GetBassal massimo una volta per frame e dormi quando non suona nulla. - L'API è versionata (
audio_extensions 'v1',ApiVersion()2). Una modifica incompatibile riceve una nuova versione e una riga nel changelog.
Domande frequenti
Come trovo ZeroDev Sound dal mio script?
Cerca la resource il cui manifest ha audio_extensions 'v1', come nel primo esempio. La cartella può avere un altro nome su alcuni server.
Il mio script può riprodurre musica sulle casse di un giocatore?
Sì, con Control(src, key, 'play', { text = 'library:1' }). Valgono le stesse regole del telecomando di Sound: il giocatore deve poter gestire quell'impianto ed essere a portata.
Luci o prop possono seguire la musica?
Sì. L'export client GetBass(key) restituisce i bassi della canzone in riproduzione, a ogni frame, da 0 a 1.