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.
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:
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
endWywoł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ę.
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ć.
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 mDodawaj je, gdy twój resource startuje, i ponownie przy <res>:ready, na wypadek gdyby Sound wystartował po tobie.
Eventy serwerowe
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 loadedTo 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.
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.
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
sourcedoControlalbo sam sprawdź uprawnienie, zanim użyjeszsrc = 0. - Czytaj
GetBassnajwyż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.