ue5coro

UE5Coro

UE5Coro ใช้การสนับสนุน Coroutine C++20 สำหรับ Unreal Engine 5 โดยมุ่งเน้นไปที่ตรรกะในการเล่นเกม ความสะดวกสบาย และการผสานรวมกับกลไกได้อย่างราบรื่น

บันทึก

การรองรับ C++17, คอมไพเลอร์, แพลตฟอร์ม และเวอร์ชันกลไกรุ่นเก่านั้นมีอยู่ในซีรีส์ UE5Coro 1.x รุ่นเก่า

มีการสนับสนุนในตัวสำหรับการเขียน UFUNCTION ที่แฝงอยู่ได้ง่าย เปลี่ยนประเภทการส่งคืนของ 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 เพื่อไม่ให้รบกวนนักออกแบบ:

ไม่สนใจ UFUNCTION ที่แฝงอยู่ใช่ไหม ไม่ใช่ปัญหา. นอกจากนี้ยังรองรับ Coroutines แบบ Raw C++ ด้วยชุดฟีเจอร์เดียวกันทุกประการ การใช้งานการสำรองข้อมูลถูกเลือกในเวลาคอมไพล์ การดำเนินการแฝงจะถูกสร้างขึ้นเฉพาะเมื่อคุณใช้งานจริงเท่านั้น

เปลี่ยนประเภทการส่งคืนของคุณเป็นประเภท Coroutine ประเภทใดประเภทหนึ่งที่ปลั๊กอินนี้ให้มา และงานอะซิงโครนัสที่ซับซ้อนซึ่งอาจยุ่งยากในการนำไปใช้ให้กลายเป็นเรื่องไม่สำคัญที่ Just Work™ ขจัดความจำเป็นในการเรียกกลับและตัวจัดการอื่น ๆ

• เพลิดเพลินกับความสะดวกสบายของ LoadSynchronous แต่ไม่มีข้อเสียใช่ไหม
  UObject* HardPtr = co_await AsyncLoadObject(SoftPtr); ให้คุณเก็บเฉพาะผลประโยชน์ (และ FPS ของคุณ)
• แล้วการกระจายการคำนวณจำนวนมากไปยังหลายขีดล่ะ?
  เพิ่ม co_await NextTick(); อยู่ในลูป และคุณก็ทำเสร็จแล้ว มีคลาสงบประมาณเวลาที่ให้คุณระบุเวลาการประมวลผลที่ต้องการได้โดยตรง และปล่อยให้ Coroutine กำหนดเวลาแบบไดนามิกเอง
• เมื่อพูดถึงการจัดกำหนดการแบบไดนามิก การควบคุมปริมาณอาจทำได้ง่ายๆ ดังนี้:
  co_await Ticks(bCloseToCamera ? 1 : 2);
• เหตุใดจึงต้องแบ่งเวลาบนเธรดเกมเมื่อคุณมีคอร์ CPU หลายตัวที่กระตือรือร้นที่จะทำงาน?
  เพิ่ม co_await MoveToTask(); ไปยังฟังก์ชันของคุณ และทุกอย่างหลังจากนั้นบรรทัดนั้นจะทำงานภายในระบบ UE::Tasks บนเธรดของผู้ปฏิบัติงาน
  
• อยากกลับไปไหม? มัน co_await MoveToGameThread(); -
  คุณมีอิสระที่จะย้ายไปมาระหว่างเธรดต่างๆ โดยพลการ และคอร์รูทีน 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™ ที่ดีพอสำหรับตอนนี้ที่ยังอยู่ใน Shipping การอัปเดตสองรายการในภายหลัง เมื่องานในมือลดลงจาก "เขียน StreamableManager สำเร็จรูปทั้งหมดและย้ายส่วนหนึ่งของฟังก์ชันการโทรไปเป็นการโทรกลับ" เหลือเพียง "ติด co_await ไว้ข้างหน้า" คุณจะเสร็จเร็วกว่าที่คิดไว้ โดยให้เหตุผลว่าเหตุใดเวอร์ชันการบล็อกแบบซิงโครนัสจึงเป็นที่ยอมรับได้

มีคุณสมบัติเพิ่มเติมมากมายในปลั๊กอิน เช่น ตัวสร้างที่ช่วยให้คุณหลีกเลี่ยงการจัดสรร TArray ทั้งหมดเพียงเพื่อส่งคืนค่าจำนวนตัวแปร ง่ายกว่าสำหรับคุณในการเขียน คอมไพเลอร์ปรับแต่งได้ง่ายขึ้น คุณต้องการเพียงพื้นที่เก็บข้อมูล O(1) แทนที่จะเป็น O(N) สำหรับรายการ N อะไรที่ไม่ชอบ

รายการคุณสมบัติ

ลิงก์ต่อไปนี้จะนำคุณไปยังหน้าที่เกี่ยวข้องของเอกสารประกอบ คั่นหน้าส่วนนี้หากคุณต้องการอ่านเอกสารล่าสุดในเบราว์เซอร์ของคุณ หรืออ่านโดยตรงจาก IDE ของคุณ ฟังก์ชัน API ทุกฟังก์ชันได้รับการบันทึกไว้ในส่วนหัวของ C++ และการเผยแพร่จะมีแหล่งที่มาของ Markdown ของเอกสารที่คุณกำลังอ่านอยู่ในขณะนี้

การเขียน Coroutine

คุณสมบัติเหล่านี้มุ่งเน้นไปที่การเปิดเผยคอร์รูทีนไปยังส่วนอื่นๆ ของเครื่องยนต์

• โครูทีน (ชัด)
  • การสนับสนุนการยกเลิกมีหน้าของตัวเอง
