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的核心重定向。