النماذج الإجرائية

ProceduralModels هي نوع من Model المدفوع بالمعلمات الذي يتيح لك بناء وتوليد كائنات ثلاثية الأبعاد باستخدام التعليمات البرمجية. بدلاً من تعديل محتوى النموذج يدوياً، يمكنك تحديد هيكله من خلال وحدة مولد ومجموعة من الخصائص. عندما تتغير تلك الخصائص، أو عندما يتم تغيير حجم النموذج، يتم تشغيل المولد تلقائيًا لتحديث النموذج.

تسهل النماذج الإجرائية:

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

إدراج النماذج الإجرائية

يمكنك إضافة نماذج إجرائية إلى لعبتك بالطرق التالية:

• إدراج كائن ProceduralModel يدويًا في Workspace. تتضمن هذه الخيار مولد قوالب ModuleScript لمساعدتك على البدء.

  

• توليد نموذج إجرائي باستخدام المساعد أو خادم MCP لاستوديو Roblox.

• إدراج نموذج إجرائي من متجر المبدعين لاستخدامه أو تخصيص نموذج موجود.

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

دالة OnGenerate

تعتبر دالة OnGenerate هي القلب النابض لكل ProceduralModel في شكل OnGenerate(params, targetContainer).

تكون هذه الدالة المحددة من قبل المطور مسؤولة عن توليد محتوى النموذج بناءً على المعلمات المقدمة وكتابة النتائج في الحاوية المعطاة.

تتمتع دالة OnGenerate بمسؤوليتين رئيسيتين:

• معالجة المعلمات المدخلة لتحديد هيكل النموذج
• كتابة النتائج المولدة وفقًا لذلك الهيكل إلى targetContainer المقدم

تصف الأقسام التالية:

• متى وكيف تستدعي المحرك OnGenerate
• كيف يقوم المحرك بمعالجة المحتويات المكتوبة في targetContainer

وحدات المولد

تُعرف دالة OnGenerate داخل ModuleScript تُسمى وحدة مولد. يقوم ProceduralModel بتحديد وحدة المولد التي يجب استخدامها من خلال خاصية Generator الخاصة به.

وحدات المولد هي وحدات Luau قياسية، لكنها مطلوبة مباشرة من قبل المحرك كجزء من عملية التوليد. تتبع هيكل محدد وتعيد جدولاً مع حقول موحدة.

هيكل وحدة المولد
local MyGenerator = {}

MyGenerator.Attributes = {
    DoSomething = true,
    AmountOfSomething = 137,
}

type Params = {
    Size: Vector3,
    Attributes: typeof(MyGenerator.Attributes),
    Pause: (self: any) -> (),
}
function MyGenerator.OnGenerate(params: Params, targetContainer: GeneratedFolder)
    
end

return MyGenerator

تشمل الحقول الموحدة:

• Attributes: خريطة تُعرف أسماء المعلمات وقيمها الافتراضية.
• OnGenerate: الدالة التي تستقبل جدول params وtargetContainer.

يتضمن جدول params داخل دالة OnGenerate:

• Attributes: جدول يحتوي إما على الخصائص المحددة بواسطة الوحدة أو جميع خصائص النموذج إذا لم يتم تحديد أي منها.
• Size: معلمة تعكس أبعاد النموذج على مقياس واحد.
• Pause: طريقة تسمح بالتوليد لتؤجل بكفاءة أثناء المهام المعقدة.

يجب أن تقوم دالة OnGenerate بتوليد المحتوى حول الأصل في targetContainer. ينبغي عليها ألا تقوم بتعديل هيكل DataModel الرئيسي مباشرةً.

المعلمات

المعلمات هي المدخلات التي تتحكم في التوليد. تتضمن هذه المعلمة المدمجة Size الخاصة بـ ProceduralModel، بالإضافة إلى الخصائص المخصصة المحددة في وحدة المولد. تُمرر هذه المعلمات الصريحة مباشرةً إلى OnGenerate. تُTrigger المعلمات الضمنية، مثل شفرة المصدر للوحدة أو حالة الدSandboxing، أيضًا إعادة التوليد عند تغييرها ولكنها لا تُمرر إلى OnGenerate.

تتضمن المجموعة الكاملة من المعلمات:

• صريحة:

  • Size: تعرف المنطقة حول الأصل حيث يتم توليد المحتوى.
  • Attributes: خريطة تحتوي على قيم خاصية الإدخال الحالية.
• ضمنية:

  • Generator: الوحدة التي تزود منطق التوليد.
  • شفرة المصدر: تغييرات في شفرة Luau لوحدة المولد.
  • Sandboxing: تغييرات على حالة الدSandboxing لوحدة المولد.

سلوك إعادة التوليد

