المحرر يعمل، البناء يفشل: تتبع أخطاء الكونسول إلى مراجع البرامج النصية والمشاهد باستخدام Unity MCP

المواضيع التي تحمل عنوان “Unity يعمل في المحرر، يفشل على الجهاز / البناء” تبدو متشابهة: Play يعمل بشكل جيد، ثم بناء Player / الجهاز يتحول إلى الأحمر، ينهار، يتحول إلى شاشة سوداء، أو يرمي NullReferenceException عند دخول المشهد. نادرًا ما يكون المحرك “مكسورًا”—مسار المحرر أخفى فجوات المرجع والمنصة: مشهد غير موجود في قائمة البناء، حقول متسلسلة تكون None على القرص، حساسية حالة المسار، أو واجهات برمجة تطبيقات UnityEditor تسربت إلى تجميع وقت التشغيل حتى وقت التعبئة.

هذا المنشور له ثلاثة محاور (كما في العنوان):

1. الكونسول / المكدس ← كائنات البرنامج النصي والمشهد
2. تحقق من إعدادات البناء، البرنامج النصي المفقود، المراجع المتسلسلة
3. تشخيص للقراءة فقط في Cursor عبر Unity MCP ← إصلاح بسيط بعد التأكيد

لا يوجد دليل تثبيت إضافات، ولا دليل كامل لنشر المتجر. يبقى تجريد IL2CPP والإضافات الأصلية في الملحق.

ذات صلة:

• تثبيت Unity MCP
• Unity MCP مع Claude Code وCursor
• ربط HUD استوديو AI بأحداث الصحة (الربط الصحيح؛ هذا المنشور هو “كيف تجد الكسر”)

أولاً: أي طبقة فشلت؟

A. نافذة البناء حمراء (فشل التجميع / التعبئة)
        ↓
B. البناء ينجح؛ الجهاز يموت أو يتحول إلى شاشة سوداء عند الإطلاق
        ↓
C. تبدأ اللعبة؛ مشهد أو ميزة تنفجر في وقت التشغيل

ما تراه	الطبقة	تحقق أولاً هنا
فشل البناء، error CS… / نوع غير موجود	A	تجميع وقت التشغيل يشير إلى UnityEditor، #if خاطئ، asmdef
NRE / MissingReference في مشهد الإقلاع	B/C	المشهد في قائمة البناء، برنامج نصي مفقود، None في المفتش
يفشل فقط عند Resources.Load / مشهد إضافي	C	حالة المسار، الأصل في الحزمة، المشهد محمّل فعليًا

Unity MCP هو الأقوى على محرر مفتوح: الكونسول، التسلسل الهرمي، حقول المكونات. يجب لصق مكدسات logcat / Xcode للجهاز في Cursor—أو شحن Development Build وإعادة إنتاج نفس مشهد الإقلاع في المحرر عندما يمكنك ذلك.

حلقة استكشاف الأخطاء وإصلاحها (يدوي + MCP)

لا تخطِ الممر اليدوي وتطلب من الذكاء الاصطناعي إعادة كتابة Player.

الخطوة 0: تجميد المشهد يدويًا (~دقيقتان)

قبل Cursor:

1. لاحظ إصدار Unity والهدف (مثل Android / IL2CPP)
2. امسح Window → General → Console، ثم قم ببناء أو Development Build مرة واحدة
3. انسخ أول خطأ ذي صلة (مع المكدس)—وليس جدار تحذيرات
4. افتح File → Build Settings: هل المشهد المشتبه به محدد؟ هل index 0 هو مشهد الإقلاع؟
5. إذا قمت بتحرير مثيل Prefab: هل قمت بـ Apply؟ غالبًا لا تصل التجاوزات غير المطبقة إلى أصل القرص الذي تعتقد أنك شحنته

الخطوة 1: فرز الكونسول للقراءة فقط عبر MCP

لخص أخطاء الكونسول المتعلقة بهذا البناء / آخر Play (تجاهل Info).
صنّفها كفشل تجميع / برنامج نصي مفقود / NullReference / تحميل موارد.
اسرد مسار البرنامج النصي، السطر، اسم GameObject لكل خطأ عند وجوده.
لا تعدّل أي أصول.

