أتمتة المحرر باستخدام Python في Unreal Engine: دليل خطوة بخطوة للمبتدئين

ما الذي ستتعلمه في هذا الدليل؟

يمكن استخدام دعم Python في Unreal Editor لتنفيذ مهام الإنتاج المتكررة عبر السكربتات، ودعم خطوط الإنتاج التي تضم تطبيقات 3D مختلفة. ومن المهام الواردة في أمثلة وثائق Epic أتمتة إدارة الأصول، وإنشاء LODs لـ Static Mesh، ووضع محتوى Level بطريقة إجرائية. كما تتيح Python إعداد واجهات مخصصة للمحرر.

سنبدأ في هذا الدليل بإعداد المشروع، ثم نشغّل أمرًا قصيرًا باستخدام Python، ونقارن بين خيارات الأتمتة عبر السكربتات المستندة إلى الملفات. الطرق الموضحة هنا مخصصة لأتمتة المحرر: يمكن استخدام دعم Python عندما يكون Unreal Editor مفتوحًا، لكنه غير متاح أثناء تشغيل اللعبة في Play In Editor أو Standalone Game أو ملف تنفيذي مُعبّأ.

المتطلبات

ستحتاج إلى مشروع Unreal Engine يمكنك تفعيل Python Editor Script Plugin فيه، وإلى Unreal Editor. بحسب دليل Epic، تُفعّل الإضافة لكل مشروع على حدة؛ لذا يجب تفعيلها أيضًا في أي مشروع آخر تريد استخدام Python فيه. ويوصى كذلك بتفعيل إضافة Editor Scripting Utilities، التي توفر واجهات API مبسطة لعمليات المحرر الشائعة.

تضمّن Python Editor Script Plugin إصدار Python 3.11.8 داخل Unreal Editor. لذلك لا تحتاج إلى تثبيت Python على الكمبيوتر لاستخدام هذا الدليل. أما استخدام إصدار مختلف من Python، فيتطلب ضبط متغير البيئة UE_PYTHON_DIR في نظام التشغيل، ثم إعادة بناء Unreal Engine من المصدر.

تصنّف وثائق Epic الخاصة بـPython API الإصدار Unreal Python 5.8 على أنه “Experimental”. كما ينبه دليل الاستخدام الرئيسي إلى أن الميزة تجريبية. لذا من الأفضل اختبار السكربتات أولًا على نسخة من مشروع الإنتاج أو في مشروع اختبار خاضع للرقابة.

خطوة بخطوة: تفعيل الإضافة وتشغيل الأمر الأول

1. افتح المشروع الذي ستعمل عليه في Unreal Editor. من القائمة العلوية، انتقل إلى Edit > Plugins.

2. في قسم Scripting ضمن نافذة الإضافات، ابحث عن Python Editor Script Plugin وحدد مربع Enabled.

3. فعّل أيضًا إضافة Editor Scripting Utilities في النافذة نفسها. بعد إجراء التغييرات، أعد تشغيل المحرر.

4. افتح لوحة Output Log وحوّل إدخال وحدة التحكم إلى وضع Python. أو افتح شريط إدخال وحدة التحكم باستخدام المفتاح ~. تُنفّذ أسطر التعليمات البرمجية المكتوبة في وضع Python فورًا داخل المحرر.

5. كتجربة أولى، اطبع رسالة في Output Log باستخدام دالة Python print:

print("Python etkin")

تُوجَّه مخرجات print إلى لوحة Output Log. لتشغيل عدة أسطر في وحدة التحكم، افصل بينها باستخدام Shift+Enter أو الصق كودًا متعدد الأسطر. تناسب هذه الطريقة تجربة الأسطر واحدًا تلو الآخر وإجراء الفحوصات البسيطة.

خيارات تشغيل ملف سكربت

في المهام المتكررة، يكون الاحتفاظ بالكود في ملف Python طريقة أكثر تنظيمًا للعمل. يمكنك تشغيل الملف بتحديد مساره في وحدة تحكم المحرر:

py "C:\MyScripts\my_script.py"

المسار هنا مثال وارد في وثائق Epic؛ استبدله بموقع السكربت الخاص بك. أو يمكنك اختيار سكربت من الكمبيوتر عبر File > Execute Python Script في النافذة الرئيسية. ويمكن أيضًا إعادة تشغيل الملفات التي سبق تشغيلها من قائمة Recent Python scripts. يقرأ المحرر الملف مجددًا من القرص، لذلك تُنفّذ أحدث التغييرات التي أُجريت عليه.

