Документация 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> (песня, которую добавил владелец по запросу).
Серверные экспорты
| Экспорт | Возвращает |
|---|---|
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Это серверные локальные события, которые никогда не отправляются с клиента, поэтому клиент не может их подделать.
Клиентские экспорты (только чтение)
| Экспорт | Возвращает |
|---|---|
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: игрок должен иметь право запускать эту систему и находиться в пределах досягаемости.
Могут ли свет или объекты следовать за музыкой?
Да. Клиентский экспорт GetBass(key) каждый кадр возвращает бас воспроизводимой песни от 0 до 1.