Documentação do ZeroDev Sound
API para desenvolvedores do ZeroDev Sound
O ZeroDev Sound tem uma API aberta para outros resources: ler o que está tocando, operar um sistema de caixas de som ou o rádio de um carro para um jogador a partir do seu menu, acompanhar mudanças, instalar caixas de som e baias de instalação próprias e controlar luzes pelo grave real. Tudo aqui vem do ZeroDev Sound 3.0.5. Os arquivos da API não são protegidos por escrow, então você mesmo pode ler o contrato: server/devapi.lua e client/devapi.lua.
O ZeroDev Sound verifica cada valor recebido e continua funcionando quando o seu resource está ausente, parado ou quebrado. Horário de silêncio, silenciamento pela polícia e o limite de volume do dono valem para tudo o que toca.
Encontrando o resource
O resource traz a marca de manifest audio_extensions 'v1'. Encontre-o por ela, não pelo nome da pasta, porque os servidores podem renomear a pasta:
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
endChame-o com exports[res]:.... Os nomes de evento começam com o nome do resource: res .. ':session'.
Uma sessão é um fluxo de uma música: um grupo de caixas de som ligadas no mundo (kind = 'speakers') ou o rádio de um carro (kind = 'car', chave car:<plate>). Uma música é escolhida por uma referência: library:<n> (uma música em Config.Library), file:<name> (um arquivo em web/library) ou request:<n> (um pedido de música adicionado pelo dono).
Exports de servidor
| Export | Retorna |
|---|---|
GetSessions() |
todas as sessões do servidor |
GetSession(key) |
uma sessão, ou nil |
GetCarSession(vehicle) |
a sessão de um veículo (entidade ou texto da placa), ou nil |
Targets(src) |
o que este jogador pode operar agora: { key, kind, label, canPlay, why } |
Control(src, key, action, data) |
ok, reason |
Ready() |
true quando o Sound carregou |
ApiVersion() |
2 |
Control executa uma ação com as mesmas regras do controle remoto do próprio Sound: qualquer pessoa no carro opera o rádio dele; um sistema colocado segue o seu dono e a sua configuração de grupo ou público, e o jogador precisa estar ao alcance. Passe src = 0 para agir com a autoridade do seu próprio script, depois que o seu script tiver decidido quem pode.
| Ação | Dados |
|---|---|
play |
{ text = reference } (sem text: retomar) |
queue |
{ text = reference } |
resume, pause, next, previous, stop |
nenhum |
volume |
{ value = 0.0 - 1.0 } |
seek |
{ at = seconds } |
mode |
{ value = 'studio' }, ou bass, club, vocal, concert, night, chipeo |
eq |
{ low, mid, high } em dB, de -12 a 12 |
repeatMode |
{ value = 'off' }, ou one, all |
Quando ok é false, reason é um destes: no_session, bad_action, no_player, not_inside, out_of_range, not_allowed, mixer_alone, no_text, catalogue_only ou error.
Exemplo: as caixas de som do clube tocam a música house quando o DJ bate o ponto.
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)Caixas de som fixas e baias de instalação
Um script de loja, clube ou garagem pode colocar caixas de som próprias e uma baia de instalação no seu prédio. Elas não têm dono nem item, nunca são salvas e somem quando o seu resource para. Os jogadores não podem movê-las nem guardá-las; a polícia ainda pode silenciá-las.
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 mAdicione-as quando o seu resource iniciar, e de novo em <res>:ready, caso o Sound inicie depois de você.
Eventos de servidor
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 loadedSão eventos locais do servidor, nunca enviados por um cliente, então um cliente não consegue falsificá-los.
Exports de cliente (somente leitura)
| Export | Retorna |
|---|---|
GetSessions() |
as sessões que este cliente conhece: as próximas e a própria |
GetCarSession(vehicle) |
a sessão do carro, ou nil |
GetBass(key) |
0.0 a 1.0: o grave da música real neste frame, 0 quando está em silêncio |
CarAudioState(vehicle) |
o estado do rádio, para telas de carro |
Exemplo: neon no chassi que pulsa com os subs do carro.
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)Exemplos de configuração
As configurações ficam em zerodev-sound/config/config.lua, e cada uma pode ser alterada no jogo em /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 }Regras para integrações
- Não altere os arquivos do ZeroDev Sound; use a API. Um arquivo protegido por escrow alterado impede o resource de carregar.
- Passe o
sourcereal paraControl, ou verifique a permissão por conta própria antes de usarsrc = 0. - Leia
GetBassno máximo uma vez por frame e durma quando nada estiver tocando. - A API é versionada (
audio_extensions 'v1',ApiVersion()2). Uma mudança incompatível recebe uma nova versão e uma linha no changelog.
Perguntas frequentes
Como encontro o ZeroDev Sound a partir do meu script?
Procure o resource cujo manifest tem audio_extensions 'v1', como no primeiro exemplo. A pasta pode ter outro nome em alguns servidores.
O meu script pode tocar música nas caixas de som de um jogador?
Sim, com Control(src, key, 'play', { text = 'library:1' }). Valem as mesmas regras do controle remoto do Sound: o jogador precisa poder operar aquele sistema e estar ao alcance.
Luzes ou props podem acompanhar a música?
Sim. O export de cliente GetBass(key) retorna o grave da música que está tocando, a cada frame, de 0 a 1.