الخطوة 2: “ثلاثي المرجع” اليدوي + MCP

لأخطاء NRE في وقت التشغيل (B/C)، حدد كائن المكدس في المحرر وتحقق منه مع MCP:

يدوي	موجه MCP
قائمة Build Settings (لقطة شاشة أو إملاء)	“اسرد مسارات مشاهد Build Settings وأعلام التمكين؛ سمِّ مشهد الإقلاع.”
المفتش: برنامج نصي مفقود / مراجع None	”في المشهد <Name>، اسرد البرامج النصية المفقودة؛ تحقق من الحقول المتسلسلة على <Object>.<Component> بحثًا عن None. جدول فقط. لا تعدّل.”
أصل Prefab مقابل مثيل المشهد	”هل <X> أصل Prefab أم مثيل مشهد؟ أي تجاوزات غير مطبقة إذا كانت مرئية؟ أبلغ فقط.”

القاعدة: تستخدم الحزم مشاهد/Prefabs على القرص. لا تعتبر تعبئات OnValidate المؤقتة التي “تبدو جيدة” في المحرر—ثق بالقيم المتسلسلة من MCP/المفتش.

الخطوة 3: قالب التشخيص، ثم التأكيد

[القيود]
- شخّص واقترح خطة بسيطة؛ انتظر موافقتي قبل التعديل
- لا تزيّف إصلاحًا بـ GameObject.Find الجماعي
- المس فقط البرامج النصية/Prefabs/المشاهد المرتبطة بهذا الخطأ

[المشهد]
- Play في المحرر: جيد / مكسور (بصدق)
- المنصة / البناء: …
- مشهد إقلاع Build Settings: …
- الكونسول / مكدس الجهاز (خام):
<paste>

[الإجابة]
1. الطبقة A / B / C
2. أعلى 1–2 أسباب جذرية (ليس في البناء / مرجع None / برنامج نصي مفقود / حالة / واجهة برمجة تطبيقات المحرر…)
3. الكائنات وأسماء الحقول التي يجب أن أتحقق منها
4. خطوات الإصلاح البسيطة (لا تنفذ بعد)

الخطوة 4: كتابة بسيطة + إعادة التحقق

طبق الإصلاح البسيط المؤكد: فقط <object.field> أو الأسطر القليلة في <script path> لهذا الخطأ.
احفظ المشهد/Prefab.
ثم أعد التحقق للقراءة فقط: هل الحقول لا تزال None؟ هل نفس الخطأ لا يزال في الكونسول؟

مثال عملي: المكدس ← الحقل

سجل Player/جهاز اصطناعي لكن واقعي (استبدل المسارات بمشروعك).

السجل

NullReferenceException: Object reference not set to an instance of an object
  at HudHealthView.HandleHealthChanged (System.Single current, System.Single max) [0x00000] in Assets/Scripts/UI/HudHealthView.cs:42
  at PlayerHealth.TakeDamage (System.Single amount) [0x00000] in Assets/Scripts/Combat/PlayerHealth.cs:28
  at DebugDealDamage.Update () [0x00000] in Assets/Scripts/Debug/DebugDealDamage.cs:15

الطبقة

• وصل إلى Update → ليس A (التجميع جيد)
• يموت عند الضرر → C (وقت التشغيل)؛ اشتبه في مراجع UI، وليس “إعادة كتابة القتال”

يدوي

1. هل مشهد HUD في Build Settings؟
2. حدد كائن HudHealthView؛ هل healthFill / playerHealth None؟
3. تعديلات Prefab: هل تم تطبيقها؟

MCP

للقراءة فقط: افتح المشهد الذي يحتوي على HUD.
1. ابحث عن الكائنات التي تحتوي على HudHealthView
2. أبلغ ما إذا كانت healthFill وplayerHealth (والنظراء) None / مفقودة
3. لا تعدّل
إذا كانت None: الخطة البسيطة هي إعادة تعيين المراجع وحفظها—وليس تغيير TakeDamage.

الإصلاح البسيط (بعد الموافقة)

