أتمتة Unreal Engine باستخدام Python: تفعيل الإضافة وتشغيل أول نص برمجي

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

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

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

المتطلبات

• مشروع Unreal Engine وUnreal Editor.

• تفعيل Python Editor Script Plugin للمشروع.

• إضافة Editor Scripting Utilities لواجهات برمجة التطبيقات المشتركة لعمليات المحرر التي يوصي بها الدليل.

• لا يلزم تثبيت Python بصورة منفصلة: وفقًا لوثائق Epic Games، تتضمن Python Editor Script Plugin إصدار Python 3.11.8 مضمّنًا.

تحمل وثائق Unreal Python API علامة “5.8 (Experimental)”. وتحذّر Epic Games أيضًا من أن هذه الميزة تجريبية، وتوصي باستخدامها بحذر، خصوصًا عند إصدار المنتجات. لذا يُستحسن اختبار الخطوات الواردة هنا أولًا على نسخة من مشروع الإنتاج أو على مشروع تجريبي. ولا تشير المصادر إلى وجود متطلبات خاصة بحساب.

خطوة بخطوة: تفعيل Python وتشغيل الشيفرة

1. تفعيل الإضافات في المشروع

افتح المشروع المطلوب في Unreal Editor، ثم انتقل من القائمة الرئيسية إلى Edit > Plugins. في قسم Scripting ضمن نافذة الإضافات، ابحث عن Python Editor Script Plugin وفعّل خيار Enabled. وتوصي Epic Games أيضًا بتفعيل Editor Scripting Utilities، التي توفر واجهات مبسطة لعمليات المحرر الشائعة.

يجب إجراء هذا الإعداد لكل مشروع على حدة. أعد تشغيل المحرر بعد تفعيل الإضافات. لا تتجاوز خطوة إعادة التشغيل؛ إذ يطلب الدليل إعادة تشغيل المحرر بعد تثبيت الإضافة.

2. استخدام وضع Python في وحدة التحكم

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

تناسب هذه الطريقة التجارب التفاعلية. كما تُوجّه المخرجات الناتجة عن دالة print إلى لوحة Output Log. وعندما تكون وحدة الأوامر في وضع Cmd، يمكن استخدام الأمر py لتنفيذ بقية السطر باعتبارها شيفرة Python. مثال على استدعاء ملف نصي موجود بهذه الطريقة:

py "C:\MyScripts\my_script.py"

مسار الملف هنا مثال وارد في الدليل، ويشير إلى موقع النص البرمجي المطلوب تشغيله؛ لذا عليك تعديل المسار ليتوافق مع ملفك.

3. تشغيل ملف نصي من قائمة File

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

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

4. التشغيل باستخدام المحرر الكامل من سطر الأوامر

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

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

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

5. استخدام خيار Commandlet دون واجهة المستخدم

تتيح طريقة Commandlet التشغيل السريع والتنفيذ من دون فتح واجهة المحرر، أي في وضع headless. ويوضح الدليل استخدام UnrealEditor-Cmd.exe مع الوسيطتين -run=pythonscript و-script:

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

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

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

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

6. تشغيل المهام المتكررة عند بدء التشغيل

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

لتحديد ملف واحد أو أكثر ليعمل عند فتح المشروع في كل مرة، انتقل إلى إعدادات Plugins > Python ضمن Edit > Project Settings، ثم أضف النصوص البرمجية إلى حقل Startup scripts. أعد تشغيل المحرر بعد تغيير الإعداد؛ إذ تعمل النصوص في المرة التالية لبدء التشغيل، بعد اكتمال تحميل مستوى بدء التشغيل الافتراضي.

أخطاء شائعة

• الاعتقاد بأن تفعيل الإضافة مرة واحدة يكفي: يجب تفعيل Python Editor Script Plugin لكل مشروع على حدة.

• محاولة استخدام Python أثناء تشغيل اللعبة: هذه الميزة مخصصة للمحرر؛ ولا تُستخدم أثناء Play In Editor أو Standalone Game أو تشغيل تطبيق مُعبّأ.

• افتراض أن Commandlet سيحمّل المستوى تلقائيًا: يؤكد المصدر صراحةً أن Commandlet لا يحمّل المستويات تلقائيًا.

• تشغيل النص البرمجي قبل أن تصبح البيئة جاهزة: لا يوصي الدليل بتشغيل نص برمجي باستخدام الأمر py ضمن معامل بدء التشغيل ExecCmd؛ فقد لا تكون بيئة المحرر أو مستوى بدء التشغيل جاهزين بعد.

• تجاهل الطابع التجريبي للميزة: توصف ميزة Python بأنها تجريبية. لذا ينبغي اختبارها أولًا في بيئة مضبوطة، خصوصًا في المشاريع التي ستدخل مرحلة التسليم أو الإصدار.

الأثر في سير عمل العمارة والتصور المعماري

بالنسبة إلى المعماريين ومصممي الديكور الداخلي وفرق archviz الذين ينشئون المشاهد في Unreal Engine، يمكن أن تشكّل Python أساسًا لتنفيذ المهام المتكررة عبر النصوص البرمجية، مثل إدارة المحتوى ووضعه في المستويات. لكن المصادر لا تقدم نصًا برمجيًا محددًا للأتمتة المعمارية؛ إذ يعتمد تكييفها مع سير العمل على محتوى المشروع والشيفرة التي ستُكتب. وتوفر وحدة التحكم بداية مناسبة للتجارب القصيرة، بينما يُعد التشغيل من ملف خيارًا أنسب للنصوص البرمجية القابلة لإعادة الاستخدام.

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

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

ابدأ بتفعيل الإضافات في مشروع تجريبي، ثم قارن بين طريقتَي التشغيل عبر وحدة التحكم وقائمة File. بعد ذلك، انقل المهام التي تنفذها لمرة واحدة إلى ملفات؛ أما مهام الإعداد التي تحتاج إلى تشغيل منتظم، ففكّر في إضافتها إلى نصوص بدء تشغيل المشروع. إذا كنت تحتاج إلى الاستخدام عبر Blueprint، فتذكّر أن عقد Python لا تتوفر إلا في فئات المحرر مثل Editor Utility Widget وEditor Utility Blueprint. ووفقًا للمصدر، تنفذ عقدة Execute Python Script مقطعًا من الشيفرة ولا تشغّل ملفًا؛ أما الخيار Execute Python Command فيتيح تشغيل ملف أو شيفرة. ويمكن الاطلاع على مخرجات الأخطاء في لوحة Output Log.

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

أُعد هذا الدليل بالاستناد إلى صفحات Epic Games الخاصة بالبدء في استخدام Python ضمن Unreal Editor ووثائق Python API. وقد أُتيحت صفحات المصدر لهذا المحتوى بموجب ترخيص حر؛ وأُعيدت صياغته وتكييفه إلى التركية.