• เครื่องกำเนิดไฟฟ้า
• การรวมระบบความสามารถในการเล่นเกมทำงานแตกต่างออกไปเล็กน้อย

การบูรณาการที่ไม่เป็นจริง

กระดาษห่อเหล่านี้ให้วิธีที่สะดวกในการใช้คุณลักษณะของเครื่องยนต์จากโครูทีนของคุณ

• การบูรณาการ AI (MoveTo, การค้นหาเส้นทาง...)
• แอนิเมชั่นรออยู่ (ตัดต่อ แจ้งเตือน...)
• ตัวรอ Async (มัลติเธรด การซิงโครไนซ์...)
• HTTP (คำขอ HTTP แบบอะซิงโครนัส)
• ตัวรอโดยนัย (เอ็นจิ้นบางประเภทสามารถรอร่วมได้โดยตรง โดยไม่มีตัวหุ้ม)
• ตัวรอแฝง (การโต้ตอบของเธรดเกม ดีเลย์...)
  • การโหลดเนื้อหา (การโหลดซอฟต์พอยน์เตอร์แบบ async, การรวมกลุ่ม...)
  • ข้อความค้นหาการชนกันของ Async (การติดตามบรรทัด การตรวจสอบที่ทับซ้อนกัน...)
  • สายโซ่แฝง (เครื่องห่อหุ้มแอคชั่นแฝงสากล)
  • ทำเครื่องหมายงบประมาณเวลา (เรียกใช้ x ms ต่อเฟรม)
• การโทรกลับแบบแฝง (การโต้ตอบกับผู้จัดการการดำเนินการแบบแฝง)

บันทึก

ฟังก์ชันเหล่านี้ส่วนใหญ่จะส่งคืนประเภทภายในที่ไม่มีเอกสารจาก UE5Coro::Private เนมสเปซ รหัสไคลเอ็นต์ไม่ควรอ้างอิงถึงสิ่งใดๆ จากเนมสเปซนี้โดยตรง เนื่องจากทุกสิ่งภายในอาจมีการเปลี่ยนแปลงในเวอร์ชันต่อๆ ไป โดยไม่มี การเลิกใช้งานล่วงหน้า

โดยส่วนใหญ่ นี่ไม่ใช่ปัญหา ตัวอย่างเช่น อ็อบเจ็กต์ชั่วคราวที่ไม่มีชื่อใน co_await Something() ไม่ปรากฏในซอร์สโค้ด หากจำเป็นต้องจัดเก็บค่าส่งคืน Private ให้ใช้ auto (หรือ TAwaitable auto ที่มีข้อจำกัด) เพื่อหลีกเลี่ยงการเขียนชื่อประเภท

การเรียกฟังก์ชัน awaitable สาธารณะตามความจำเป็นโดยตรง await_ready , await_suspend และ await_resume ไม่ได้รับการสนับสนุนบน awaiter ใดๆ

คุณสมบัติเพิ่มเติม

• รวมผู้รอคอย (WhenAny, WhenAll, Race...)
• ไทม์ไลน์แฝง (การแก้ไขที่ราบรื่นเมื่อติ๊ก)
• เธรดดั้งเดิม (เซมาฟอร์ เหตุการณ์...)

การติดตั้ง

รองรับเฉพาะรุ่นที่มีหมายเลขเท่านั้น อย่าใช้สาขา Git โดยตรง

ดาวน์โหลดรุ่นที่คุณเลือก และแตกไฟล์ลงในโฟลเดอร์ปลั๊กอินของโปรเจ็กต์ของคุณ เปลี่ยนชื่อโฟลเดอร์เป็น UE5Coro โดยไม่มีหมายเลขเวอร์ชัน เมื่อทำอย่างถูกต้องแล้ว คุณควรจะจบลงด้วย YourProjectPluginsUE5CoroUE5Coro.uplugin

บันทึก

โปรดดู README ของรีลีส หากคุณใช้ 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 ขึ้นอยู่กับโมดูลเครื่องยนต์ที่เปิดใช้งานตามค่าเริ่มต้นเท่านั้น

สำคัญ

อย่า #include ส่วนหัวอื่นใดโดยตรง เฉพาะส่วนหัวที่ตรงกับชื่อของโมดูลเท่านั้น IDE หลักๆ ที่ใช้กับ Unreal Engine เป็นที่ทราบกันว่าคำแนะนำส่วนหัวไม่ถูกต้อง หากคุณเพิ่ม UE5Coro.h ลงใน PCH ของคุณ คุณจะสามารถใช้งานได้ทุกที่

อัพเดท

หากต้องการอัปเดต ให้ลบ UE5Coro ออกจากโฟลเดอร์ปลั๊กอินของโปรเจ็กต์ และติดตั้งเวอร์ชันใหม่ตามคำแนะนำด้านบน

บรรจุภัณฑ์

ไม่จำเป็นต้องทำแพ็กเกจ UE5Coro แยกต่างหาก (จากหน้าต่างปลั๊กอิน) และไม่รองรับ

การกำจัด

หากต้องการลบปลั๊กอินออกจากโปรเจ็กต์ของคุณ ให้ปรับใช้ Coroutine ทั้งหมดของคุณอีกครั้งโดยไม่มีฟังก์ชันการทำงาน ลบการอ้างอิงทั้งหมดไปยังปลั๊กอินและโมดูลของปลั๊กอิน และเพิ่มการเปลี่ยนเส้นทางหลักจาก /Script/UE5CoroK2.K2Node_UE5CoroCallCoroutine ไปยัง /Script/BlueprintGraph.K2Node_CallFunction