Документація ZeroDev Sound
API для розробників ZeroDev Sound
ZeroDev Sound має відкритий API для інших ресурсів: дізнаватися, що грає, керувати системою колонок або автомагнітолою гравця зі свого меню, стежити за змінами, розміщувати власні колонки та бокси встановлення й керувати світлом за реальним басом. Усе тут узято з ZeroDev Sound 3.0.5. Файли API не захищені escrow, тож ви можете самі прочитати контракт: server/devapi.lua і client/devapi.lua.
ZeroDev Sound перевіряє кожне передане значення й продовжує працювати, якщо ваш ресурс відсутній, зупинений або зламаний. Тихі години, глушіння поліцією та обмеження гучності власника діють на все, що відтворюється.
Пошук ресурсу
У маніфесті ресурсу є маркер audio_extensions 'v1'. Шукайте його за цим маркером, а не за назвою папки, бо сервери можуть перейменовувати папку:
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Викликайте його через exports[res]:.... Назви подій починаються з назви ресурсу: res .. ':session'.
Сесія — це один потік пісні: група пов'язаних колонок у світі (kind = 'speakers') або автомагнітола одного авто (kind = 'car', ключ car:<plate>). Пісню вибирають за посиланням: library:<n> (пісня з Config.Library), file:<name> (файл у web/library) або request:<n> (пісня, яку додав власник за запитом).
Серверні exports
| Export | Повертає |
|---|---|
GetSessions() |
усі сесії на сервері |
GetSession(key) |
одну сесію або nil |
GetCarSession(vehicle) |
сесію транспортного засобу (сутність або текст номерного знака) або nil |
Targets(src) |
що цей гравець може запустити просто зараз: { key, kind, label, canPlay, why } |
Control(src, key, action, data) |
ok, reason |
Ready() |
true, коли Sound завантажився |
ApiVersion() |
2 |
Control виконує дію за тими самими правилами, що й власний пульт Sound: будь-хто в авто керує його магнітолою; встановлена система слідує за своїм власником і налаштуванням «для компанії» або «для всіх», і гравець має перебувати в межах досяжності. Передайте src = 0, щоб діяти з правами вашого скрипта, після того як ваш скрипт вирішив, кому це дозволено.
| Дія | Дані |
|---|---|
play |
{ text = reference } (без text: продовжити) |
queue |
{ text = reference } |
resume, pause, next, previous, stop |
немає |
volume |
{ value = 0.0 - 1.0 } |
seek |
{ at = seconds } |
mode |
{ value = 'studio' } або bass, club, vocal, concert, night, chipeo |
eq |
{ low, mid, high } у дБ, від -12 до 12 |
repeatMode |
{ value = 'off' } або one, all |
Якщо ok дорівнює false, reason набуває одного зі значень no_session, bad_action, no_player, not_inside, out_of_range, not_allowed, mixer_alone, no_text, catalogue_only або error.
Приклад: клубні колонки грають хаус, коли діджей відмічається на зміні.
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)Стаціонарні колонки та бокси встановлення
Скрипт магазину, клубу чи гаража може поставити у своїй будівлі власні колонки та бокс встановлення. У них немає власника й предмета, вони ніколи не зберігаються й зникають, коли зупиняється ваш ресурс. Гравці не можуть їх рухати чи прибирати; поліція й надалі може їх заглушити.
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Додавайте їх під час запуску вашого ресурсу й ще раз за <res>:ready, на випадок якщо Sound запуститься після вас.
Серверні події
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Це серверні локальні події, які ніколи не надсилаються з клієнта, тому клієнт не може їх підробити.
Клієнтські exports (лише читання)
| Export | Повертає |
|---|---|
GetSessions() |
сесії, які знає цей клієнт: найближчі та власна |
GetCarSession(vehicle) |
сесія авто або nil |
GetBass(key) |
від 0.0 до 1.0: бас справжньої пісні в цьому кадрі, 0 за тиші |
CarAudioState(vehicle) |
стан головного пристрою, для екранів авто |
Приклад: підсвітка днища, що пульсує в такт сабвуферам авто.
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)Приклади конфігурації
Налаштування розташовані в zerodev-sound/config/config.lua, і кожне з них можна змінити в грі в /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 }Правила для інтеграцій
- Не змінюйте файли ZeroDev Sound; використовуйте API. Змінений файл під escrow не дасть ресурсу завантажитися.
- Передавайте справжній
sourceдоControlабо перевіряйте дозвіл самі, перш ніж використовуватиsrc = 0. - Читайте
GetBassне частіше ніж раз на кадр і засинайте, коли нічого не грає. - API має версії (
audio_extensions 'v1',ApiVersion()2). Критична зміна отримує нову версію та запис у списку змін.
Поширені запитання
Як знайти ZeroDev Sound зі свого скрипта?
Шукайте ресурс, у маніфесті якого є audio_extensions 'v1', як у першому прикладі. На деяких серверах папка може мати іншу назву.
Чи може мій скрипт відтворювати музику на колонках гравця?
Так, через Control(src, key, 'play', { text = 'library:1' }). Діють ті самі правила, що й для власного пульта Sound: гравець має мати право запускати цю систему й перебувати в межах досяжності.
Чи можуть світло або об'єкти слідувати за музикою?
Так. Клієнтський export GetBass(key) щокадру повертає бас пісні, що грає, від 0 до 1.