قدرات السكربت

قدرات السكربت تمكنك من التحكم في الإجراءات التي يمكن أن تقوم بها السكربتات داخل شجرة DataModel. بدلاً من نظام "الكل أو لا شيء" الافتراضي، يمكنك ضبط السكربت ليكون قادرًا على الوصول إلى فئات معينة فقط، مثل الصوت، والفيزياء، ومتاجر البيانات، والمزيد.

• يتيح لك هذا النظام تحديد ما يمكن لنماذج المستخرجة من صندوق الأدوات القيام به، ويسهل تضمين المحتوى الذي أنشأه المستخدم داخل اللعبة.
• يمكن أن يساعد أيضًا في ضمان أمان أفضل للألعاب التي تسمح للاعبين بتشغيل الشفرات الخاصة بهم، والتي يتم تنفيذها غالبًا في بيئة مقيدة أو محاكية.
• يمكن أيضًا استخدامه لمشاركة المكتبات التي تحد من ما يمكن أن تفعله بنفسها. على سبيل المثال، يمكن أن تكون مكتبة توفر طرق رياضية إضافية محدودة بأصغر مجموعة من القدرات التي تحتاجها بحيث لا يتعين على المطورين الآخرين الذين يستخدمون تلك المكتبة التحقق من كامل قاعدة التعليمات البرمجية للتأكد من عدم تضمينها شفرات ضارة.

تفعيل قدرات السكربت

لتفعيل هذه الميزة، قم بتغيير خاصية SandboxedInstanceMode من Default إلى Experimental في نافذة المستكشف و الخصائص.

حاوية محمية

تintroduces قدرات السكربت مفهوم حاوية محمية. يحتوي Models و Folders و Scripts، أو أي من أحفاد هذه الفئات على خاصية Sandboxed المتاحة في نافذة الخصائص.

تفعيل خاصية Sandboxed يحدد العنصر كحاوية محمية داخل شجرة DataModel، مما يحد من الإجراءات التي يمكن أن تقوم بها السكربتات داخل تلك الحاوية بناءً على مجموعة القيم في خاصية Capabilities.

القدرات

خاصية Capabilities هي مجموعة من القيم التي تتحكم في جوانب مختلفة من التنفيذ. تقع القدرات ضمن الفئات العامة التالية:

• التحكم في التنفيذ - تحدد ما إذا كان يمكن للسكربت العمل على العميل أو الخادم
• التحكم في الوصول إلى العناصر - تحدد أجزاء DataModel التي يمكن أن يتفاعل معها السكربت
• التحكم في وظائف السكربت - تحدد الوظائف التي يمكن أن تستدعيها السكربتات
• التحكم في الوصول إلى واجهة برمجة التطبيقات - تحدد أي أجزاء من واجهة برمجة التطبيقات الخاصة بـ Roblox يمكن استخدامها

عند محاولة السكربت تنفيذ إجراء غير موجود في مجموعة القدرات، تُبلغ Roblox عن خطأ. تشمل الأخطاء عادةً الإجراء الذي تم محاولة تنفيذه، الهدف من الإجراء، وأول قدرة مفقودة:

لا يمكن للخيط الحالي تعديل 'Workspace' (يفتقر إلى القدرة AccessOutsideWrite)
لا يمكن للخيط الحالي استدعاء 'Clone' (يفتقر إلى القدرة CreateInstances)
لا يمكن للخيط الحالي استدعاء 'GetSecret' (يفتقر إلى القدرة Network)

التحكم في التنفيذ

تعامل قدرتان مع التحكم في التنفيذ:

• RunClientScript - يُسمح لـ LocalScript أو Script الذي يحمل قيمة RunContext من نوع Client بالتنفيذ على العميل
• RunServerScript - يُسمح لـ Script الذي يحمل قيمة RunContext من نوع Server بالتنفيذ على الخادم

إذا كان السكربت Enabled، لكن القدرة المقابلة لمكان البدء ليست متاحة، يتم عرض رسالة تحذير في نافذة الإخراج. إذا لم يكن من المفترض أن يعمل السكربت في تلك السياق، قم بتعطيله أو حذفه.

لاحظ أن ModuleScripts لا تحتاج إلى امتلاك هذه القدرات التنفيذية لتكون مطلوبة.

عندما يفشل السكربت في البدء بسبب فقدان القدرة على التحكم في التنفيذ، يتم الإبلاغ عن ذلك كتحذير في الإخراج، على سبيل المثال:

لا يمكن بدء السكربت الخادمي 'Script' (يفتقر إلى القدرة RunServerScript)

التحكم في الوصول إلى العناصر

تعامل قدرة واحدة مع التحكم في الوصول إلى العناصر:

• AccessOutsideWrite - يُسمح للسكربت بجلب واستقبال العناصر من خارج الحاوية المحمية

