واجهة Godot 4 والثيم: تسليم شجرة Control وقبول التشغيل

واجهة Godot 4 ليست جاهزة عندما تكتفي بوضع صور PNG على عقد TextureRect: فـ StyleBox داخل الثيم والخطوط الافتراضية وسلسلة الحاويات (MarginContainer → HBoxContainer / VBoxContainer) والمراسي / الإزاحات تحدد مجتمعةً ما إذا كان التخطيط يصمد عبر الدقات المختلفة. قد يبدو Auto Layout في Figma مثاليًا بينما لا يزال Play يُظهر أشرطة سفلية منزلقة، أو أزرارًا بحد أدنى صفري، أو نصًا طويلًا مقتطعًا—والسبب عادةً أن شجرة Control أو مورد الثيم لم يطابق مواصفات التسليم.

يركّز ما يلي على Godot 4.x Control + Theme. يمكن لفرق Unity تطبيق القائمة ذاتها عبر قائمة فحص المحرك + MCP. المسار الكامل Figma → Godot: Figma إلى Godot (يصدّر VberAI Studio شجرة Control). تغطي هذه المقالة هيكل HUD فقط: الثيم، تسمية العقد، فحص Play—لا خطوات تثبيت MCP.

معايير الفشل (أي واحد منها = لم يُجتَز): عناصر تحكم HUD الأساسية مقتطعة عند نسبة العرض المستهدفة (بما في ذلك ما يعادل المنطقة الآمنة عبر DisplayServer.get_display_safe_area())؛ عدم تطابق حجم الزر نفسه بين المحرر والبناء المُصدَّر دون مواصفة مكتوبة؛ حالات زر الثيم (عادي / تحويم / مضغوط / معطّل، إلخ) حالات ناقصة شُحنت رغم ذلك؛ تغيّرت شجرة المشهد من أجل لغة واحدة فقط (يتعارض مع i18n بنفس البنية—انظر فيض اللغات)؛ minimum_size غير مضبوط فيبدو خلف لوحة nine-slice جيدًا لكن النص يلتصق بالحواف.

---

الثيم والعقد: ما يجب أن يتوافق معه التسليم

تسليم التصميم	الاستقبال في Godot
ألوان / أنصاف أقطار / لوحات محدودة	StyleBoxFlat / StyleBoxTexture في Theme (هوامش الرقعة حسب nine-slice)
أحجام المتن / العنوان	font_size الافتراضي في الثيم + تنويعات نوع Label إذا لزم
حالات الزر	أربع مجموعات StyleBox على Button: عادي / تحويم / مضغوط / معطّل
أيقونة + نص	TextureRect للأيقونة بـ حد أدنى ثابت؛ Label للنص في حاوية قابلة للتمدد
جذر HUD بملء الشاشة	إعداد مرساة Control للجذر + MarginContainer للمنطقة الآمنة

التسمية: أسماء عقد المشهد تطابق دلالات مكوّنات Figma (HUD_BottomBar، Btn_Shop) لتبقى مسارات MCP / السكربت $ مستقرة (قائمة فحص المحرك + MCP).

---

ترتيب قبول Play (6 خطوات)

1. تثبيت منفذ العرض والمنطقة الآمنة

• اضبط عرض/ارتفاع الأساس المستهدف في Project Settings ← Display (اصطلاح الفريق للوضع الرأسي).
• أدرج هامشًا لجذر HUD عبر DisplayServer.get_display_safe_area() أو عقدة SafeArea في Godot 4.2+؛ افحص هاتفًا طويلًا واحدًا (انظر مقال المنطقة الآمنة).

2. الثيم كمصدر وحيد للحقيقة

• الشجرة الفرعية لـ HUD ترث مورد Theme واحدًا، لا تجاوزات يدوية لكل زر.
• أي عقد تجاوز يجب إدراجها في المواصفة وإلا سيفوتها إعادة التنسيق.

3. سلسلة الحاويات وأعلام الحجم

