توثيق ZeroDev Sound

واجهة API للمطورين في ZeroDev Sound

يوفر ZeroDev Sound واجهة API مفتوحة للـ resources الأخرى: اقرأ ما يُشغَّل الآن، وشغّل نظام سماعات أو مسجل سيارة للاعب من قائمتك الخاصة، وتابع التغييرات، وضع سماعات وورش تركيب خاصة بك، وحرّك الأضواء بالباس الحقيقي. كل ما هنا مأخوذ من ZeroDev Sound 3.0.5. ملفات الـ API غير مشفّرة بـ escrow، فيمكنك قراءة العقد بنفسك: server/devapi.lua وclient/devapi.lua.

لإصدار ZeroDev Sound 3.0.6قراءة في 6 دقائقآخر تحديث

يتحقق ZeroDev Sound من كل قيمة تُمرَّر إليه ويواصل العمل حتى لو كان الـ resource لديك مفقوداً أو متوقفاً أو معطوباً. تسري الساعات الهادئة وكتم الشرطة وحد الصوت الذي يضعه المالك على كل ما يُشغَّل.

العثور على الـ resource

يحمل الـ resource علامة الـ 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]:.... تبدأ أسماء الأحداث باسم الـ resource: res .. ':session'.

الـ session هي بث أغنية واحد: مجموعة سماعات مرتبطة في العالم (kind = 'speakers') أو مسجل سيارة واحدة (kind = 'car'، والمفتاح car:<plate>). تُختار الأغنية بـ reference: library:<n> (أغنية في Config.Library) أو file:<name> (ملف في web/library) أو request:<n> (طلب أغنية أضافه المالك).

exports السيرفر

Export القيمة المعادة
GetSessions() كل session على السيرفر
GetSession(key) session واحدة، أو nil
GetCarSession(vehicle) الـ session الخاصة بسيارة (entity أو نص اللوحة)، أو nil
Targets(src) ما يستطيع هذا اللاعب تشغيله الآن: { key, kind, label, canPlay, why }
Control(src, key, action, data) ok, reason
Ready() true بعد أن يكتمل تحميل Sound
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 } بالديسيبل، من -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)

سماعات ثابتة وورش التركيب

يستطيع سكربت متجر أو نادٍ أو جراج وضع سماعاته الخاصة وورشة تركيب في مبناه. ليس لها مالك ولا عنصر، ولا تُحفظ أبداً، وتزول عند إيقاف الـ resource لديك. لا يستطيع اللاعبون نقلها أو حزمها؛ ولا تزال الشرطة قادرة على كتمها.

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

أضفها عند بدء الـ resource لديك، ومرة أخرى عند الحدث <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

هذه أحداث محلية على السيرفر، لا تُرسل من عميل أبداً، ولذلك لا يستطيع العميل تزييفها.

exports العميل (للقراءة فقط)

Export القيمة المعادة
GetSessions() الـ sessions التي يعرفها هذا العميل: القريبة منه وخاصته
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)

أمثلة الإعدادات

الإعدادات في 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 يمنع الـ resource من التحميل.
  • مرّر قيمة source الحقيقية إلى Control، أو تحقق من الصلاحية بنفسك قبل أن تستخدم src = 0.
  • اقرأ GetBass مرة واحدة على الأكثر في كل إطار، وأوقف الحلقة مؤقتاً حين لا شيء يُشغَّل.
  • للـ API إصدارات (audio_extensions 'v1'، وApiVersion() 2). التغيير الذي يكسر التوافق يحصل على إصدار جديد وسطر في سجل التغييرات.

الأسئلة الشائعة

كيف أجد ZeroDev Sound من سكربتي؟

ابحث عن الـ resource الذي يحمل الـ manifest فيه audio_extensions 'v1'، كما في المثال الأول. قد يكون للمجلد اسم آخر على بعض السيرفرات.

هل يستطيع سكربتي تشغيل موسيقى على سماعات لاعب؟

نعم، بـ Control(src, key, 'play', { text = 'library:1' }). تنطبق نفس قواعد الريموت الخاص بـ Sound: يجب أن يكون مسموحاً للاعب بتشغيل ذلك النظام وأن يكون في المتناول.

هل تستطيع الأضواء أو الـ props متابعة الموسيقى؟

نعم. يعطي export العميل GetBass(key) باس الأغنية الجارية في كل إطار، من 0 إلى 1.

مترجمة من الإنجليزية. إذا تعارض أي شيء هنا مع الصفحة الإنجليزية، فالصفحة الإنجليزية هي الصحيحة. English