يُعد التشغيل من سطر الأوامر خيارًا آخر للفرق التي تريد إضافة السكربتات إلى خط الأتمتة. يمكنك تشغيل السكربت بعد فتح المحرر بالكامل وتحميل المشروع ومستوى بدء التشغيل الافتراضي:

UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -ExecutePythonScript="c:\my_script.py"

يتطلب هذا الأسلوب تفعيل Python Scripting Plugin وEditor Scripting Utilities في المشروع. وبعد اكتمال السكربت، يُغلق المحرر.

ولتشغيل أسرع دون واجهة مستخدم، يمكنك استخدام commandlet pythonscript:

UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -run=pythonscript -script="c:\\my_script.py"

لا تحمّل هذه الطريقة المستويات تلقائيًا. إذا كان السكربت يحتاج إلى الوصول إلى محتوى Level محدد، فيمكن استخدام استدعاء التحميل الوارد في وثائق Epic كسطر أول؛ المسار الوارد فيه يخص مشروعًا نموذجيًا، ويجب تعديله ليتوافق مع مسار Level في المشروع الفعلي:

unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).load_level("/Game/maps/UVlayoutTest.UVlayoutTest")

الأخطاء الشائعة والقيود

أكثر ما يُغفل عنه هو ضرورة تفعيل الإضافة لكل مشروع على حدة. لا تفترض أن السكربت الذي يعمل في مشروع سيعمل في مشروع آخر أيضًا؛ تحقق أولًا من حالة الإضافة المعنية. ولا تنسَ متطلبات Editor Scripting Utilities عند استخدام طريقة تشغيل المحرر الكامل عبر سطر الأوامر.

يختلف سلوك commandlet عن تشغيل المحرر الكامل. بما أن commandlet لا يحمّل المستوى تلقائيًا، يجب تضمين خطوة التحميل صراحةً في السكربتات التي تعتمد على محتوى المستوى. أما في طريقة المحرر الكامل، فيُشغّل السكربت بعد فتح المشروع وتجهيز مستوى بدء التشغيل الافتراضي.

كذلك، فإن محاولة استخدام Python لمنطق اللعب ليست استخدامًا مناسبًا. توضح وثائق Epic أن بيئة Python موجودة في Unreal Editor، ولا تتوفر في أوضاع التشغيل. كما أن عقد تشغيل Python من داخل Blueprint متاحة فقط في فئات Blueprint الموجهة للمحرر، مثل Editor Utility Widget وEditor Utility Blueprint، ولا يمكن استخدامها في فئات وقت التشغيل العادية.

أثر ذلك في سير عمل العمارة والتصميم الداخلي والتصور المعماري

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

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

الخطوات التالية

بعد تشغيل السكربت الأول، اختر مهمة صغيرة يمكن التراجع عنها؛ مثل التحقق من أمر داخل المحرر أو أتمتة خطوة إنتاج قائمة بطريقة خاضعة للرقابة. بعد ذلك، احفظ العملية في ملف وجرّب Execute Python Script أو طريقة سطر الأوامر المناسبة. ويمكن أيضًا التفكير في سكربتات بدء التشغيل للمشاريع التي سيستخدمها أكثر من شخص: إذ يمكن وضع init_unreal.py في مجلد Content/Python الخاص بالمشروع أو الإضافة، وسيشغّله المحرر تلقائيًا. كما يمكن تحديد السكربتات التي تُشغّل عند بدء التشغيل في إعدادات المشروع.

مع توسع سير العمل، راجع وثائق Unreal Python API إلى جانب الإصدار الذي تستخدمه؛ فهي مرجع للوحدات والأنواع وعناوين API. وسّع نطاق الاستخدام تدريجيًا، مع مراعاة أن الميزة تجريبية وأن السكربتات تعمل داخل المحرر فقط.

المصدر والترخيص

أُعد هذا الدليل باللغة التركية استنادًا إلى دليل Epic Games بعنوان “Scripting the Unreal Editor Using Python” وصفحة “Unreal Python API Documentation”. تشير المصادر إلى أنها متاحة للاستخدام الحر؛ وقد أُعيد تنظيم النص والأمثلة.