الفحص	الخطأ الشائع
size_flags_horizontal / vertical	Label يفترض أن يتمدد بلا Fill/Expand ← اقتطاع اللغة
custom_minimum_size	ارتفاع زر = 0 ← هدف لمس صغير جدًا
MarginContainer متداخل	هوامش مزدوجة ← حلقة فراغ إضافية

4. فحص اللغات

• في Localization، بدّل لغات الضغط (DE/ES، إلخ) ولغة الشحن؛ غيّر نص tr() فقط، لا شجرة العقد.
• الفيض ← مسار فيض اللغات (أدنى عرض / نص / إعادة تصدير).

5. الحالات والتركيز

• تركيز لوحة المفاتيح/ذراع التحكم (إن كان مدعومًا): StyleBox focus معرّف في الثيم.
• الأزرار المعطّلة لا تزال تحجب النقرات (mouse_filter، حالة disabled).

6. إعادة اختبار البناء المُصدَّر

• شغّل HUD الرئيسي 30 ثانية في Debug وRelease؛ إذا غيّر احتياطي الخط العرض، أعد الاختبار على الجهاز (عنصر ما قبل الشحن 5 Dev/Release؛ جميع اللغات العنصر 2).

---

مقارنة تقريبية مع Figma Auto Layout

Figma	Godot 4
Auto Layout رأسي	VBoxContainer + فصل
Auto Layout أفقي	HBoxContainer
الحشو	MarginContainer أو هامش محتوى StyleBox
ملء الحاوية	size_flags Expand + Fill
احتواء المحتوى	الأبناء بلا Expand؛ الأب يحتوي

إذا كان VberAI Studio (أو خط أنابيبك) قد صدّر الحاويات بالفعل، اقبل في Play—لا تكتفِ بالنظر إلى إطارات المحرر الثابتة.

---

توجيه الإصلاح

العَرَض	السبب المحتمل	الإجراء	المسؤول
الشريط السفلي تحت النوتش	لا هامش آمن	هامش الجذر + واجهة المنطقة الآمنة	هندسة
لغة واحدة تفيض	أدنى عرض / حجم خط	حد أدنى للثيم أو الحاوية؛ نص ترجمة أقصر	تصميم + هندسة
أنماط خاطئة بعد إعادة التنسيق	تجاوزات متناثرة	توحيد الثيم؛ إعادة تصدير	هندسة + تصميم
خط فاصل nine-slice في StyleBox	هامش رقعة خاطئ	طابق بكسل التصميم؛ انظر مقال nine-slice	هندسة + تصميم
MCP لا يستطيع ربط العقد	الأسماء ≠ التصدير	توحيد التسمية؛ إعادة تصدير Scene/PackedScene	هندسة

---

الأسئلة الشائعة

ثيم واحد لكل شاشة أم واحد للعبة بأكملها؟ النمط الشائع: ثيم عام + theme_override نادر؛ أشكال الأحداث عبر تبديل ثيم إعادة التنسيق، لا تعديلات صبغة لكل عقدة.

هل نمزج Control مع تخطيط CanvasItem الخام؟ أبقِ HUD ثنائي الأبعاد على شجرة Control واحدة؛ لا تخلطه بإحداثيات CanvasLayer الموضوعة يدويًا في نفس HUD.

هل نحتاج نمط تركيز منفصل للوحة المفاتيح/ذراع التحكم؟ إذا كان المشروع يدعم تركيز لوحة المفاتيح/ذراع التحكم، عرّف StyleBox focus على Button وLineEdit وغيرها في الثيم (أو theme_override مرئي)، وافحص Tab/d-pad في Play. يمكن لـ HUD اللمسي فقط أن يحدد لا حاجة لتنسيق التركيز ليشترك QA والهندسة في قائمة واحدة.

كيف يختلف هذا عن قبول Unity Prefab؟ نفس القائمة (اقتطاع، لغات، حالات، Release)؛ بدّل الأسماء إلى StyleBox / size_flags / PackedScene.

هل يجب استخدام Figma؟ لا. بدون Figma لا تزال بحاجة إلى مواصفة الثيم + الحاويات؛ مع Figma، قائمة فحص تسليم التصميم ثم Godot.