للحفاظ على الأداء وتبسيط تفاعلات واجهة البرمجة، لا يتم استدعاء OnGenerate فوراً عند تغيير المعلمات. بدلاً من ذلك، يتم وضع علامة على ProceduralModel على أنه غير نظيف، مما يدل على أن إعادة التوليد معلقة. وغالبًا ما تحدث هذه الإعادة المعلقة لاحقًا في نفس الإطار.

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

عملية التنفيذ

عند توفر وقت المعالجة، يقوم المحرك بإعادة توليد النماذج غير النظيفة من خلال تنفيذ الخطوات التالية:

1. يتطلب وحدة المولد، مع التوقف إذا لزم الأمر.
2. يبدأ خيطًا جديدًا لعملية التوليد.
3. يبني جدول المعلمات، يقوم بتطبيع Size حسب مقياس النموذج الحالي.
4. يطبق القيم الافتراضية على أي خصائص مفقودة.
5. يقوم بتهيئة GeneratedFolder مؤقتة كـ targetContainer.
6. يستدعي OnGenerate.
7. بعد عودة OnGenerate:

   • إذا كانت ناجحة، يتم نقل النتائج في targetContainer إلى ProceduralModel.
   • إذا فشلت التوليد، تُستخدم عنصر نائبة للفشل بدلاً من ذلك.

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

نتائج التوليد

تتضمن خطوات وضع النتائج المولدة في النموذج ما يلي:

1. إنهاء أي خيوط فرعية تسربت أثناء التوليد.
2. وضع النتائج باستخدام PivotTo.
3. إذا لم يكن مقياس النموذج 1، يستخدم ScaleTo لإلغاء تطبيع الحجم.
4. ينسب النتائج إلى GeneratedFolder للنموذج.
5. إذا كانت وحدة المولد في وضع ساندي، يتأكد من أن ModuleScripts في النتيجة لا تتجاوز قدرات وحدة المولد.
6. يمتلئ أي خصائص مفقودة في النموذج بقيمها الافتراضية.
7. يتم مسح حالة النموذج غير النظيفة.

تفاصيل التوليد

بالإضافة إلى تدفق التوليد الرئيسي، تصف التفاصيل التالية سلوكيات واعتبارات تؤثر على كيفية عمل توليد ProceduralModel.

الحجم

بسبب تطبيع المقياس الذي يتم تطبيقه أثناء التوليد، تدعم ProceduralModel عدة سير عمل لحجم:

• تغيير خاصية Size يعيد توليد النموذج بمحتوى جديد.
• تغيير Scale يقوم بتغيير حجم النتائج الحالية بشكل موحد باستخدام ScaleTo.

مهلات

كإجراء وقائي، يتم إنهاء وحدة المولد التي تؤدي الكثير من العمل دون التوقف. إذا وصلت عملية التوليد إلى خطأ "مهلة برنامج نصي"، أضف استدعاءات إضافية إلى parameters:Pause() للسماح للمحرك بتأجيل العمل المتبقي إلى إطار لاحق.

استدعاء parameters:Pause() رخيص جداً وعادة ما يعود على الفور أثناء تنفيذ المولد العادي، لذا يمكن استدعاؤه بحرية في بداية الحلقات دون التأثير على الأداء.

تاريخ التراجع

تُجمع النتائج المولدة مع تغيير المعلمة الذي أطلقها باستخدام تجاوزات نقطة التراجع. إذا حدثت تغييرات متعددة على المعلمات في إطار واحد، تُرتبط النتائج بأحدث نقطة.

Sandbox

تدعم ProceduralModel وضع Sandbox. جميع النماذج الإجرائية من الأطراف الثالثة التي تُدرجها من متجر المبدعين تكون في وضع Sandbox بشكل افتراضي للمساعدة في منع التغييرات غير المرغوب فيها في لعبتك.

تعمل شفرة التوليد في سياق وحدة المولد وتستخدم حالة الدSandboxing لتلك الوحدة. لا تظهر هذه الإعدادات افتراضيًا. لمشاهدتها أو تعديلها، اضبط Workspace.SandboxedInstanceMode = Experimental. هذا يكشف خصائص Sandboxed و Capabilities على ModuleScript.

تتطلب وحدة المولد التي تعمل في وضع Sandbox عادةً على الأقل القدرات التالية:

• RunServerScript (لتنفيذ الوحدة)
• CreateInstances
• Basic

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

التعشيش

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

القيود

• لا يُدعم التوليد داخل مثيلات Actor.
• لا يمكن تحويل النماذج إلى حزم.
• لا تُحافظ المفاصل التي تُنشأ عند استخدام أدوات السحب مع سطوح المفاصل الممكّنة عبر تجديد ProceduralModel.