Dokumentacja ZeroDev Sound

API dla deweloperów ZeroDev Sound

ZeroDev Sound ma otwarte API dla innych resource'ów: odczytaj, co jest odtwarzane, obsługuj system głośników lub radio samochodowe gracza z własnego menu, śledź zmiany, ustawiaj własne głośniki i warsztaty montażu i steruj światłami na podstawie prawdziwego basu. Wszystko tutaj pochodzi z ZeroDev Sound 3.0.5. Pliki API nie są objęte escrow, więc możesz sam przeczytać kontrakt: server/devapi.lua i client/devapi.lua.

Dla ZeroDev Sound 3.0.66 min czytaniaAktualizacja

ZeroDev Sound sprawdza każdą otrzymaną wartość i działa dalej, gdy twojego resource brakuje, jest zatrzymany lub uszkodzony. Godziny ciszy, wyciszanie przez policję i limit głośności właściciela obowiązują dla wszystkiego, co jest odtwarzane.

Znalezienie resource

Resource ma w manifeście znacznik audio_extensions 'v1'. Szukaj go po nim, a nie po nazwie folderu, bo serwery mogą zmienić nazwę folderu:

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

Wywołuj go przez exports[res]:.... Nazwy eventów zaczynają się od nazwy resource: res .. ':session'.

Sesja to jeden strumień utworu: grupa połączonych głośników w świecie (kind = 'speakers') albo radio jednego auta (kind = 'car', klucz car:<plate>). Utwór wybiera się przez referencję: library:<n> (utwór w Config.Library), file:<name> (plik w web/library) albo request:<n> (prośba o utwór dodana przez właściciela).

Eksporty serwerowe

Eksport Zwraca
GetSessions() każdą sesję na serwerze
GetSession(key) jedną sesję albo nil
GetCarSession(vehicle) sesję pojazdu (entity lub tekst tablicy) albo nil
Targets(src) co ten gracz może teraz uruchomić: { key, kind, label, canPlay, why }
Control(src, key, action, data) ok, reason
Ready() true, gdy Sound się załadował
ApiVersion() 2

Control wykonuje akcję według tych samych zasad co własny pilot Sound: każdy w aucie obsługuje jego radio; ustawiony system podlega właścicielowi i ustawieniu grupowemu lub publicznemu, a gracz musi być w zasięgu. Przekaż src = 0, aby działać z uprawnieniami własnego skryptu, po tym jak twój skrypt zdecyduje, kto może.

Akcja Dane
play { text = reference } (bez text: wznów)
queue { text = reference }
resume, pause, next, previous, stop brak
volume { value = 0.0 - 1.0 }
seek { at = seconds }
mode { value = 'studio' } albo bass, club, vocal, concert, night, chipeo
eq { low, mid, high } w dB, od -12 do 12
repeatMode { value = 'off' } albo one, all

Gdy ok ma wartość false, reason to jedno z no_session, bad_action, no_player, not_inside, out_of_range, not_allowed, mixer_alone, no_text, catalogue_only lub error.

Przykład: głośniki klubu puszczają domyślny utwór klubu, gdy DJ zaczyna służbę.

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)

Stałe głośniki i warsztaty montażu

Skrypt sklepu, klubu lub garażu może ustawić w swoim budynku własne głośniki i warsztat montażu. Nie mają właściciela ani przedmiotu, nigdy nie są zapisywane i znikają, gdy twój resource się zatrzyma. Gracze nie mogą ich przesuwać ani pakować; policja nadal może je wyciszyć.

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

Dodawaj je, gdy twój resource startuje, i ponownie przy <res>:ready, na wypadek gdyby Sound wystartował po tobie.

Eventy serwerowe

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

To eventy lokalne dla serwera, nigdy nie wysyłane od klienta, więc klient nie może ich sfałszować.

Eksporty klienckie (tylko do odczytu)

Eksport Zwraca
GetSessions() sesje, które zna ten klient: pobliskie i własna
GetCarSession(vehicle) sesja auta albo nil
GetBass(key) od 0.0 do 1.0: bas prawdziwego utworu w tej klatce, 0 przy ciszy
CarAudioState(vehicle) stan radia samochodowego, dla ekranów aut

Przykład: podświetlenie podwozia pulsujące razem z subami 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)

Przykłady configu

Ustawienia są w zerodev-sound/config/config.lua i każde można zmienić w grze w /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 }

Zasady dla integracji

  • Nie zmieniaj plików ZeroDev Sound; używaj API. Zmieniony plik objęty escrow powoduje, że resource się nie załaduje.
  • Przekaż prawdziwy source do Control albo sam sprawdź uprawnienie, zanim użyjesz src = 0.
  • Czytaj GetBass najwyżej raz na klatkę i usypiaj pętlę, gdy nic nie gra.
  • API ma wersje (audio_extensions 'v1', ApiVersion() 2). Zmiana łamiąca zgodność dostaje nową wersję i wpis w changelogu.

Najczęściej zadawane pytania

Jak znaleźć ZeroDev Sound ze swojego skryptu?

Szukaj resource, którego manifest ma audio_extensions 'v1', jak w pierwszym przykładzie. Folder może mieć inną nazwę na niektórych serwerach.

Czy mój skrypt może puszczać muzykę na głośnikach gracza?

Tak, przez Control(src, key, 'play', { text = 'library:1' }). Obowiązują te same zasady co przy własnym pilocie Sound: gracz musi mieć prawo obsługiwać ten system i być w zasięgu.

Czy światła lub propy mogą podążać za muzyką?

Tak. Eksport kliencki GetBass(key) podaje bas odtwarzanego utworu w każdej klatce, od 0 do 1.

Przetłumaczone z angielskiego. Jeśli coś tutaj różni się od strony angielskiej, rację ma strona angielska. English