• اسحب صورة HUD_HealthFill إلى healthFill؛ وPlayerHealth للاعب إلى playerHealth
• احفظ؛ Development Build؛ خذ ضررًا مرة أخرى

”إصلاح” سيء (لا تفعل)

// نمط مضاد: Find يخفي None—لا يزال ينكسر عند إعادة التسمية / التحميل الإضافي
healthFill = GameObject.Find("HUD_HealthFill").GetComponent<Image>();

الربط الصحيح: HUD ← أحداث الصحة. هنا: ثبّت الحقل من المكدس، ثم أعد الربط.

مصفوفة الأعراض (المحور)

العرض 1: البناء أحمر—نوع غير موجود / UnityEditor

السبب المحتمل	يدوي	MCP
برنامج نصي وقت التشغيل يستخدم واجهة برمجة تطبيقات المحرر	هل الملف خارج Editor/؟	“ابحث عن UnityEditor. خارج مجلدات Editor؛ اسرد المسارات فقط.”
#if مقلوب، أنواع Player مفقودة	تحقق من أن UNITY_EDITOR يحيط	”ما الأنواع الموجودة تحت Editor مقابل Player لهذا الملف؟“
فجوة asmdef	افتح .asmdef الفاشل	”اسرد مراجع asmdef؛ أي واحد مفقود؟”

نمط مضاد (واجهة برمجة تطبيقات المحرر في تجميع وقت التشغيل ← فشل بناء Player):

using UnityEngine;
using UnityEditor; // يفشل البناء إذا لم يكن تجميع محرر

public class BadBake : MonoBehaviour
{
    [MenuItem("Tools/Bad")] // اعتماد إضافي على UnityEditor
    static void Run() { }
}

الإصلاح أ: الملف بأكمله تحت Editor/

Assets/Scripts/Editor/BakeTools.cs   ← تجميع محرر فقط

الإصلاح ب: عزل داخل الملف (فقط إذا كان يجب مشاركة ملف)

using UnityEngine;

public class RuntimeSafe : MonoBehaviour
{
    public void DoGameplay() { /* مرئي للاعب */ }

#if UNITY_EDITOR
    [ContextMenu("Debug/Fill Refs")]
    void EditorOnlyFill()
    {
        // محرر فقط—لا تعامل هذا كبيانات وقت تشغيل معبأة من Awake
    }
#endif
}

أنظف أيضًا: برامج نصية للمحرر فقط + asmdef حتى لا تسحب تجميعات وقت التشغيل مراجع المحرر أبدًا.

العرض 2: NRE على الجهاز عند دخول المشهد؛ Play في المحرر “يبدو جيدًا”

تحقق بالترتيب—لا إعادة كتابة ضخمة متوازية:

1. المشهد غير موجود في Build Settings أو مشهد إقلاع خاطئ
2. برنامج نصي مفقود / None متسلسل (بما في ذلك Prefab غير مطبق)
3. المشهد الإضافي غير محمّل قبل Find / الوصول
4. حالة مسار Resources.Load (محرر macOS غالبًا غير حساس لحالة الأحرف؛ Android ليس كذلك)

1. أبلغ عن مشاهد Build Settings، أعلام التمكين، فهرس الإقلاع
2. اسرد جميع البرامج النصية المفقودة في المشهد <X>
3. تحقق من المراجع العامة على GameManager / Player / HUD على طول مسار الإقلاع بحثًا عن None
أبلغ فقط؛ لا تعدّل.

في المحرر	في الحزمة	السبب النموذجي
المراجع تبدو مضبوطة	None في وقت التشغيل	تجاوزات مثيل غير مطبقة؛ ملف مشهد خاطئ تم تحريره
Find يعمل	null على الجهاز	كائن في مشهد غير محمّل؛ اسم غير مطابق
Resources.Load يعمل	null على الجهاز	حالة المسار؛ الأصل ليس تحت Resources/

// على القرص: Assets/Resources/UI/HealthBar.png
// غالبًا يفشل على Android (عدم تطابق الحالة):
Resources.Load<Sprite>("ui/healthbar");
// طابق المسار تحت Resources، مثل:
Resources.Load<Sprite>("UI/HealthBar");

