ue5coro

UE5科羅

UE5Coro 實現了對虛幻引擎 5 的 C++20 協程支持，重點是遊戲邏輯、便利性並提供與引擎的無縫整合。

筆記

舊版 UE5Coro 1.x 系列支援 C++17、較舊的編譯器、平台和引擎版本。

內建支援輕鬆創作潛在 UFUNCTION。更改潛在 UFUNCTION 的返回類型以使其成為協程，並且您可以免費獲得所有 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崩潰。

甚至協程返回類型也對 BP 隱藏，以免打擾設計者：

對潛在的 UFUNCTION 不感興趣？不是問題。也支援原始 C++ 協程，具有完全相同的功能集。支援實作是在編譯時選擇的；僅當您實際使用潛在操作時才會建立它們。

將您的返回類型更改為該插件提供的協程類型之一，並且您自己實現起來很麻煩的複雜異步任務變成了 Just Work™ 的瑣碎單行，從而消除了對回調和其他處理程序的需要。

• 享受 LoadSynchronous 的便利，但不享受它的缺點？
  UObject* HardPtr = co_await AsyncLoadObject(SoftPtr);讓您只保留福利（以及您的 FPS）。
• 將繁重的計算分散到多個刻度上怎麼樣？
  新增一個co_await NextTick();在一個循環中，你就已經完成了。有一個時間預算類別可以讓您直接指定所需的處理時間，並讓協程自行動態調度。
• 說到動態調度，限制可以像這樣簡單：
  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 委託，而無需僅為 AddDynamic/BindDynamic 編寫 UFUNCTION，或位於 UCLASS 或任何類別：
  co_await YourDynamicDelegate; （這就是整個程式碼）
• 哦，您想要該委託的參數嗎？
  auto [Your, Parameters] = co_await YourDynamicDelegate;

這應該可以讓您體驗到使用此外掛程式可以顯著減少程式碼和工作量。編寫更少、更簡單的程式碼通常意味著更少的錯誤，並且易於編寫的非同步程式碼意味著在立即以正確的方式做事時不會出現任何摩擦。

告別仍在發布中的“good-enough-for-now™ LoadSynchronous”，兩次更新後。隨著手頭上的任務從“編寫所有 StreamableManager 樣板並將調用函數的一部分移動到回調”減少到僅僅“將 co_await 放在它前面”，您將比出現時更快地完成並解釋為什麼同步阻塞版本在某種程度上是可以接受的。

該插件中有很多附加功能，例如生成器，可以讓您避免僅僅為了返回可變數量的值而分配整個 TArray。更容易編寫，更容易編譯器優化，您只需要 O(1) 儲存而不是 O(N) 儲存 N 項，有什麼不喜歡的呢？

功能列表

以下連結將帶您造訪文件的相關頁面。如果您希望在瀏覽器中閱讀最新文檔，或直接從 IDE 中閱讀，請將此部分加入書籤。每個 API 函數都記錄在 C++ 標頭中，且版本包含您正在閱讀的文件的 Markdown 原始碼。

協程編寫

這些功能著重於將協程暴露給引擎的其餘部分。

• 協程（顯然）
  • 取消支援有自己的頁面。
• 發電機
• 遊戲能力系統整合的工作原理略有不同。

虛幻集成

這些包裝器提供了從協程使用引擎功能的便捷方法。

• AI 整合（MoveTo、尋路...）
• 動畫等候者（蒙太奇、通知...）
• 非同步等待者（多執行緒、同步...）
• HTTP（非同步 HTTP 請求）
• 隱式等待者（某些引擎類型直接 co_awaitable，沒有包裝器）
• 潛在等待者（遊戲線程互動、延遲...）
  • 資源載入（非同步載入軟指標、捆綁包...）
  • 非同步碰撞查詢（線路追蹤、重疊檢查...）
  • 潛在鏈（通用潛在動作包裝器）
  • 刻度時間預算（每幀運行 x 毫秒）
• 潛在回調（與潛在操作管理器互動）

筆記

這些函數中的大多數從UE5Coro::Private命名空間傳回未記錄的內部類型。客戶端程式碼不應直接引用此命名空間中的任何內容，因為其中的所有內容都可能在未來版本中發生更改，而無需事先棄用。

大多數情況下，這不是問題：例如， co_await Something()中的未命名臨時物件不會出現在原始程式碼中。如果需要儲存Private回傳值，請使用auto （或受約束的TAwaitable auto ）以避免寫入類型的名稱。

任何等待程式都不支援直接呼叫公共必要的 C++ 可等待函數await_ready 、 await_suspend和await_resume 。

附加功能

• 聚合等待者（WhenAny、WhenAll、Race...）
• 潛在時間軸（刻度上的平滑插值）
• 線程原語（信號量、事件...）

安裝

僅支援編號版本。不要直接使用 Git 分支。

下載您選擇的版本，並將其解壓縮到專案的 Plugins 資料夾中。將資料夾重新命名為 UE5Coro，不含版本號。正確完成後，您最終應該得到YourProjectPluginsUE5CoroUE5Coro.uplugin 。

筆記

如果您使用的是 1.x，請參閱該版本自己的自述文件。它有一種不同的安裝方法，涉及多個插件。

項目設定

您的專案可能會使用一些需要刪除的舊設定才能解鎖 C++20 支持，否則這些設定將成為虛幻引擎 5.3 或更高版本中建立的新專案的標準配置。

在您的Target.cs檔案（所有檔案）中，請確保您使用的是最新設定並包含訂單版本：

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

如果您使用的是舊版bEnableCppCoroutinesForEvaluation標誌，則不再需要它，並且不應再明確開啟它；這樣做可能會導致問題。建議從建置檔中刪除對它的所有引用。

如果您在 Build.cs 檔案中將CppStandard設定為CppStandardVersion.Cpp17 ...不要:)

用法

像引用任何其他 C++ 模組一樣從 Build.cs 中引用"UE5Coro"模組，並使用#include "UE5Coro.h" 。插件本身不需要啟用。

某些功能位於需要單獨引用的選用模組中。例如，遊戲能力系統支援需要 Build.cs 中的"UE5CoroGAS" ，並#include "UE5CoroGAS.h" 。核心 UE5Coro 模組僅依賴預設啟用的引擎模組。

重要的

不要直接 #include 任何其他標頭，僅包含與模組名稱相符的標頭。眾所周知，與虛幻引擎一起使用的主要 IDE 會得到錯誤的標頭建議。如果將 UE5Coro.h 新增至 PCH，則可以使其在任何地方都可使用。

更新

若要更新，請從專案的 Plugins 資料夾中刪除 UE5Coro，然後按照上述說明安裝新版本。

包裝

不需要也不支援單獨打包 UE5Coro（從「插件」視窗）。

移動

若要從專案中刪除插件，請重新實現所有沒有其功能的協程，刪除對該插件及其模組的所有引用，並新增從/Script/UE5CoroK2.K2Node_UE5CoroCallCoroutine到/Script/BlueprintGraph.K2Node_CallFunction的核心重定向。