عن المشروع

# helengine helengine هو مساحة عمل مشتركة للمحرك والمحرر تبني حزم المنصات من ملفات المشروع `.heproj`. وهو مصمم لاستهداف أجهزة محدودة الموارد (مثل وحدات التحكم الريترو مثل DS وPS2) مع استخدام خطوط أصول وأدوات حديثة. ## عمليات بناء منصة واجهة سطر أوامر المحرر يتم تنسيق عمليات بناء المنصات عبر سكربت غلاف PowerShell باسم `scripts/build-platform.ps1`، والذي يستعيد وينشر واجهة سطر أوامر المحرر، ثم يبني المشروع المؤلف مباشرة. مثال على الاستخدام: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File C:\dev\helworks\helengine\scripts\build-platform.ps1 ` -Project C:\dev\helprojs\city\project.heproj ` -Platform ds ` -Output C:\dev\helprojs\city\ds-build ` -BuildProfile release ` -CacheRoot D:\helengine-cache ``` تشمل المعاملات الرئيسية `-Project` (مسار `.heproj`)، و`-Platform` (كما هو معلن في `settings/platforms.json` الخاص بالمشروع)، و`-Output` (دليل الإخراج)، و`-BuildProfile` (مثل `debug` أو `release`)، و`-CacheRoot` (موقع ذاكرة تخزين مؤقت قابلة لإعادة الاستخدام)، و`-LockTimeout`، و`-Clean`، و`-PruneCacheOlderThanDays`، و`-AdditionalArgs` لوسائط إضافية لواجهة سطر أوامر المحرر. يدعم الغلاف أيضًا انتظار البناء حتى اكتماله بشكل موثّق. ## أوضاع الوحدات والبناء يستخدم كود المشروع تعريفات `code.module.json`. تعتمد وحدات وقت التشغيل فقط على وحدات وقت التشغيل؛ أما الوحدات الخاصة بالمحرر فقط فتستخدم `"moduleKind": "editor"` ويمكنها الاعتماد على وحدات وقت التشغيل. يجب تسمية مجلدات الاختبارات `<module-id>.tests` ويجب أن تطابق وحدة إنتاج معلنة. تستخدم جلسات المحرر التفاعلية وأوامر المحرر `EditorFull` (يشمل وحدات وقت التشغيل + وحدات المحرر + الاختبارات)، بينما تستخدم عمليات بناء المنصات `RuntimeOnly` (تستبعد الاختبارات/أوامر المحرر). يمكن لملفات تعريف بناء المنصة الإعلان عن أوامر ما قبل البناء المرتبة عبر `editorPrebuildCommandIdsByBuildProfileId`. ## عقد الذاكرة المؤقتة والاستدعاء تستخدم الذاكرة المؤقتة القابلة لإعادة الاستخدام `v2` هوية حتمية مشتقة من مسار المشروع القانوني ونسخة المحرر. يتم تسلسل عمليات البناء لكل مشروع عبر قفل المشروع ولكل إخراج عبر قفل الإخراج؛ يمكن للمشاريع المختلفة أن تتداخل فقط إذا استخدمت مخرجات مختلفة. لا ينسخ الغلاف المشروع؛ بل يبني في المكان ويحتفظ بالملفات الوسيطة في الذاكرة المؤقتة. `HELENGINE_BUILD_INVOCATION_ID` هو GUID ارتباط داخلي، وليس إعدادًا للمستخدم. تصف رموز الخروج (`0`، `2`، `3`، `4`، `5`، `6`، `10`) حالات فشل الغلاف والتحقق؛ قد تتزامن رموز خروج العمليات الفرعية، لذا يجب على المستدعين فحص التشخيصات و`.helengine-build-state.json`. ## توليد الكود توليد الكود من C# إلى C++ هو وحدة فرعية git في `engine/vendor/csharpcodegen`، مثبتة بواسطة commit المحرك. ينشره سكربت البناء في دليل `codegen/` بجانب المحرر، ويُستخدم لعمليات بناء المنصات. لم تعد إدخالات المنصة تحمل `codegenToolPath`؛ يتم تجاهل التذكيرات مع تحذير. بعد الاستنساخ أو تبديل الفرع، شغّل `git submodule update --init --recursive`. ## انتظار البناء الموثّق ينتظر `tools/build-waiter` اكتمال البناء بنجاح عبر التقاط رمز الخروج، وملف `.helengine-build-state.json` الحالي، وحداثة العناصر المطلوبة (مثل `game.iso`، `disc/SYSTEM.CNF`). ويتنسق مع الغلاف عبر مرحلة إقرار. في الاستدعاءات التي يتحكم بها المنتظر، يفشل الغلاف برمز الخروج `10` بعد 30 ثانية إذا كان الإقرار مفقودًا. مثال على بناء PS2: ```powershell dotnet run --project ...\helengine.buildwaiter.csproj -- ` --output ...\output\ps2 ` --require game.iso ` --require disc/SYSTEM.CNF ` --require disc/HELENGIN.ELF ` -- powershell ... -File ...\build-platform.ps1 -Project ... -Platform ps2 -Output ... ``` ## اختبار دخان الذاكرة المؤقتة المستقرة الأصلية يتطلب اختبار دخان أصلي على Windows (`scripts/tests/build-platform-native-cache-smoke.tests.ps1`) مصدر المنصة الشقيق الخارجي، وأدوات Visual Studio C++، وCMake، وNinja، وباني Windows. يبني تركيبة صغيرة مرتين بنفس الذاكرة المؤقتة، متوقعًا `helengine_windows.exe` غير فارغ وملف حالة بناء حديثًا. شغّله صراحةً؛ فهو ليس ضمن المجموعة الافتراضية.