Dokumentace ZeroDev Sound

API pro vývojáře ZeroDev Sound

ZeroDev Sound má otevřené API pro další resources: čtěte, co hraje, ovládejte reproduktorový systém nebo autorádio hráče z vlastního menu, sledujte změny, umisťujte vlastní reproduktory a montážní dílny a řiďte světla podle skutečných basů. Vše zde pochází z ZeroDev Sound 3.0.5. Soubory API nejsou chráněné escrow, takže kontrakt si můžete přečíst sami: server/devapi.lua a client/devapi.lua.

Pro ZeroDev Sound 3.0.66 min čteníAktualizováno

ZeroDev Sound kontroluje každou hodnotu, kterou dostane, a funguje dál, když váš resource chybí, je zastavený nebo rozbitý. Doba klidu, ztlumení policií a strop hlasitosti nastavený majitelem platí pro vše, co hraje.

Nalezení resource

Resource nese v manifestu značku audio_extensions 'v1'. Hledejte ho podle ní, ne podle názvu složky, protože servery mohou složku přejmenovat:

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

Volejte ho přes exports[res]:.... Názvy eventů začínají názvem resource: res .. ':session'.

Session je jeden proud skladby: skupina propojených reproduktorů ve světě (kind = 'speakers') nebo autorádio jednoho auta (kind = 'car', klíč car:<plate>). Skladba se vybírá referencí: library:<n> (skladba v Config.Library), file:<name> (soubor ve web/library) nebo request:<n> (žádost o skladbu, kterou přidal majitel).

Serverové exporty

Export Vrací
GetSessions() každou session na serveru
GetSession(key) jednu session, nebo nil
GetCarSession(vehicle) session vozidla (entity nebo text SPZ), nebo nil
Targets(src) co může tento hráč právě teď ovládat: { key, kind, label, canPlay, why }
Control(src, key, action, data) ok, reason
Ready() true, jakmile se Sound načetl
ApiVersion() 2

Control provede akci podle stejných pravidel jako vlastní dálkový ovladač Soundu: kdokoli v autě ovládá jeho rádio; umístěný systém se řídí svým majitelem a nastavením pro skupinu nebo veřejnost a hráč musí být v dosahu. Předejte src = 0, abyste jednali s oprávněním vlastního scriptu, až váš script rozhodne, kdo smí.

Akce Data
play { text = reference } (bez text: pokračovat)
queue { text = reference }
resume, pause, next, previous, stop žádná
volume { value = 0.0 - 1.0 }
seek { at = seconds }
mode { value = 'studio' } nebo bass, club, vocal, concert, night, chipeo
eq { low, mid, high } v dB, od -12 do 12
repeatMode { value = 'off' } nebo one, all

Když je ok false, reason je jedno z no_session, bad_action, no_player, not_inside, out_of_range, not_allowed, mixer_alone, no_text, catalogue_only nebo error.

Příklad: klubové reproduktory přehrají výchozí skladbu klubu, když DJ nastoupí do služby.

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)

Pevné reproduktory a montážní dílny

Script obchodu, klubu nebo garáže může ve své budově umístit vlastní reproduktory a montážní dílnu. Nemají majitele ani předmět, nikdy se neukládají a zmizí, když se váš resource zastaví. Hráči je nemohou přesouvat ani sbalit; policie je stále může ztlumit.

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

Přidejte je při startu svého resource a znovu při <res>:ready, pro případ, že Sound nastartuje po vás.

Serverové eventy

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

Jsou to eventy lokální pro server, nikdy se neposílají od klienta, takže je klient nemůže padělat.

Klientské exporty (jen pro čtení)

Export Vrací
GetSessions() session, které tento klient zná: ty v okolí a jeho vlastní
GetCarSession(vehicle) session auta, nebo nil
GetBass(key) 0.0 až 1.0: bas skutečné skladby v tomto snímku, 0 při tichu
CarAudioState(vehicle) stav head unitu, pro displeje aut

Příklad: podsvícení podvozku, které pulzuje se suby auta.

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)

Příklady configu

Nastavení jsou v zerodev-sound/config/config.lua a každé lze změnit ve hře v /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 }

Pravidla pro integrace

  • Neměňte soubory ZeroDev Sound; používejte API. Změněný soubor chráněný escrow zabrání načtení resource.
  • Předejte skutečný source do Control, nebo si oprávnění zkontrolujte sami, než použijete src = 0.
  • Čtěte GetBass nejvýše jednou za snímek a když nic nehraje, nechte smyčku spát.
  • API je verzované (audio_extensions 'v1', ApiVersion() 2). Změna, která porušuje kompatibilitu, dostane novou verzi a řádek v changelogu.

Časté dotazy

Jak najdu ZeroDev Sound ze svého scriptu?

Hledejte resource, jehož manifest má audio_extensions 'v1', jako v prvním příkladu. Složka může mít na některých serverech jiný název.

Může můj script přehrávat hudbu na reproduktorech hráče?

Ano, přes Control(src, key, 'play', { text = 'library:1' }). Platí stejná pravidla jako u vlastního ovladače Soundu: hráč musí smět ten systém ovládat a být v dosahu.

Mohou světla nebo propy sledovat hudbu?

Ano. Klientský export GetBass(key) vrací bas hrající skladby v každém snímku, od 0 do 1.

Přeloženo z angličtiny. Pokud se zde něco liší od anglické stránky, platí anglická stránka. English