Документація ZeroDev Sound

API для розробників ZeroDev Sound

ZeroDev Sound має відкритий API для інших ресурсів: дізнаватися, що грає, керувати системою колонок або автомагнітолою гравця зі свого меню, стежити за змінами, розміщувати власні колонки та бокси встановлення й керувати світлом за реальним басом. Усе тут узято з ZeroDev Sound 3.0.5. Файли API не захищені escrow, тож ви можете самі прочитати контракт: server/devapi.lua і client/devapi.lua.

Для ZeroDev Sound 3.0.66 хв читанняОновлено

ZeroDev Sound перевіряє кожне передане значення й продовжує працювати, якщо ваш ресурс відсутній, зупинений або зламаний. Тихі години, глушіння поліцією та обмеження гучності власника діють на все, що відтворюється.

Пошук ресурсу

У маніфесті ресурсу є маркер audio_extensions 'v1'. Шукайте його за цим маркером, а не за назвою папки, бо сервери можуть перейменовувати папку:

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

Викликайте його через 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.

Приклад: клубні колонки грають хаус, коли діджей відмічається на зміні.

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)

Стаціонарні колонки та бокси встановлення

Скрипт магазину, клубу чи гаража може поставити у своїй будівлі власні колонки та бокс встановлення. У них немає власника й предмета, вони ніколи не зберігаються й зникають, коли зупиняється ваш ресурс. Гравці не можуть їх рухати чи прибирати; поліція й надалі може їх заглушити.

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

Додавайте їх під час запуску вашого ресурсу й ще раз за <res>:ready, на випадок якщо Sound запуститься після вас.

Серверні події

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

Це серверні локальні події, які ніколи не надсилаються з клієнта, тому клієнт не може їх підробити.

Клієнтські exports (лише читання)

Export Повертає
GetSessions() сесії, які знає цей клієнт: найближчі та власна
GetCarSession(vehicle) сесія авто або nil
GetBass(key) від 0.0 до 1.0: бас справжньої пісні в цьому кадрі, 0 за тиші
CarAudioState(vehicle) стан головного пристрою, для екранів авто

Приклад: підсвітка днища, що пульсує в такт сабвуферам авто.

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)

Приклади конфігурації

Налаштування розташовані в zerodev-sound/config/config.lua, і кожне з них можна змінити в грі в /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 }

Правила для інтеграцій

  • Не змінюйте файли 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.

Перекладено з англійської. Якщо щось тут розходиться з англійською сторінкою, правильною є англійська сторінка. English