عندما تكون القدرة غير متاحة، يمكن للسكربت فقط البحث عن العناصر التي تكون داخل حاويته المحمية. على سبيل المثال، إذا وُضِع السكربت مباشرةً في الحاوية المحمية، فإن script.Parent.Parent يعيد nil.

بالإضافة إلى ذلك، أي حدث API من Roblox يمرر في Instance يمرر nil لأي Instance خارج الحاوية المحمية. على سبيل المثال، إذا تم تفعيل حدث BasePart.Touched بلمسة من عنصر خارج الحاوية المحمية، يتم استلام الحدث، لكن الحجة تكون nil.

تجنب تعيين هذه القدرة؛ ضمانات الحماية تكون أضعف عندما يمكن للسكربتات التفاعل مع أي عنصر في اللعبة.

الوصول إلى الخدمات

حتى بدون AccessOutsideWrite، يمكن للسكربتات في الحاوية المحمية الاستمرار في الوصول إلى game و workspace والخدمات. يتم توفير هذا الوصول حتى تتمكن السكربتات من استدعاء طرق مفيدة من تلك المتغيرات العالمية، مثل DataModel.GetService، لكن الوصول إلى عناصرها الفرعية لا يزال يتم التحقق منه.

العناصر الممررة داخليًا

إذا تم تمرير عنصر من خلال استدعاء دالة لا تمر عبر واجهات برمجة تطبيقات Roblox، يُحتفظ بالمرجع. ومع ذلك، إذا تم تمرير ModuleScript بهذه الطريقة، فلا يمكن استدعاؤه بدون AccessOutsideWrite. وذلك لأن نتيجة ModuleScript غالبًا ما تكون قابلة للتغيير ويمكن تعديلها بواسطة سكربت في حاوية محمية.

التحكم في وظائف السكربت

تتحكم مجموعة قدرات هذه في بعض الجوانب العامة للسكربتات:

• CreateInstances - يمكن للسكربت إنشاء عناصر جديدة باستخدام Instance.new و Instance.fromExisting أو Instance:Clone()
• LoadString - يُسمح للسكربت باستدعاء loadstring
• LoadUnownedAsset - يُسمح للسكربت باستدعاء require مع معرف الأصل أو AssetService:LoadAssetAsync()
• ScriptGlobals - يحتوي السكربت على shared و _G المتاحة

تذكر أن قيود الوظائف الافتراضية لا تزال تنطبق. حتى إذا كانت LoadString مفعلّة، يجب على اللعبة أيضًا تفعيلها في ServerScriptService، ولا تزال متاحة فقط على الخادم.

لإنشاء عناصر جديدة، بالإضافة إلى CreateInstances، تتطلب واجهة API الخاصة بالمحرك قدرة إضافية توفر الوصول إلى تلك العناصر.

التحكم في الوصول إلى واجهة برمجة التطبيقات

تتحكم مجموعة القدرات الأخيرة هذه في وصول السكربت إلى واجهات برمجة التطبيقات المختلفة:

• Animation - الوصول إلى العناصر المتعلقة بالرسوم المتحركة
• AssetCreateUpdate - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بإنشاء أو تحديث الأصول
• AssetManagement - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بالعمليات على الأصول التي لا تُقرأ أو تُنشأ أو تُحدث
• AssetRead - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بالحصول على معلومات حول الأصول
• Audio - الوصول إلى العناصر المتعلقة بواجهات برمجة تطبيقات الصوت
• AvatarAppearance - الوصول إلى العناصر المتعلقة بالعناصر المرئية للصور الرمزية
• AvatarBehavior - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بالتحكم أو تعديل البشرية
• Basic - الوصول إلى واجهات برمجة التطبيقات العامة التي تقدم مخاطر قليلة
• CSG - الوصول إلى العناصر والوظائف المتعلقة بالهندسة الصلبة البنائية (CSG)
• CapabilityControl - الوصول إلى تعديل خصائص Sandboxed وCapabilities للعناصر
• Capture - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بالتقاط لقطات الشاشة أو الفيديوهات على شاشة المستخدم
• Chat - الوصول إلى العناصر المتعلقة بالدردشة داخل اللعبة
• Consequences - الوصول إلى واجهات برمجة التطبيقات لمعاقبة المستخدمين (طرد أو حظر)
• DataStore - الوصول إلى واجهات برمجة التطبيقات الخاصة بمتجر البيانات ومتجر الذاكرة
• DynamicGeneration - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بتعديل الأصول ديناميكيًا
• Environment - الوصول إلى العناصر المتعلقة بالتحكم في كيفية عرض البيئة
• Groups - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بالمجموعات/المجتمعات
• Input - الوصول إلى العناصر المتعلقة بإدخال المستخدم
• LegacySound - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بالصوت الذي سيتم إهماله
• LoadOwnedAsset - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك لتحميل الأصول المملوكة لك، أو المشتركة معك، أو المملوكة لروبلوكس، أو متعلقة بنوع الأصول السليمة
• Logging - الوصول إلى واجهة برمجة التطبيقات الخاصة بالسجلات
• Material - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بالمواد
• Monetization - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بتحقيق الدخل من لعبة، باستثناء معظم PromptPurchases
• Network - الوصول إلى واجهات برمجة التطبيقات الخاصة بالشبكات HTTP
• Physics - الوصول إلى العناصر المتعلقة بالفيزياء
• PlatformAvatarEditing - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بإنشاء أو تحديث الصور الرمزية، أو واجهات برمجة التطبيقات لمساعدة ذلك
• Players - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بفئة Player أو التي ترجع/تتفاعل مع Players.LocalPlayer
• PromptExternalPurchase - يتيح الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بمطالبة شراء أصول عشوائية
• RemoteEvent - الوصول إلى العناصر لعمليات الشبكات الداخلية
• SensitiveInput - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بالتقاط إدخال حساس من المستخدم، أي مستشعرات أجهزة خصوصية عالية.
• ServerCommunication - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بالتواصل عبر الخوادم، مثل MessagingService
• Social - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بالميزات الاجتماعية، مثل الأصدقاء والدعوات
• Teleport - الوصول إلى واجهات برمجة التطبيقات الخاصة بالمحرك المتعلقة بالتنقل
• UI - الوصول إلى العناصر المتعلقة بواجهات المستخدم

