ZeroDev Sound 文档

ZeroDev Sound 开发者 API

ZeroDev Sound 为其他资源提供开放的 API:读取正在播放的内容,从你自己的菜单为玩家操作音箱系统或车载音响,跟踪变化,放置你自己的音箱和改装间,并用真实的低音驱动灯光。这里的所有内容都取自 ZeroDev Sound 3.0.5。API 文件没有加密(escrow),你可以自己阅读接口约定:server/devapi.lua 和 client/devapi.lua。

适用于 ZeroDev Sound 3.0.6阅读约 6 分钟更新于

ZeroDev Sound 会检查收到的每一个值,即使你的资源缺失、已停止或出错,它也会继续运行。安静时段、警察静音和所有者设定的音量上限,对所有正在播放的内容都生效。

找到资源

资源的 manifest 中带有标记 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'。

一个 session 是一路歌曲流:世界中相互关联的一组音箱(kind = 'speakers'),或一辆车的音响(kind = 'car',键为 car:<plate>)。歌曲通过 reference 选择:library:<n>(Config.Library 中的一首歌)、file:<name>(web/library 中的一个文件)或 request:<n>(所有者添加的点歌)。

服务端导出函数

导出函数 返回值
GetSessions() 服务器上的所有 session
GetSession(key) 一个 session,或 nil
GetCarSession(vehicle) 某辆车的 session(实体或车牌文本),或 nil
Targets(src) 该玩家现在可以操作的内容:{ key, kind, label, canPlay, why }
Control(src, key, action, data) ok, reason
Ready() Sound 加载完成后为 true
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 },单位 dB,-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。

示例:DJ 打卡上班时,俱乐部的音箱播放浩室歌曲。

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() 这个客户端知道的 session:附近的和它自己的
GetCarSession(vehicle) 这辆车的 session,或 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)

config 示例

设置在 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?

查找 manifest 中带有 audio_extensions 'v1' 的资源,如第一个示例所示。在某些服务器上,文件夹可能叫别的名字。

我的脚本能在玩家的音箱上播放音乐吗?

可以,用 Control(src, key, 'play', { text = 'library:1' })。适用与 Sound 自带遥控器相同的规则:玩家必须有权操作该系统,并且在可操作的距离内。

灯光或道具能跟着音乐变化吗?

可以。客户端导出函数 GetBass(key) 每一帧都会给出正在播放歌曲的低音,范围是 0 到 1。

译自英文。如有任何内容与英文页面不一致,以英文页面为准。 English