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
endexports[res]:...로 호출합니다. 이벤트 이름은 리소스 이름으로 시작합니다: res .. ':session'.
세션은 곡 하나의 스트림입니다. 월드에서 연결된 스피커 그룹(kind = 'speakers') 또는 차 한 대의 스테레오(kind = 'car', 키는 car:<plate>)입니다. 곡은 참조로 지정합니다: library:<n>(Config.Library의 곡), file:<name>(web/library의 파일), request:<n>(소유자가 추가한 신청곡).
서버 export
| Export | 반환값 |
|---|---|
GetSessions() |
서버의 모든 세션 |
GetSession(key) |
세션 하나. 없으면 nil |
GetCarSession(vehicle) |
차량의 세션(엔티티 또는 번호판 문자열). 없으면 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 |
dB 단위의 { low, mid, high }, -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리소스가 시작될 때, 그리고 Sound가 나중에 시작되는 경우를 대비해 <res>:ready에서도 다시 추가하세요.
서버 이벤트
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이들은 서버 로컬 이벤트이며 클라이언트에서 보내지 않으므로, 클라이언트가 위조할 수 없습니다.
클라이언트 export(읽기 전용)
| Export | 반환값 |
|---|---|
GetSessions() |
이 클라이언트가 아는 세션: 주변의 세션과 자기 세션 |
GetCarSession(vehicle) |
차량의 세션. 없으면 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 자체 리모컨과 같은 규칙이 적용되어, 플레이어는 그 시스템을 조작할 권한이 있고 손이 닿는 거리에 있어야 합니다.
조명이나 프롭이 음악을 따라 움직이게 할 수 있나요?
네. 클라이언트 export GetBass(key)가 재생 중인 곡의 베이스를 매 프레임 0에서 1 사이 값으로 돌려줍니다.