ue5coro

UE5Coro

يطبق UE5Coro دعم C++20 coroutine لـ Unreal Engine 5 مع التركيز على منطق اللعب والراحة وتوفير التكامل السلس مع المحرك.

ملحوظة

يتوفر الدعم لـ C++ 17 والمترجمين الأقدم والأنظمة الأساسية وإصدارات المحرك في سلسلة UE5Coro 1.x القديمة.

يوجد دعم مدمج لسهولة تأليف الوظائف الكامنة. قم بتغيير نوع الإرجاع لـ UFUNCTION الكامن لجعله coroutine، وستحصل على كل نموذج FPendingLatentAction مجانًا، مع دعم تعدد مؤشرات الترابط الآمن لـ BP خارج الصندوق:

 UFUNCTION (BlueprintCallable, meta = (Latent, LatentInfo = LatentInfo))
FVoidCoroutine Example(FLatentActionInfo LatentInfo)
{
    UE_LOGFMT (LogTemp, Display, " Started " );
    co_await UE5Coro::Latent::Seconds ( 1 ); // Does not block the game thread!
    UE_LOGFMT (LogTemp, Display, " Done " );
    co_await UE5Coro::Async::MoveToThread (ENamedThreads::AnyThread);
    auto Value = HeavyComputation ();
    co_await UE5Coro::Async::MoveToGameThread ();
    UseComputedValue (Value);
}

سيتتبع هذا الكوروتين كائن UObject المستهدف تلقائيًا عبر الخيوط، لذلك حتى إذا تم تدمير الكائن الخاص به قبل أن ينتهي، فلن يتعطل بسبب تعليق this في خيط اللعبة.

حتى نوع الإرجاع coroutine مخفي عن BP حتى لا يزعج المصممين:

لست مهتما بالوظائف الكامنة؟ ليست مشكلة. يتم أيضًا دعم coroutines Raw C++، مع نفس مجموعة الميزات بالضبط. يتم تحديد تنفيذ الدعم في وقت الترجمة؛ يتم إنشاء الإجراءات الكامنة فقط إذا كنت تستخدمها بالفعل.

قم بتغيير نوع الإرجاع الخاص بك إلى أحد أنواع coroutine التي يوفرها هذا البرنامج الإضافي، والمهام غير المتزامنة المعقدة التي قد يكون من الصعب تنفيذها بنفسك، تصبح مهام بسيطة تافهة تعمل بها Just Work™، مما يلغي الحاجة إلى عمليات الاسترجاعات والمعالجات الأخرى.

• هل تستمتع براحة LoadSynchronous، ولكن ليس عيوبه؟
  UObject* HardPtr = co_await AsyncLoadObject(SoftPtr); يتيح لك الاحتفاظ بالمزايا فقط (وإطار FPS الخاص بك).
• ماذا عن نشر عملية حسابية ثقيلة عبر عدة علامات؟
  أضف co_await NextTick(); داخل حلقة، وقد انتهيت بالفعل. هناك فئة ميزانية زمنية تتيح لك تحديد وقت المعالجة المطلوب مباشرةً، والسماح للكوروتين بجدولة نفسه ديناميكيًا.
• عند الحديث عن الجدولة الديناميكية، يمكن أن يكون الاختناق بهذه البساطة:
  co_await Ticks(bCloseToCamera ? 1 : 2);
• لماذا تقطع الوقت في سلسلة اللعبة عندما يكون لديك العديد من مراكز وحدة المعالجة المركزية المتشوقة للعمل؟
  أضف co_await MoveToTask(); إلى وظيفتك، وسيتم تشغيل كل شيء بعد هذا السطر داخل نظام UE::Tasks على مؤشر ترابط عامل.
  
• هل تريد العودة؟ إنه co_await MoveToGameThread(); .
  أنت حر في التنقل بشكل تعسفي بين المواضيع، وتنتقل coroutines UFUNCTION الكامنة تلقائيًا إلى سلسلة اللعبة عند الانتهاء لاستئناف BP.
• لا تزال غير مقتنع؟ إليك كيفية تشغيل مخطط زمني كامل:
  co_await Timeline(this, From, To, Duration, YourUpdateLambdaGoesHere);
• من الصعب إرضائك؟ إليك كيفية الانتظار بشكل غير متزامن لمفوض DYNAMIC دون كتابة UFUNCTION فقط لـ AddDynamic/BindDynamic، أو التواجد في UCLASS، أو أي فصل دراسي على الإطلاق:
  co_await YourDynamicDelegate; (هذا هو الكود بأكمله)
• أوه، أردت المعلمات مع هذا المندوب؟
  auto [Your, Parameters] = co_await YourDynamicDelegate;

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

قل وداعًا لجهاز LoadSynchronous الجيد بما يكفي الآن والذي لا يزال قيد الشحن، بعد تحديثين. مع تقليل المهمة المطروحة من "كتابة كل نموذج StreamableManager ونقل جزء من وظيفة الاتصال إلى رد اتصال" إلى مجرد "التمسك بالانتظار أمامها"، ستنتهي بشكل أسرع مما قد يستغرقه الأمر للظهور مع تبرير سبب قبول إصدار الحظر المتزامن إلى حد ما.

هناك الكثير من الميزات الإضافية في البرنامج المساعد، مثل المولدات التي تتيح لك تجنب تخصيص TArray بالكامل فقط لإرجاع عدد متغير من القيم. من الأسهل عليك الكتابة، ومن الأسهل على المترجم تحسينه، فأنت تحتاج فقط إلى تخزين O(1) بدلاً من O(N) للعناصر N، ما الذي لا يعجبك؟

