Документация 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> (песня, которую добавил владелец по запросу).

Серверные экспорты

Экспорт Возвращает
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

Это серверные локальные события, которые никогда не отправляются с клиента, поэтому клиент не может их подделать.

Клиентские экспорты (только чтение)

Экспорт Возвращает
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: игрок должен иметь право запускать эту систему и находиться в пределах досягаемости.

Могут ли свет или объекты следовать за музыкой?

Да. Клиентский экспорт GetBass(key) каждый кадр возвращает бас воспроизводимой песни от 0 до 1.

Переведено с английского. Если что-то здесь расходится с английской страницей, верна английская страница. English