ZeroDev Sound ドキュメント
ZeroDev Sound 開発者 API
ZeroDev Sound には、ほかのリソース向けのオープンな API があります。再生中の曲の取得、自分のメニューからのスピーカーシステムやカーステレオの操作、変化の監視、独自のスピーカーや取り付けベイの設置、そして実際の低音に合わせたライトの制御ができます。ここに書かれている内容はすべて ZeroDev Sound 3.0.5 に基づいています。API のファイルはエスクローされていないため、server/devapi.lua と client/devapi.lua で仕様を自分で確認できます。
ZeroDev Sound は受け取ったすべての値を検証し、お使いのリソースがない、停止している、壊れている場合でも動き続けます。静音時間、警察による消音、オーナーが設定した音量の上限は、再生されるすべてに適用されます。
リソースを見つける
リソースには、マニフェストのマーカー 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'。
セッションとは、1つの曲のストリームです。ワールド内でリンクされたスピーカーのグループ(kind = 'speakers')、または1台の車のステレオ(kind = 'car'、キーは car:<plate>)を指します。曲はリファレンスで指定します:library:<n>(Config.Library の曲)、file:<name>(web/library のファイル)、request:<n>(オーナーが追加したリクエスト曲)。
サーバー exports
| Export | 戻り値 |
|---|---|
GetSessions() |
サーバー上のすべてのセッション |
GetSession(key) |
1つのセッション。なければ 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これらはサーバー内のローカルイベントで、クライアントから送られることはないため、クライアントが偽造することはできません。
クライアント exports(読み取り専用)
| 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 を使ってください。エスクローされたファイルを変更すると、リソースが読み込まれなくなります。
sourceには本物の値をControlに渡すか、src = 0を使う前に自分で権限を確認してください。GetBassは1フレームに最大1回だけ読み取り、何も再生されていないときは待機してください。- API にはバージョンがあります(
audio_extensions 'v1'、ApiVersion()は 2)。互換性を壊す変更は新しいバージョンになり、変更履歴にも記載されます。
よくある質問
自分のスクリプトから ZeroDev Sound を見つけるには?
最初の例のように、マニフェストに audio_extensions 'v1' があるリソースを探します。サーバーによっては、フォルダー名が別の名前になっていることがあります。
自分のスクリプトからプレイヤーのスピーカーで音楽を再生できますか?
はい。Control(src, key, 'play', { text = 'library:1' }) で可能です。Sound 自身のリモコンと同じルールが適用され、プレイヤーはそのシステムを操作する許可があり、届く範囲にいる必要があります。
ライトやプロップを音楽に合わせて動かせますか?
はい。クライアントの export GetBass(key) が、再生中の曲の低音を、毎フレーム 0 から 1 の値で返します。