قائمة الميزات

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

التأليف كوروتين

تركز هذه الميزات على تعريض الكوروتين لبقية المحرك.

• كوروتين (من الواضح)
  • دعم الإلغاء له صفحته الخاصة.
• مولدات
• يعمل تكامل نظام القدرة على اللعب بشكل مختلف قليلاً.

التكامل غير الحقيقي

توفر هذه الأغلفة طرقًا ملائمة لاستهلاك ميزات المحرك من كوروتيناتك.

• تكامل الذكاء الاصطناعي (MoveTo، Pathfinding...)
• انتظار الرسوم المتحركة (المونتاج، الإخطارات...)
• أجهزة انتظار غير متزامنة (تعدد مؤشرات الترابط، المزامنة...)
• HTTP (طلبات HTTP غير المتزامنة)
• المنتظرون الضمنيون (بعض أنواع المحركات تكون في انتظارهم بشكل مباشر، بدون أغلفة)
• المنتظرون الكامنون (تفاعل خيط اللعبة، التأخير...)
  • تحميل الأصول (تحميل غير متزامن للمؤشرات الناعمة والحزم...)
  • استعلامات التصادم غير المتزامنة (تتبعات الأسطر، عمليات التحقق من التداخل...)
  • السلسلة الكامنة (مجمع الفعل الكامن العالمي)
  • ميزانية وقت التجزئة (تشغيل لمدة x مللي ثانية لكل إطار)
• عمليات الاسترجاعات الكامنة (التفاعل مع مدير الإجراءات الكامنة)

ملحوظة

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

في أغلب الأحيان، هذه ليست مشكلة: على سبيل المثال، الكائن المؤقت غير المسمى في co_await Something() لا يظهر في التعليمات البرمجية المصدر. إذا كانت هناك حاجة إلى تخزين قيمة إرجاع Private ، فاستخدم auto (أو TAwaitable auto المقيدة ) لتجنب كتابة اسم النوع.

إن الاتصال المباشر بالوظائف المنتظرة C++ العامة حسب الضرورة await_ready و await_suspend و await_resume غير مدعوم في أي انتظار.

ميزات إضافية

• المنتظرون المجمعون (WhenAny، WhenAll، Race...)
• الجداول الزمنية الكامنة (استيفاء سلس على القراد)
• خيوط الأوليات (الإشارات والأحداث ...)

تثبيت

يتم دعم الإصدارات المرقمة فقط. لا تستخدم فروع Git مباشرة.

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

ملحوظة

يرجى الرجوع إلى الملف التمهيدي الخاص بالإصدار إذا كنت تستخدم الإصدار 1.x. كان لديه طريقة مختلفة للتثبيت تتضمن مكونات إضافية متعددة.

إعداد المشروع

قد يستخدم مشروعك بعض الإعدادات القديمة التي تحتاج إلى إزالتها لفتح دعم C++20، والتي تأتي بشكل قياسي في المشاريع الجديدة التي تم إنشاؤها في Unreal Engine 5.3 أو الإصدارات الأحدث.

في ملفات Target.cs (جميعها)، تأكد من أنك تستخدم أحدث الإعدادات وتضمين إصدار الطلب:

 DefaultBuildSettings = BuildSettingsVersion . Latest ;
IncludeOrderVersion = EngineIncludeOrderVersion . Latest ;

إذا كنت تستخدم علامة bEnableCppCoroutinesForEvaluation القديمة، فلن تكون هناك حاجة لذلك بعد الآن، ولا ينبغي تشغيلها بشكل صريح بعد الآن؛ القيام بذلك قد يسبب مشاكل. يوصى بإزالة كافة الإشارات إليه من ملفات البناء الخاصة بك.

إذا كنت تقوم بتعيين CppStandard على CppStandardVersion.Cpp17 في ملف Build.cs... فلا تفعل ذلك :)

الاستخدام

قم بالإشارة إلى وحدة "UE5Coro" من Build.cs الخاص بك كما تفعل مع أي وحدة C++ أخرى، واستخدم #include "UE5Coro.h" . لا يلزم تمكين البرنامج المساعد نفسه.

توجد بعض الوظائف في وحدات اختيارية تحتاج إلى الرجوع إليها بشكل منفصل. على سبيل المثال، يحتاج دعم نظام إمكانية اللعب "UE5CoroGAS" في Build.cs، و #include "UE5CoroGAS.h" . تعتمد وحدة UE5Coro الأساسية فقط على وحدات المحرك التي يتم تمكينها افتراضيًا.

مهم

لا تقم بتضمين أي رأس آخر بشكل مباشر، فقط الذي يطابق اسم الوحدة. من المعروف أن IDEs الرئيسية المستخدمة مع Unreal Engine تخطئ في اقتراحات الرأس. إذا قمت بإضافة UE5Coro.h إلى PCH الخاص بك، فيمكنك إتاحته في كل مكان.

التحديثات

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

التعبئة والتغليف

ليست هناك حاجة إلى تعبئة UE5Coro بشكل منفصل (من نافذة المكونات الإضافية)، وهو غير مدعوم.

إزالة

لإزالة المكون الإضافي من مشروعك، أعد تنفيذ جميع العناصر الأساسية الخاصة بك دون وظائفها، وأزل جميع المراجع إلى المكون الإضافي ووحداته، وأضف إعادة توجيه أساسية من /Script/UE5CoroK2.K2Node_UE5CoroCallCoroutine إلى /Script/BlueprintGraph.K2Node_CallFunction .