ZeroDev Sound ドキュメント

ZeroDev Sound 開発者 API

ZeroDev Sound には、ほかのリソース向けのオープンな API があります。再生中の曲の取得、自分のメニューからのスピーカーシステムやカーステレオの操作、変化の監視、独自のスピーカーや取り付けベイの設置、そして実際の低音に合わせたライトの制御ができます。ここに書かれている内容はすべて ZeroDev Sound 3.0.5 に基づいています。API のファイルはエスクローされていないため、server/devapi.lua と client/devapi.lua で仕様を自分で確認できます。

ZeroDev Sound 3.0.6 向け約6分で読めます更新日

ZeroDev Sound は受け取ったすべての値を検証し、お使いのリソースがない、停止している、壊れている場合でも動き続けます。静音時間、警察による消音、オーナーが設定した音量の上限は、再生されるすべてに適用されます。

リソースを見つける

リソースには、マニフェストのマーカー 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'。

セッションとは、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 が出勤を打刻すると、クラブのスピーカーでハウスの曲が流れる。

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

リソースの起動時と、Sound があとから起動した場合に備えて <res>:ready の際にも、追加してください。

サーバーイベント

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

これらはサーバー内のローカルイベントで、クライアントから送られることはないため、クライアントが偽造することはできません。

クライアント exports(読み取り専用)

Export 戻り値
GetSessions() このクライアントが把握しているセッション:近くのものと自分のもの
GetCarSession(vehicle) 車のセッション。なければ 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 を使ってください。エスクローされたファイルを変更すると、リソースが読み込まれなくなります。
  • 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 の値で返します。

英語から翻訳しています。内容が英語のページと異なる場合は、英語のページが正しい内容です。 English