تُعرض قدرات كل فئة، وخصائص، وطرق، وأحداث في مرجع واجهة برمجة التطبيقات للمحرك. على سبيل المثال، يتطلب Player:GetFriendsOnlineAsync() قدرة Player و Social.

تتوفر العديد من طرق HttpService بدون أي قدرات بخلاف القدرة على تنفيذ السكربتات:

• HttpService:JSONDecode()
• HttpService:JSONEncode()
• HttpService:GenerateGUID()

إذا تم الوصول إلى خاصية أو طريقة عنصر بدون قدرة مطلوبة، يتم الإبلاغ عن خطأ يصف القدرة المفقودة.

أخيرًا، لا تغطي القدرات كل عنصر في محرك Roblox اليوم. العناصر غير المدرجة في هذا القسم أو القسم التالي غير متاحة للتفاعل من حاوية محمية وتطرح خطأ تقول أن قدرة غير معينة غير متاحة للسكربت الحالي.

limitation إضافية هي أن دوال getfenv() و setfenv() غير متاحة للسكربتات في حاوية محمية. يُبلغ استدعائها من سكربت محمي عن:

لا يمكن للخيط الحالي استدعاء ['getfenv'/'setfenv'] - الهدف يستخدم واجهات برمجة التطبيقات غير المتاحة في الحماية الحالية

يقتصر وصول السكربت إلى العناصر فقط. يمكن للعناصر نفسها لا تزال توجد وتعمل بأنفسها داخل حاوية محمية. تظل الأضواء مضاءة، وواجهات المستخدم لا تزال مرئية، وتلعب إعدادات الصوت المتصلة بالفعل الأصوات.

التفاعلات بين الحاويات

الحاويات المتداخلة

عندما تكون حاوية محمية واحدة مدمجة داخل أخرى، فإن العناصر في الحاوية الداخلية تكون متاحة للحاوية الخارجية.

تقتصر قدرات الحاوية الداخلية على القدرات الخاصة بالحاوية الخارجية. على سبيل المثال، إذا كانت الحاوية الخارجية تمتلك قدرات Basic، Audio و CSG، بينما تحتوي الحاوية الداخلية على Basic و Network، فإن القدرات المتاحة للحاوية الداخلية في وقت التشغيل هي فقط Basic.

إذا لم تكن هناك قدرات مشتركة بين الحاويتين الداخلية والخارجية، فإن مجموعة القدرات الناتجة تكون فارغة.

الدوال والأحداث القابلة للإشعال

تقدم BindableEvent و BindableFunction أفضل طريقة للتواصل مع الحاوية أو السماح لها بتشغيل الاستدعاءات باستخدام القدرات التي لا يُسمح لها باستخدامها مباشرة.

عند إطلاق حدث أو استدعاء دالة، يتم تنفيذ الاتصالات في سياق الدالة التي قامت بتسجيلها. هذا يعني أنه إذا تم تسجيل الحدث أو استدعاء الدالة بواسطة الحاوية المحمية، يتم استدعاؤها باستخدام قدرات تلك الحاوية. إذا تم تسجيل الاستدعاء بواسطة الشيفرة خارجًا، فإن السكربتات الموجودة في الحاوية المحمية تستدعيها، يقومون بتنفيذ دوالك باستخدام القدرات المتاحة لدوالك.

