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.

Para o ZeroDev Sound 3.0.66 min de leituraAtualizado em

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:

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

Chame-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.

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)

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.

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

Adicione-as quando o seu resource iniciar, e de novo em <res>:ready, caso o Sound inicie depois de você.

Eventos de servidor

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

Sã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.

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)

Exemplos de configuração

As configurações ficam em zerodev-sound/config/config.lua, e cada uma pode ser alterada no jogo em /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 }

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 source real para Control, ou verifique a permissão por conta própria antes de usar src = 0.
  • Leia GetBass no 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.

Traduzido do inglês. Se algo aqui divergir da página em inglês, vale a página em inglês. English