情報は力ではない

UE4 とか Blender とか。

Gameplay Targeting System Plugin について

UE5.2 のリリースノートに記載されていた Gameplay Targeting System Plugin について気になったので調べてみました。

概要

Unreal Engine 5.2 にて追加された、ターゲットリクエストをデータドリブンで行えるようにするプラグイン

docs.unrealengine.com

以下では主に Blueprint での Gameplay Targeting System Plugin(以下 Targeting System)の使用方法を説明します。

導入方法

Targeting System を導入するには Plugins より Targeting System を有効にします。

ターゲットリクエス

Targeting System ではターゲットリクエストを行うことで、ターゲット対象を取得することができます。ターゲットリクエストには、即時ターゲットリクエストと非同期ターゲットリクエストの2種類あります。

即時ターゲットリクエス

即時ターゲットリクエストは、ターゲットリクエスト実行後、即座にターゲット対象を取得することができます。同期的な処理のため、ターゲットリクエストが完了するまで処理がブロッキングされます。

即時ターゲットリクエストを行うには、TargetingSubsystem の ExecuteTargetingRequest ノードを使用します。

このノードには3つの入力が必要で、それぞれ Targeting Preset、Targeting Source Context、Delegate(Completion Dynamic Delegate)になります。

Targeting Preset、Targeting Source Context は後述します。Delegate は、ターゲットリクエストが完了した際に呼ばれる Delegate です。この Delegate は Targeting Request Handle を入力引数とするイベントになります。

Targeting Request Handle については後述します。

非同期ターゲットリクエス

非同期ターゲットリクエストは、ターゲットリクエスト実行後、非同期にターゲット対象を取得することができます。非同期処理のため、ターゲットリクエストが完了するまで処理がブロッキングされない可能性があります(公式ドキュメントにゲームスレッドがブロックされない可能性がありますとの記載があるため、本記事でも「可能性があります」と記載)。

非同期ターゲットリクエストを行うには、TargetingSubsystem の StartAsyncTargetingRequest ノードを使用します。

このノードの入力は即時ターゲットリクエストと同様です。このノードには出力があり Targeting Request Handle になります。

Targeting Request Handle

Targeting Request Handle は、ターゲットリクエストの結果を取得するために使用するデータ構造です。

即時ターゲットリクエストの場合は Delegate の入力引数として取得できます。

非同期ターゲットリクエストの場合は Delegate の入力引数だけでなく TargetingSubsystem の StartAsyncTargetingRequest の出力としても取得ができます。

リクエスト結果の取得

ターゲットリクエストの結果を取得するには、以下の2つのノードが用意されています。

GetTargetingResults は、入力に TargetRequestHandle を渡すことで、そのリクエストに対応した結果を HitResult の配列として取得できます。

GetTargetingResultsActors は GetTargetingResults と同様、入力に TargetingRequestHandle を渡すことで、そのリクエストに対応した結果からターゲット対象となった Actor の配列を取得できます。

例えば、即時ターゲットリクエストを用いて、リクエスト結果を取得する処理は以下のような流れになるかと思います。

非同期ターゲットリクエストの場合も同様に Delegate イベントにてターゲットリクエストの結果を取得する流れになると思います。StartAsyncTargetRequest の出力から得られた Targeting Request Handle を保持しておいて、ターゲットリクエスト完了後に好きなタイミングでターゲットリクエストの結果を得ることもできると思います。

上記までで、ターゲットリクエストの実行方法、リクエスト結果の取得方法を説明したので、次に説明を後回しにしていたターゲットリクエストの入力である Targeting Preset、Targeting Source Context について説明します。

Targeting Preset

Targeting Preset は、ターゲットリクエスト時にターゲット対象を決めるための処理(Targeting Task)を設定した Data Asset です。

Targeting Preset に設定するのは Targeting Task のみで複数の Targeting Task を設定可能です。ターゲットリクエスト時には Targeting Preset に設定した Targeting Task を上から順に評価し、ターゲット対象を取得します。

下図は2つの Targeting Task を設定した Targeting Preset の例で Targeting Selection Task AOE で範囲内のターゲット対象を取得し、距離の近い順にソートした結果を取得することを期待した Targeting Preset です。

Targeting Task

Targeting Task は Targeting Preset で設定するクラスで、その処理の内容により大まかにターゲット対象の選択、フィルタ、ソートの3つに分類できます。

Targeting System で用意されている Targeting Task は以下になります。

名前 カテゴリ 説明
TargetingFilterTask_ActorClass フィルタ Filter する Actor、しない Actorを指定するフィルタタスク
TargetingFilterTask_SortByDistance ソート Source からの位置でソートするソートタスク。Source の位置は SourceContext の SourceActor の ActorLocation または SourceLocation を使用する
TargetingSelectionTask_AOE 選択 Source からの位置を中心とした領域と衝突するすべてのアクタを取得するタスク。複数の形状 (ボックス、シリンダー、球体、カプセル) をサポートするだけでなく、コンポーネント タグで指定されたソース アクタ上でのコンポーネントの使用もサポートしている。AOE は Area of Effect の略だと思われる。
TargetingSelectionTask_SourceActor 選択 SourceContext に指定されている SourceActor を取得するタスク
TargetingSelectionTask_Trace 選択 LineTrace/SweepTrace で最初に衝突した Actor を取得するタスク

自身で Targeting Task を作成することも可能です。筆者が Targeting Task の作成まで調査していないため、説明を省きますが、それぞれのカテゴリごとに親クラスが用意されているようです。

カテゴリ 使用する親クラス
選択 TargetingTask
フィルター TargetingFilterTask_BasicFilterTemplate
ソート TargetingSortTask_Base

Targeting Source Context

Targeting Source Context は、ターゲットリクエストのコンテキストデータで、ターゲットリクエスト時の Source Actor や Instigator Actor、Source の位置を保持するデータ構造です。

例えば TargetingSelectionTask_Trace は Source の位置からトレースを開始しますが、この Source の位置は Targeting Source Context に与えられた Source Actor(Source Actor が設定されていなければ Source の位置)を使用します。

以上が Targeting Preset、Targeting Source Context の説明になります。

Targeting Preset、Targeting Source Context、Delegate を準備することでターゲットリクエストが実施でき、ターゲットリクエストの結果を受け取り、その結果を処理することができます。

例ではありますが、即時ターゲットリクエストを行う際の処理の流れは以下のようになるかと思います。

その他

デバッグコマンド

ターゲットリクエストの結果をHUD 上に表示したり、可視化したりするデバッグ機能がある。 コンソールコマンド自体については公式ドキュメントに記載があるので、そちらを参照。

docs.unrealengine.com

Gameplay Ability 向けタスクノード

まだ調べていないので記載していませんが Gameplay Ability 向けのタスクノードも用意されているようです。

Targeting Request Handle の解放

公式ドキュメントにも記載がありますが Targeting Request Handle に対応した結果は自身で削除しないと残り続け、自動的に解放してくれないように見えます(即時ターゲットリクエスト、非同期ターゲットリクエストに関わらず)。

今のところ、Targeting Request Handle に対応した結果を削除することは Blueprint ではできないように見えるため、必要であれば C++ でノードを作成する必要がありそうです。*1

*1:TargetingSubsystem に RemoveAsyncTargetingRequestWithHandle がありますが Blueprint 上は Targeting Request Handle が出力となっており、入力に指定した Targeting Request Handle に対応したターゲットリクエストの結果を削除するようなノードはなさそうに見える。