من المهم أن نلاحظ أنه حتى مع قدرة AccessOutsideWrite، لا يمكن للسكربتات في الحاويات المحمية استدعاء الأحداث أو الدوال خارج حاوياتها إذا كانت لديها مجموعة قدرات أكبر من الحاوية نفسها.

عندما يحاول سكربت محمي إطلاق أو استدعاء حدث أو دالة (BindableEvent، BindableFunction، أو RemoteEvent) تكون قدراتها الأجداد أكبر من قدراته الخاصة، يسمي الخطأ الخاصية التي يجب التحقق منها.

إذا لم يكن الهدف داخل أي حاوية محمية:

لا يمكن للخيط الحالي إطلاق '<Target>' لأن '<Target>' لديه خاصية محمية مضبوطة على false ولكن الخيط المستدعي محمي

لحل هذه المشكلة، قم بتعيين Sandboxed إلى true للهدف. بدلاً من ذلك، يمكنك تعديل مصدر الخيط المستدعي ليكون لديه Sandboxed مضبوطة على false، ولكن لا يُوصى بذلك لأنه يقضي على فوائد الأمان التي توفرها الحماية.

إذا كان الهدف محميًا ولكن لديه قدرات يفتقر إليها المستدعي:

لا يمكن للخيط الحالي إطلاق '<Target>' لأن '<Target>' لديه قيم إضافية لخاصية Capabilities: <First Missing Capability> (و N أكثر)

لحل هذه المشكلة، ضيق قدرات الهدف Capabilities إلى مجموعة فرعية من قدرات المستدعي، أو قم بتوسيع قدرات المستدعي Capabilities لتتناسب مع قدرات الهدف.

استدعاء الوحدة

يمكن للحاوية المحمية عادةً أن تطلب ModuleScripts الداخلية كما هو معتاد. ومع ذلك، إذا كانت العنصر الهدف خارج الحاوية، فلا يمكن طلب ModuleScript إلا إذا كانت مجموعة القدرات المتاحة لها أصغر أو تساوي القدرات المتاحة للحاوية.

لا تنطبق هذه القيود على قدرات RunClientScript و RunServerScript. إذا وُضِع ModuleScript في حاوية تحتوي فقط على RunClientScript ولكن تم طلبه من سكربت يمتلك قدرة RunServerScript، فإنه يُسمح له بالنجاح وتشغيل تلك الوظائف على الخادم.

عندما يفشل require() بسبب عدم تطابق القدرة، يسمي الخطأ وحدة الهدف والخاصية التي يجب التحقق منها بنفس الطريقة كما في دوال وأحداث Bindable المذكورة في القسم السابق.

دوال الاستدعاء المباشر

إذا تم طلب دالة ModuleScript في حاوية محمية من خارج الحاوية، فإن بعض الحماية لن تكون متاحة. بشكل خاص، يمكن أن تصل الدالة المستهدفة إلى جميع العناصر المتاحة للمستدعي. إذا لم يكن المستدعي في حاوية محمية، فإن الاستدعاء يتصرف كما لو كانت AccessOutsideWrite متاحة له.

لا تزال تنطبق القيود الأخرى للقدرة. إذا كانت لديك قدرة الوصول إلى DataStore، لكن الوحدة المستهدفة ليس لديها ذلك، فلن تتمكن من استدعاء طرق DataStore. ومع ذلك، إذا قمت بتمرير دالتك الخاصة التي تعمل مع DataStore، يمكن للهدف تشغيلها خلال ذلك الاستدعاء. إذا كان الهدف يقوم بجدولة خيط باستخدام طرق مثل تلك الموجودة في task، فإن تلك الخيوط تفقد القدرة على استدعاء تلك الدالة.

يمكن تمرير العناصر إلى الوحدة المستهدفة أو تعيينها إلى حقول الوحدة.

إذا لزم الأمر، يُوصى بتعيين أعضاء الجدول باستخدام rawset لتجنب تشغيل الـ __index/__newindex الطرق التحول التي قد تكون قد تم تعيينها على الجدول.

التوصية العامة هي التواصل مع BindableEvent و BindableFunction كلما كان ذلك ممكنًا.

حركة العناصر

لا تحتوي معظم العناصر على قيود على الحركة بين الحاويات. ومع ذلك، يمكن نقل عناصر السكربت فقط إلى حاوية تحتوي على نفس مجموعة القدرات أو مجموعة فرعية من تلك القدرات.

وهذا يعني أن الحاوية المحمية التي تحتوي على AccessOutsideWrite لا يمكنها فقط إعادة تهيئة سكربت داخلها إلى الخارج والحصول على المزيد من القدرات.