ابحث عن سلاسل مسار Resources.Load / Addressables.LoadAssetAsync؛
أنشئ جدولًا حساسًا لحالة الأحرف مقابل المسارات النسبية الفعلية. لا تعدّل الكود بعد.

العرض 3: الكونسول مليء بالبرامج النصية المفقودة

افحص المشهد <X> وPrefab <path>:
اسرد مسارات GameObject مع البرامج النصية المفقودة.
لكل عنصر: اقترح إعادة إرفاق البرنامج النصي الأصلي أو إزالة المكون الفارغ (من الاسم/GUID المتبقي إذا كان مرئيًا).
لا تحذف تلقائيًا بشكل جماعي.

يدوي: تأكد من أن ملف البرنامج النصي لا يزال موجودًا وأن asmdef/GUID لم ينكسر؛ أكد واحدًا تلو الآخر قبل حذف الفارغ.

قائمة التحقق للقبول

1. اختفت الأخطاء المطابقة من الكونسول
2. Play في المحرر يسير في نفس المسار الفاشل (ادخل المستوى، خذ ضررًا، افتح UI…)
3. Development Build واحد إلى الهدف (أو Player محلي)
4. إعادة تحقق للقراءة فقط عبر MCP: الحقول المشتبه بها لم تعد None / مفقودة
5. فرق Git هو فقط التغيير الصغير المتوقع في المشهد/Prefab/البرنامج النصي—لا إعادة هيكلة عابرة

إعادة تحقق للقراءة فقط: أي None أو برنامج نصي مفقود على <قائمة الكائنات>؟ اسرد الاستثناءات. لا تعدّل.

الخطوط الحمراء للموجه

لا تفعل	افعل
”فقط اجعل Play يعمل”	الطبقة A/B/C + ثبّت الحقل من المكدس
Find جماعي بدلاً من المراجع	أصلح الحقول المتسلسلة أو الحقن الصريح
أعد ترتيب Build Settings دون سؤال	أبلغ عن القائمة الحالية ومشهد الإقلاع أولاً
”هناك NRE”	الصق أول 20–40 سطرًا من المكدس

حدود المنتج

• Unity MCP: كونسول المحرر، التسلسل الهرمي، البرامج النصية، المراجع—محور هذه المقالة.
• AI Studio: بنية UI في المحرك؛ أعد الربط بعد إعادة التصدير وفقًا لمنشور الربط—لا تجد UI من أسلوب اللعب.
• الشهادات، المتاجر، ROMs الخاصة بالمصنعين: الصق نص السجل في Cursor للمساعدة في القراءة؛ خارج نطاق تحرير مشهد MCP.

الملحق: شائع لكن خارج المحور

استبعد محور هذه المقالة أولاً:

العرض	الاتجاه
Development جيد، Release يموت	تجريد مُدار / link.xml؛ MCP: “خمّن الأنواع المجردة من مكدس الانهيار؛ اقترح link.xml؛ لا تكتب ملفات بعد.”
انهيار أصلي على Android (غير مُدار)	.so / الأذونات / Gradle؛ الصق logcat للقراءة
واجهة برمجة تطبيقات Unity خارج الخيط الرئيسي	تحقق من عودة استدعاءات async إلى الخيط الرئيسي

لا تدمج التجريد والبرنامج النصي المفقود في “إعادة كتابة كبيرة” واحدة.

الملخص

1. المحرر جيد / الحزمة مكسورة ← تعامل مع المراجع / المشاهد في البناء / المسارات / واجهة برمجة تطبيقات المحرر أولاً
2. تجميد يدوي لإعدادات البناء والخطأ الأول، ثم فرز للقراءة فقط عبر MCP
3. المكدس ← سطر البرنامج النصي ← حقل المكون؛ أعد الربط أو أزل المكونات الفارغة بعد التأكيد
4. لا Find أو إعادة كتابة أسلوب اللعب كإصلاحات مزيفة
5. اقبل مع Development Build + إعادة تحقق للقراءة فقط

نفذ “تجميد ← طبقة ← ثلاثي المرجع ← ثبّت الحقل مثل العينة” وستتقلص معظم أخطاء مرجع الجهاز إلى فرق صغير قابل للمراجعة.