Documentação do ZeroDev Sound

API para programadores do ZeroDev Sound

O ZeroDev Sound tem uma API aberta para outros resources: ler o que está a tocar, operar um sistema de colunas ou o rádio de um carro para um jogador a partir do seu menu, acompanhar alterações, instalar colunas e baias de instalação próprias e controlar luzes pelo grave real. Tudo aqui vem do ZeroDev Sound 3.0.5. Os ficheiros da API não estão protegidos por escrow, por isso pode ler o contrato por si: server/devapi.lua e client/devapi.lua.

Para o ZeroDev Sound 3.0.66 min de leituraAtualizado a

O ZeroDev Sound verifica cada valor que recebe e continua a funcionar quando o seu resource está ausente, parado ou avariado. O horário de silêncio, o silenciamento pela polícia e o limite de volume do dono aplicam-se a tudo o que toca.

Encontrar 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 colunas 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 ficheiro em web/library) ou request:<n> (um pedido de música adicionado pelo dono).

Exports de servidor

Export Devolve
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 matrícula), 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 comando remoto do próprio Sound: qualquer pessoa no carro opera o rádio dele; um sistema colocado segue o seu dono e a sua definição de grupo ou público, e o jogador tem de estar ao alcance. Passe src = 0 para agir com a autoridade do seu próprio script, depois de o seu script ter 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 colunas do clube tocam a música house quando o DJ entra em serviço.

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)

Colunas fixas e baias de instalação

Um script de loja, clube ou garagem pode colocar colunas próprias e uma baia de instalação no seu edifício. Não têm dono nem item, nunca são guardadas e desaparecem quando o seu resource pára. Os jogadores não as podem mover nem arrumar; a polícia ainda as pode silenciar.

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 arrancar, e de novo em <res>:ready, caso o Sound arranque depois de si.

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, por isso um cliente não os consegue falsificar.

Exports de cliente (só de leitura)

Export Devolve
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 ecrãs de carro

Exemplo: neon no chassis 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 definiçõ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 ficheiros do ZeroDev Sound; use a API. Um ficheiro protegido por escrow alterado impede o resource de carregar.
  • Passe o source real a Control, ou verifique a permissão por si antes de usar src = 0.
  • Leia GetBass no máximo uma vez por frame e durma quando nada estiver a tocar.
  • A API tem versões (audio_extensions 'v1', ApiVersion() 2). Uma alteração 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 colunas de um jogador?

Sim, com Control(src, key, 'play', { text = 'library:1' }). Aplicam-se as mesmas regras do comando remoto do Sound: o jogador tem de poder operar esse sistema e estar ao alcance.

As luzes ou props podem acompanhar a música?

Sim. O export de cliente GetBass(key) devolve o grave da música que está a tocar, a cada frame, de 0 a 1.

Traduzido do inglês. Se alguma coisa aqui não coincidir com a página em inglês, vale a página em inglês. English