ZeroDev Sound 文档
ZeroDev Sound 开发者 API
ZeroDev Sound 为其他资源提供开放的 API:读取正在播放的内容,从你自己的菜单为玩家操作音箱系统或车载音响,跟踪变化,放置你自己的音箱和改装间,并用真实的低音驱动灯光。这里的所有内容都取自 ZeroDev Sound 3.0.5。API 文件没有加密(escrow),你可以自己阅读接口约定:server/devapi.lua 和 client/devapi.lua。
ZeroDev Sound 会检查收到的每一个值,即使你的资源缺失、已停止或出错,它也会继续运行。安静时段、警察静音和所有者设定的音量上限,对所有正在播放的内容都生效。
找到资源
资源的 manifest 中带有标记 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'。
一个 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 打卡上班时,俱乐部的音箱播放浩室歌曲。
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() |
这个客户端知道的 session:附近的和它自己的 |
GetCarSession(vehicle) |
这辆车的 session,或 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)config 示例
设置在 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?
查找 manifest 中带有 audio_extensions 'v1' 的资源,如第一个示例所示。在某些服务器上,文件夹可能叫别的名字。
我的脚本能在玩家的音箱上播放音乐吗?
可以,用 Control(src, key, 'play', { text = 'library:1' })。适用与 Sound 自带遥控器相同的规则:玩家必须有权操作该系统,并且在可操作的距离内。
灯光或道具能跟着音乐变化吗?
可以。客户端导出函数 GetBass(key) 每一帧都会给出正在播放歌曲的低音,范围是 0 到 1。