ue5coro

UE5コロ

UE5Coro は、ゲームプレイ ロジック、利便性、およびエンジンとのシームレスな統合の提供に重点を置いて、Unreal Engine 5 用の C++20 コルーチン サポートを実装しています。

注記

C++17、古いコンパイラ、プラットフォーム、エンジン バージョンのサポートは、レガシー UE5Coro 1.x シリーズで利用できます。

潜在的な UFUNCTION を簡単に作成するためのサポートが組み込まれています。潜在 UFUNCTION の戻り値の型を変更してコルーチンにすると、BP セーフなマルチスレッド サポートを備えた FPendingLatentAction ボイラープレートをすべて無料で入手できます。

 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++ コルーチンもサポートされています。基になる実装はコンパイル時に選択されます。潜在的なアクションは、実際に使用した場合にのみ作成されます。

戻り値の型をこのプラグインが提供するコルーチン型の 1 つに変更すると、自分で実装するには面倒な複雑な非同期タスクが 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);
• 喜ばせるのは難しいですか？ AddDynamic/BindDynamic 専用の UFUNCTION を記述したり、UCLASS や他のクラスに属したりせずに、DYNAMIC デリゲートを非同期で待機する方法を次に示します。
  co_await YourDynamicDelegate; (これがコード全体です)
• ああ、そのデリゲートにパラメータが必要だったのですか?
  auto [Your, Parameters] = co_await YourDynamicDelegate;

これにより、このプラグインで可能なコードと労力の大幅な削減がわかるはずです。一般に、記述するコードが少なく単純であればバグも少なくなります。また、非同期コードが簡単に記述できるということは、物事を正しい方法ですぐに実行する際に摩擦がないことを意味します。

現時点では十分な機能を備えた LoadSynchronous に別れを告げましょう。この LoadSynchronous はまだ出荷中ですが、2 回の更新が予定されています。当面のタスクが「StreamableManager ボイラープレートをすべて記述し、呼び出し関数の一部をコールバックに移動する」から単に「その前に co_await を貼り付ける」に減らされると、思いつくよりも早く完了するでしょう。同期ブロッキング バージョンが何らかの形で受け入れられる理由の正当な理由を示します。

このプラグインには、可変数の値を返すためだけに TArray 全体を割り当てることを回避できるジェネレーターなど、追加機能が多数あります。記述が容易になり、コンパイラーによる最適化が容易になり、N 個の項目に対して O(N) ではなく O(1) ストレージのみが必要になります。何が気に入らないでしょうか?

機能一覧

次のリンクから、ドキュメントの関連ページにアクセスできます。最新のドキュメントをブラウザで読みたい場合、または IDE から直接読みたい場合は、このセクションをブックマークしてください。すべての API 関数は C++ ヘッダーに文書化されており、リリースには、現在読んでいる文書の Markdown ソースが含まれています。

コルーチンのオーサリング

これらの機能は、コルーチンをエンジンの残りの部分に公開することに重点を置いています。

• コルーチン (当然)
  • キャンセルサポートには専用のページがあります。
• 発電機
• ゲームプレイ能力 システム統合の仕組みは若干異なります。

アンリアルの統合

これらのラッパーは、コルーチンからエンジン機能を利用する便利な方法を提供します。

• AI 統合 (MoveTo、経路検索など)
• アニメーション待機 (モンタージュ、通知など)
• 非同期待機者 (マルチスレッド、同期など)
• HTTP (非同期 HTTP リクエスト)
• 暗黙的な awaiter (特定のエンジン タイプはラッパーなしで直接 co_awaitable)
• 潜在的な待機者 (ゲーム スレッドのインタラクション、遅延など)
  • アセットの読み込み (ソフト ポインター、バンドルなどの非同期読み込み)
  • 非同期衝突クエリ (ライン トレース、オーバーラップ チェックなど)
  • 潜在チェーン (ユニバーサル潜在アクション ラッパー)
  • ティック時間バジェット (フレームごとに x ミリ秒実行)
• 潜在的なコールバック (潜在的なアクション マネージャーとの対話)

注記

これらの関数のほとんどは、 UE5Coro::Private名前空間から文書化されていない内部型を返します。クライアント コードは、この名前空間の内容を直接参照しないでください。事前に非推奨にされることなく、将来のバージョンで変更される可能性があるためです。

ほとんどの場合、これは問題ではありません。たとえば、 co_await Something()内の名前のない一時オブジェクトはソース コードには表示されません。 Private戻り値を保存する必要がある場合は、型の名前を書き込まないようにauto (または制約付きTAwaitable auto ) を使用します。

必要に応じてパブリックな C++ 待機可能関数await_ready 、 await_suspend 、およびawait_resumeを直接呼び出すことは、どの awaiter でもサポートされていません。

追加機能

• 集約待機者 (WhenAny、WhenAll、Race...)
• 潜在的なタイムライン (ティック上のスムーズな補間)
• スレッドプリミティブ (セマフォ、イベントなど)

インストール

番号付きのリリースのみがサポートされます。 Git ブランチを直接使用しないでください。

選択したリリースをダウンロードし、プロジェクトの Plugins フォルダーに抽出します。フォルダーの名前を、バージョン番号を付けずに UE5Coro に変更します。正しく実行すると、 YourProjectPluginsUE5CoroUE5Coro.upluginが作成されるはずです。

注記

1.x を使用している場合は、リリース独自の README を参照してください。複数のプラグインを含む別のインストール方法がありました。

プロジェクトのセットアップ

プロジェクトでは、C++20 サポートのロックを解除するために削除する必要があるレガシー設定が使用されている場合があります。それ以外の場合は、Unreal Engine 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 しないでください。モジュール名に一致するヘッダーのみを含めてください。 Unreal Engine で使用される主要な IDE は、ヘッダーの提案が間違っていることが知られています。 UE5Coro.h を PCH に追加すると、どこでも利用できるようになります。

アップデート

更新するには、プロジェクトの Plugins フォルダーから UE5Coro を削除し、上記の手順に従って新しいバージョンをインストールします。

包装

UE5Coro を (プラグイン ウィンドウから) 個別にパッケージ化する必要はなく、サポートされていません。

除去

プロジェクトからプラグインを削除するには、その機能を除いてすべてのコルーチンを再実装し、プラグインとそのモジュールへのすべての参照を削除し、 /Script/UE5CoroK2.K2Node_UE5CoroCallCoroutineから/Script/BlueprintGraph.K2Node_CallFunctionへのコア リダイレクトを追加します。