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.

Per ZeroDev Sound 3.0.66 min di letturaAggiornato il

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:

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

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

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)

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.

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

Aggiungile all'avvio della tua resource e di nuovo su <res>:ready, nel caso Sound parta dopo di te.

Eventi 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

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

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)

Esempi di configurazione

Le impostazioni sono in zerodev-sound/config/config.lua e ognuna si può cambiare in gioco 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 }

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 source a Control, oppure controlla tu i permessi prima di usare src = 0.
  • Leggi GetBass al 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.

Tradotto dall'inglese. Se qualcosa qui non corrisponde alla pagina in inglese, vale la pagina in inglese. English