توثيق ZeroDev Sound
واجهة API للمطورين في ZeroDev Sound
يوفر ZeroDev Sound واجهة API مفتوحة للـ resources الأخرى: اقرأ ما يُشغَّل الآن، وشغّل نظام سماعات أو مسجل سيارة للاعب من قائمتك الخاصة، وتابع التغييرات، وضع سماعات وورش تركيب خاصة بك، وحرّك الأضواء بالباس الحقيقي. كل ما هنا مأخوذ من ZeroDev Sound 3.0.5. ملفات الـ API غير مشفّرة بـ escrow، فيمكنك قراءة العقد بنفسك: server/devapi.lua وclient/devapi.lua.
يتحقق ZeroDev Sound من كل قيمة تُمرَّر إليه ويواصل العمل حتى لو كان الـ resource لديك مفقوداً أو متوقفاً أو معطوباً. تسري الساعات الهادئة وكتم الشرطة وحد الصوت الذي يضعه المالك على كل ما يُشغَّل.
العثور على الـ resource
يحمل الـ resource علامة الـ 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]:.... تبدأ أسماء الأحداث باسم الـ 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 دخوله للعمل.
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 لديك. لا يستطيع اللاعبون نقلها أو حزمها؛ ولا تزال الشرطة قادرة على كتمها.
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 بعدك.
أحداث السيرفر
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) |
حالة الهيد يونت، لشاشات السيارة |
مثال: إضاءة سفلية تنبض مع الساب ووفر في السيارة.
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.
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.