كيف تكتب إضافة Python في Blender؟ إنشاء أول مشغّل

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

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

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

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

المتطلبات

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

يحدد المثال الوارد في الدليل إصدار Blender على أنه (2, 80, 0) ضمن معلومات الإضافة. وهذه القيمة هي الحد الأدنى للإصدار المذكور في البيانات الوصفية للمثال؛ ولا تعني أن الشيفرة اختُبرت أيضًا مع إصدارات Blender الحالية. لذا ينبغي التحقق من سلوك الواجهة البرمجية في الإصدار الذي تستخدمه. ولا يذكر الدليل متطلبات لحساب مستخدم أو ميزة عتادية أو ترخيص مدفوع.

يُعد تشغيل Blender من الطرفية أحد الخيارات المتاحة لتصحيح الأخطاء. ويشير الدليل أيضًا إلى أن تفعيل إضافات المطوّرين من التفضيلات قد يساعد في عملية تطوير الإضافات.

خطوة بخطوة: اكتب أول مشغّل

1. أضف الشيفرة إلى محرر النصوص

يعرّف الصنف ObjectMoveX المشغّل في المثال أدناه. عند تشغيل execute()، تُعالَج كائنات المشهد النشط واحدًا تلو الآخر، وتُضاف القيمة 1.0 إلى موضع كل منها على المحور X. ويسمح الخيار UNDO ضمن bl_options باستخدام المشغّل مع إمكانية التراجع عن العملية.

bl_info = {
    "name": "Move X Axis",
    "blender": (2, 80, 0),
    "category": "Object",
}

import bpy

class ObjectMoveX(bpy.types.Operator):
    """My Object Moving Script"""
    bl_idname = "object.move_x"
    bl_label = "Move X by One"
    bl_options = {'REGISTER', 'UNDO'}

    def execute(self, context):
        scene = context.scene
        for obj in scene.objects:
            obj.location.x += 1.0
        return {'FINISHED'}

def register():
    bpy.utils.register_class(ObjectMoveX)

def unregister():
    bpy.utils.unregister_class(ObjectMoveX)

if __name__ == "__main__":
    register()

يسجّل هذا المثال البسيط فئة المشغّل، لكنه لا يضيف عنصرًا إلى قائمة أو واجهة. وتزيل unregister() الفئة التي سبق تسجيلها. يحدد bl_idname المعرّف الفريد للمشغّل، بينما يحدد bl_label الاسم الظاهر في واجهة Blender ونتائج البحث. وعند نجاح العملية، تعيد الدالة execute() النتيجة FINISHED.

2. شغّل النص البرمجي واستدعِ المشغّل

الصق الشيفرة في محرر النصوص في Blender وشغّلها. يسجّل النص البرمجي المشغّل، لكنه لا يحرّك الكائنات تلقائيًا في هذه المرحلة. بعد ذلك، افتح نافذة البحث عن المشغّلات، وابحث عن الاسم Move X by One، ثم شغّل المشغّل. تنقل العملية جميع الكائنات في المشهد النشط بمقدار وحدة واحدة على المحور X.

من المهم استخدام المعامل context في execute(self, context). فقد يشغّل Blender المشغّلات أحيانًا ضمن سياق خاص. لذلك يوصي الدليل باستخدام قيمة context التي تُمرّر إلى المشغّل بدلًا من الرجوع مباشرةً إلى السياق العام.

3. احفظ الملف وحمّله كإضافة

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

يؤدي تفعيل الإضافة إلى تشغيل Blender للوحدة وتنفيذ عمليات التسجيل الواردة في register(). وعند إيقاف الإضافة، يستدعي Blender الدالة unregister()، ما يؤدي في هذا المثال إلى إزالة فئة المشغّل. قد تظهر مجلدا المصدر والوجهة في وحدة التحكم أثناء التثبيت. ويشرح الدليل أيضًا كيفية عرض مسارات الإضافات باستخدام addon_utils.paths() في وحدة تحكم Python.

الاستخدام في سير عمل العمارة والتصوّر

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

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

أخطاء شائعة

• توقّع تحرّك الكائنات فور تشغيل النص البرمجي: يسجّل التشغيل الأول المشغّل. ولتغيير الكائنات، يجب اختيار Move X by One من نافذة البحث عن المشغّلات.

• إغفال نطاق التأثير: لا تقتصر الشيفرة على الكائنات المحددة، بل تعالج جميع الكائنات في المشهد النشط.

• نسيان تنسيق الملف: احفظ ملف الإضافة بامتداد .py واختر اسمًا صالحًا للاستخدام كوحدة Python.

• الخلط بين الحفظ والتفعيل: حفظ الملف وحده لا يفعّل الإضافة. يجب تحميل الملف من التفضيلات ثم تفعيلها من القائمة.

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

ابدأ بتشغيل المثال في مشهد تجريبي ولاحظ نتيجة المشغّل. ثم تعرّف إلى وظيفة bl_info وفئة المشغّل وexecute() ودوال التسجيل، كلٌّ على حدة. وفي مرحلة التطوير التالية، يمكنك استكشاف تحويل القيم الثابتة إلى خصائص للمشغّل قابلة للضبط من قبل المستخدم؛ إذ يتناول الجزء التالي من دليل Blender هذا الموضوع ومثالًا آخر لإنشاء نسخ من كائنات مرتبطة.

عند ظهور رسائل خطأ، قد تساعدك مراجعة مخرجات وحدة التحكم في Blender على تحديد الخطوة التي وقع فيها الخلل. ومن المراجع التي يشير إليها الدليل لمزيد من التفاصيل: النظرة العامة على Blender API، ووثيقتا bpy.context وbpy.types.Operator.

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

أُعدّ هذا الدليل بتكييفه إلى التركية استنادًا إلى وثيقة Blender الرسمية «Add-on Tutorial» ومثال الإضافة والمشغّل الوارد فيها. المصدر مرخّص بموجب CC BY-SA 4.0.