StateTreeの構成について

# 最初に
StateTreeについて触る機会があったので、自分の中の整理を含めて記事にしてみました。
間違い等あればご指摘頂けますと幸いです。
また、今回の内容は基本的にプログラマー向けになります。

# 環境
Windows 11
UE 5.4.3

# 参考
https://dev.epicgames.com/documentation/ja-jp/unreal-engine/state-tree-in-unreal-engine
# 履歴
| 日時 | 内容 |
| --- | --- |
| 2024/08/15 | Schemaに関する情報に誤解を招く表現があったため、修正しました |

# 準備
エディターのメニューから「編集」>「プラグインの設定」から下記2つを有効化します
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/ffe9fd01-55fd-bea4-d004-e34e9732ebf0.png)

# StateTreeとは
StateTreeとは、様々な場面でロジックをBehaviorTreeやStateMachineの様に管理できる
「**階層型ステートマシン**」です。

BehaviorTreeの代わりに思考を管理する用途に使用することもできれば、
BehaviorTree側で呼び出しのTaskも用意されているため併用も可能です。

また、UE5.4時点でExperimentalではありますが
[Avalanche](https://dev.epicgames.com/community/learning/tutorials/3VRe/unreal-engine-5-s-new-motion-graphic-tools-will-blow-your-mind-project-avalanche?locale=ja-jp)や[MassEntity](https://dev.epicgames.com/documentation/ja-jp/unreal-engine/overview-of-mass-entity-in-unreal-engine)、[GameplayInteractions](https://portal.productboard.com/epicgames/1-unreal-engine-public-roadmap/c/1467-gameplay-interactions-plugin-experimental?&utm_medium=social&utm_source=starter_share)プラグインの中でも使用されており、
今後の活躍が期待できます。

# StateTreeの構成

まず、StateTreeの機能を構成している主な要素について説明をしようと思います。

1. State Tree Component
2. State Tree Schema
3. State
4. Transition
5. Node(Task, Evaluator, Condition)

# 1. State Tree Component

StateTreeを利用したいActorにアタッチするComponentです。
AI使用を目的として用意された派生である`UStateTreeAIComponent`の他、
C++、BPで継承して独自実装も可能です。

StateTreeComponentで行う内容は以下

- StateTreeの開始、一時停止、終了
- 使用するStateTreeとParameterの設定
- 使用するSchemaの定義

### StateTreeの開始、一時停止、終了

`UStateTreeComponent`は`UBrainComponent`を継承しており、
各種オーバーライドした関数がStateTreeに対する実行処理になります

| 関数名 | 処理内容 |
| --- | --- |
| StartLogic | StateTreeの開始 |
| RestartLogic | 実行中、また終了しているStateTreeの再稼働 |
| StopLogic | StateTreeの停止 |
| PauseLogic | StateTreeの一時停止 |
| ResumeLogic | StateTreeの再開 |
| IsRunning | StateTreeが実行中か |
| IsPaused | StateTreeが一時停止中か |

### 使用するStateTreeとParameterの設定

このComponentで使用するStateTreeの指定を行います。
![image (1).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/4dc4649c-ed0b-4a38-d159-76b0c11e4e6a.png)

Parameterというのは、StateTreeのアセット側で定義して、
外部から引数として指定できる値でそれなりに自由なパラメーターの指定が可能です。
![image (2).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/30080233-1e0b-04a9-c642-9203d6252c91.png)
値を追加すると、StateTreeを設定している場所で追加した値の設定が可能になります。
![image (3).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/0addbbfc-4077-e9df-3797-b393683388cc.png)

### 使用するSchemaの定義

Schemaの定義は、StateTreeComponentが継承している
`IStateTreeSchemaProvider`の`GetSchema`を使って、
このComponentで使用したいSchemaのクラスを指定します。
```cpp
// 例：AIStateTreeComponent
TSubclassOf<UStateTreeSchema> UStateTreeAIComponent::GetSchema() const
{
	return UStateTreeAIComponentSchema::StaticClass();
}
```
この指定を行うことで、StateTreeComponentでStateTreeを設定する時に
同じSchemaを使用しているStateTreeしかリストアップされなくなります。

# 2. Schema
後述するNode(Task、Condition、Evaluator)の制限や、
StateTreeエディタにあるContext項目など各所で利用するデータの構造や形式を定義します。
![image (4).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/f6737ba5-6e47-9c74-a28f-51cfbf74de82.png)
C++限定ですが自分で`UStateTreeSchema`を継承して作成や拡張することも可能です。

Schemaの基本的な役割は以下
- Contextの指定
- Nodeに対する制限
- Nodeとして使用できる型の制限
- ExternalDataの型指定、収集

### **Contextの指定**
Schemaで定義される、StateTree内で使用可能な外部のデータです。
基本的にはStateTreeを利用しているActorやAIControllerなどが対象になっています。
![image (6).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/bc17d0ac-d9b3-9055-f2c7-12e42207e85d.png)
![image (5).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/1afae77d-e0aa-30ce-8d70-f13ce03f9004.png)
ここで定義された内容はStateTree内でNodeのPropertyBindとして使用可能です。
![image (7).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/adb1f79a-4d97-0f9e-2eae-ba91d030d9fc.png)

### Nodeに対する制限
Evaluator、ConditionのStateTree上での使用を制限できます
```cpp
/** @return True if enter conditions are allowed. */
virtual bool AllowEnterConditions() const { return true; }

/** @return True if evaluators are allowed. */
virtual bool AllowEvaluators() const { return true; }
```
また、１つのStateに１つのTaskだけにすることも可能です。
```cpp
/** @return True if multiple tasks are allowed. */
virtual bool AllowMultipleTasks() const { return true; }
```

### Nodeとして使用できる型の制限

特定の型のTask、Evaluator、Conditionのエディタ上での使用自体を制限できます
`UStateTreeAISchema`では追加で`FStateTreeAITaskBase`を使用できるように指定しています。

```cpp
/** @return True if specified struct is supported */
virtual bool IsStructAllowed(const UScriptStruct* InScriptStruct) const { return false; }

/** @return True if specified class is supported */
virtual bool IsClassAllowed(const UClass* InScriptStruct) const { return false; }
```
```cpp
bool UStateTreeAIComponentSchema::IsStructAllowed(const UScriptStruct* InScriptStruct) const
{
	return Super::IsStructAllowed(InScriptStruct) || InScriptStruct->IsChildOf(FStateTreeAITaskBase::StaticStruct());
}
```

### ExternalDataの型指定、収集
External Dataとは、各Nodeで特定の外部データを参照したい時、
都度取得するための関数を呼ばなくて済むように予め情報をキャッシュして
Handle経由で簡単にアクセスできるようにする機能です。

Schemaではそこで使用できる型の指定と、実際のデータの収集を行います。
```cpp
class STATETREEMODULE_API UStateTreeSchema : public UObject
{
	// 使用できる型の判定.
	virtual bool IsExternalItemAllowed(const UStruct& InStruct) const { return false; }
}
```

※具体的な使用方法はNodeのExternal Dataに関する項目をご確認ください。
例として、StateTreeComponentSchemaでは

- Actor
- Component
- World Subsystem

の使用が許可されています。


```cpp
bool UStateTreeComponentSchema::IsExternalItemAllowed(const UStruct& InStruct) const
{
	return InStruct.IsChildOf(AActor::StaticClass())
			|| InStruct.IsChildOf(UActorComponent::StaticClass())
			|| InStruct.IsChildOf(UWorldSubsystem::StaticClass());
}
```
そして、CollectExternalData関数で外部データの情報をキャッシュしています。
```cpp
bool UStateTreeComponentSchema::CollectExternalData(const FStateTreeExecutionContext& Context, const UStateTree* StateTree, TArrayView<const FStateTreeExternalDataDesc> ExternalDataDescs, TArrayView<FStateTreeDataView> OutDataViews)
{
	// ~略~
	AAIController* AIOwner = Cast<AAIController>(Owner);
	for (int32 Index = 0; Index < ExternalDataDescs.Num(); Index++)
	{
		const FStateTreeExternalDataDesc& ItemDesc = ExternalDataDescs[Index];
		if (ItemDesc.Struct != nullptr)
		{
			if (ItemDesc.Struct->IsChildOf(UWorldSubsystem::StaticClass()))
			{
				UWorldSubsystem* Subsystem = World->GetSubsystemBase(Cast<UClass>(const_cast<UStruct*>(ItemDesc.Struct.Get())));
				OutDataViews[Index] = FStateTreeDataView(Subsystem);
			}
			else if (ItemDesc.Struct->IsChildOf(UActorComponent::StaticClass()))
			{
				UActorComponent* Component = Owner->FindComponentByClass(Cast<UClass>(const_cast<UStruct*>(ItemDesc.Struct.Get())));
				OutDataViews[Index] = FStateTreeDataView(Component);
			}
			else if (ItemDesc.Struct->IsChildOf(APawn::StaticClass()))
			{
				APawn* OwnerPawn = (AIOwner != nullptr) ? AIOwner->GetPawn() : Cast<APawn>(Owner);
				OutDataViews[Index] = FStateTreeDataView(OwnerPawn);
			}
			else if (ItemDesc.Struct->IsChildOf(AAIController::StaticClass()))
			{
				AAIController* OwnerController = AIOwner;
				OutDataViews[Index] = FStateTreeDataView(OwnerController);
			}
			else if (ItemDesc.Struct->IsChildOf(AActor::StaticClass()))
			{
				AActor* OwnerActor = (AIOwner != nullptr) ? AIOwner->GetPawn() : Owner;
				OutDataViews[Index] = FStateTreeDataView(OwnerActor);
			}
		}
	}

	return true;
}
```

ここで注意しないといけないのが、上記処理をみると`UStateTreeComponentSchema`で
取得できるActorやComponentは**全てOwnerを経由したものである**ということです。
つまり、Ownerに関連していない他キャラなどの参照は行えません。
そういったデータを参照するときはEvaluaterを使用するのが良いでしょう。

# **3. State**
状態(階層)を定義します。遷移する条件に応じてアクティブなStateを切り替えることで、
状況に応じたTaskなどの処理を行うことができます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/dc8bf557-0ee3-6f9d-a0ed-f561237111d9.png)
Stateのパラメーターを見ていきましょう
![image (9).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/b875a0cf-7ef8-190b-406d-88c7a7082a88.png)

| 名前 | 説明 |
| --- | --- |
| Name | Stateの名前 |
| Type | Stateのタイプ |
| Selection Behavior | Stateがアクティブになる時の挙動 |
| Parameters | このState以下でバインド可能な一時変数 |
| Enter Conditions | このStateをアクティブの判定に使用されるConditionのリスト |
| Tasks | このStateがアクティブな場合に処理されるTaskのリスト |
| Transitions | このStateがアクティブな時に他Stateへ移動する場合の遷移先リスト |

### Type
このStateがどういった挙動を行うかの設定です。

- State
Taskや子供Stateを含む通常のState

- Group
子Stateだけを含むStateです。これ自体に処理を行う能力はありません。
※そのためTaskは設定できません、途中でタイプを切替してもCompile時に破棄されます

    ![image (10).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/a200e84d-273d-0502-49af-28e6bfbc5ce1.png)
    
- Linked
StateTree内の別Stateのフローを流用したい場合に使用します。
Linked Subtreeには流用したいState(TypeはSubtree設定のものOnly)を指定します
※Group同様、このState自体にTaskを設定することはできません。

    ![image (11).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/141e8019-806b-38da-3fe7-5e056bbd060d.png)
    
- Subtree
Linked設定のStateから指定することができるStateです。
このStateは意図的に遷移しない限り、通常のフローで遷移することはありません
    
    ![image (12).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/546eaa26-8bdb-7ec2-72b5-0eb6a5dc26d9.png)

    
- Linked Asset    
    別のSubTreeアセットを使用することが可能です。
    ※使用できるのは、別のStateTreeのみです
    
    ![image (13).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/3fe9ab33-a408-affc-444b-62ef2384de40.png)

    
<details><summary>※Linked と SubTreeについての補足</summary>    
使用例を説明すると 

- 戦闘中はエネミーに向かって移動し、到着したらランダムなアクション
- 非戦闘中はプレイヤーに向かって移動し、到着したらランダムなアクション

といったすごいアレな内容のフローを用意したい時があるとします。
これを何も考えずに作ります。
![image (14).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/38f9b87b-c6f1-01ac-0ef7-1eedc60b7ee7.png)
    
今は単純な移動とランダムなアクション、と言っているので問題ないですが
これが複雑な行動になっていくと、それぞれのStateに都度タスクや
子Stateを追加していくのは正直なところ手間です。
    
そこでLinkedとSubTreeを活用します、
先ほどの画像の処理をSubTreeを使って変更するとこのようになります。

![image (15).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/af1f69c9-c55d-7ed4-8a71-059ea646d614.png)
    
変更した内容としては
- それぞれのStateで行っていた処理を別のフローで用意
- 呼び出し元のStateをLinked設定に変更して移動先のStateをSubTreeに変更
   
これで今後拡張があっても、共通処理になっているので
SubTreeの方を変更するだけで済みます。
    
ちなみに、SubTreeのStateでは呼び出し元(Linked)のStateから
渡すパラメーターを引数の様に定義できます。
    
これを利用すれば、同じフローで条件を変更して処理をさせるといったことも可能です
![image (16).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/e25da7b8-bb34-1d36-bea9-c91c06340f55.png)

![image (17).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/e3e758c8-cf84-f0df-a5af-71bccbe9edb5.png)
    
</details>

### Selection Behavior

- None
Transitionの遷移先候補に指定できません、また、通常の遷移の対象にもなりません。

- TryEnterState    
    子Stateがいても、まずこのStateが選択されます。
    子Stateに遷移したい場合は別途Transitionを指定する必要があります。
    
- TrySelectChildrenInOrder
最初に遷移可能な子Stateを選択しようとします。
子Stateが存在しない場合は、このStateが選択されます

- TryFollowTransitions
    Stateに遷移する時、代わりにTransitionをトリガーして有効なStateに遷移します

# **4. Transition**
Stateなどから、他のStateに遷移したい場合の条件などを設定するための機能です、
こちらは以下のパターンの使用方法があります。

- State 経由のTransition
- Instance Data 経由のTransition

### State経由のTransition
![image (18).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/ae23e61c-b10b-193c-6b04-2f8050db381a.png)
各パラメーターの説明を記載します。

### Trigger
遷移の判定タイミングです。
| On State Completed | Stateが終了した時に遷移判定が行われます |
| --- | --- |
| On State Succeeded | Stateが成功終了した時に遷移判定が行われます |
| On State Failed | Stateが失敗終了した時に遷移判定が行われます |
| On Tick | 毎フレーム遷移判定が行われます |
| On Event | 特定のEvent(Gameplay Tag)が発行された時に遷移判定が行われます |

OnEventのトリガーとなるイベントは各Nodeから呼び出し可能です。
![image (19).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/2ae1acc2-2245-408a-34fc-a022593bc8d8.png)
C++は`FStateTreeInstanceData(FStateTreeInstanceStorage)`の`EventQueue`の関数を呼び出します。

```cpp
struct FStateTreeInstanceStorage
{
	/** Events */
	UPROPERTY()
	FStateTreeEventQueue EventQueue;
};

struct STATETREEMODULE_API FStateTreeEventQueue
{
	void SendEvent(const UObject* Owner, const FGameplayTag& Tag, const FConstStructView Payload = FConstStructView(), const FName Origin = FName());
};
```

`UStateTreeComponent`を使用している場合は下記関数でも呼び出し可能です。

```cpp
class UStateTreeComponent
{
	/** Sends event to the running StateTree. */
	UFUNCTION(BlueprintCallable, Category = "Gameplay|StateTree")
	void SendStateTreeEvent(const FStateTreeEvent& Event);

	/** Sends event to the running StateTree. */
	void SendStateTreeEvent(const FGameplayTag Tag, const FConstStructView Payload = FConstStructView(), const FName Origin = FName());
};
```

### Transition To

遷移先の指定を行います。特定のStateを指定する他、遷移の仕方の指定をすることもできます
![image (20).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/98707a27-cab6-8af9-5c9e-89be4589e5aa.png)

| None | 何もしません |
| --- | --- |
| Next State | 同階層の次(下)にあるStateに移動します |
| Next Selectable State | 同階層の次(下)にある、遷移可能なStateに移動します |
| Tree Succeeded | StateTreeを成功扱いで終了させます。 |
| Tree Failed | StateTreeを失敗扱いで終了させます。 |
| StateTree内のState名 | 指定したStateに遷移します |

#### Conditions
遷移条件です。複数指定可、詳細は後述するNodeのConditionをご参照ください。

#### Priority
※On Tick, On Eventのみ
遷移の優先度です。同じ優先度が複数ある場合は登録順に実行されます。

#### Delay Transition

※On Tick, On Eventのみ
trueを指定すると、遷移実行がDelay Duration( + Delay Random Variance)の秒数だけ遅延します。
遅延中に他のTransitionが条件を満たした場合は、そちらが優先されます。

#### Delay Duration

※On Tick, On Eventのみ
遷移の実行を遅らせる時間(秒)

#### Delay Random Variance

※On Tick, On Eventのみ
Delay Durationに加算する、遅延時間のランダムな範囲の最大値(秒)です。

### Instance Data経由のTransition
TransitionはState外、各Nodeからのリクエスト可能です。
![image (21).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/de89a2c6-9316-96cc-cde2-9d5bfc6a8263.png)

C++では`FStateTreeInstanceData`(`FStateTreeInstanceStorage`)経由でリクエストします。

```cpp
struct FStateTreeInstanceStorage
{
	void AddTransitionRequest(const UObject* Owner, const FStateTreeTransitionRequest& Request);
};
```

# **5. Node**
StateTree内で使用する要素で、以下の派生があります。

1. Task
基本はActiveなState内で行う「処理」を定義するものです
※Global Taskという、StateTree実行中にStateに関係なく動作するTaskもあります
2. Evaluator
SchemaのContextやExternal Data、StateTreeのParameterで参照できない、
外部のデータをStateTreeで参照できるようにするものです。
3. Condition
StateのTransition全般で「条件」を定義するものです。

これら全てをまとめて「Node」と呼称します。
実際、各種使用される定義の派生は全てNodeBaseを継承しています。

C++ベースの継承
```mermaid
classDiagram
	class FStateTreeNodeBase{
		Nodeとしての機能全般
	}
	namespace  ソース側で独自実装する時のBase {
		class FStateTreeTaskCommonBase{
		}
		class FStateTreeEvaluatorCommonBase{
		}
		class FStateTreeConditionCommonBase{
		}
	}
	FStateTreeNodeBase--FStateTreeTaskBase:派生
	FStateTreeNodeBase--FStateTreeEvaluatorBase:派生
	FStateTreeNodeBase--FStateTreeConditionBase:派生
	
	FStateTreeTaskBase--FStateTreeTaskCommonBase:派生
	FStateTreeEvaluatorBase--FStateTreeEvaluatorCommonBase:派生
	FStateTreeConditionBase--FStateTreeConditionCommonBase:派生
```
BPベースの継承
```mermaid
classDiagram
	class FStateTreeNodeBase{
		Nodeとしての機能全般
	}
	FStateTreeNodeBase--FStateTreeTaskBase:派生
	FStateTreeNodeBase--FStateTreeEvaluatorBase:派生
	FStateTreeNodeBase--FStateTreeConditionBase:派生
	
	FStateTreeTaskBase--FStateTreeBlueprintTaskWrapper:派生
	FStateTreeEvaluatorBase--FStateTreeBlueprintEvaluatorWrapper:派生
	FStateTreeConditionBase--FStateTreeBlueprintConditionWrapper:派生
	
	FStateTreeBlueprintTaskWrapper-->UStateTreeTaskBlueprintBase:呼び出し
	FStateTreeBlueprintEvaluatorWrapper-->UStateTreeEvaluatorBlueprintBase:呼び出し
	FStateTreeBlueprintConditionWrapper-->UStateTreeConditionBlueprintBase:呼び出し

namespace  BPで独自実装する時のBase {
		class UStateTreeTaskBlueprintBase{
		}
		class UStateTreeEvaluatorBlueprintBase{
		}
		class UStateTreeConditionBlueprintBase{
		}
	}

```

まずそれぞれの話に移る前に、Nodeで共通部分の説明をします。
- Instance Data
- Property Bind
- External Data(外部データの参照の設定)

### Instance Data
各Nodeは、
- `FStateTreeNodeBase`を継承した実処理を記載する定義
- NodeのRuntime中のデータを保存するInstanceData用の定義

で構成されます　**※BPベースの場合は考慮の必要はありません**

デフォルトで用意されている、DelayTaskを例に見てみます。

```cpp
USTRUCT()
struct STATETREEMODULE_API FStateTreeDelayTaskInstanceData
{
	GENERATED_BODY()
	
	/** Delay before the task ends. */
	UPROPERTY(EditAnywhere, Category = Parameter, meta = (EditCondition = "!bRunForever", ClampMin="0.0"))
	float Duration = 1.f;
	
	/** Adds random range to the Duration. */
	UPROPERTY(EditAnywhere, Category = Parameter, meta = (EditCondition = "!bRunForever", ClampMin="0.0"))
	float RandomDeviation = 0.f;
	
	/** If true the task will run forever until a transition stops it. */
	UPROPERTY(EditAnywhere, Category = Parameter)
	bool bRunForever = false;

	/** Internal countdown in seconds. */
	float RemainingTime = 0.f;
};

USTRUCT(meta = (DisplayName = "Delay Task"))
struct STATETREEMODULE_API FStateTreeDelayTask : public FStateTreeTaskCommonBase
{
	GENERATED_BODY()

	using FInstanceDataType = FStateTreeDelayTaskInstanceData;
	
	FStateTreeDelayTask() = default;

	virtual const UStruct* GetInstanceDataType() const override { return FInstanceDataType::StaticStruct(); }

	virtual EStateTreeRunStatus EnterState(FStateTreeExecutionContext& Context, const FStateTreeTransitionResult& Transition) const override;
	virtual EStateTreeRunStatus Tick(FStateTreeExecutionContext& Context, const float DeltaTime) const override;
};
```

コードを見るとわかりますが、

- `FStateTreeDelayTask`が`FStateTreeNodeBase`を継承して、時間カウントの実処理の定義
- `FStateTreeDelayTaskInstanceData`が処理で使用するパラメーターを保持

となっています。

何故このような構成になっているのかは、
ActiveではないStateのメモリを無駄に確保しないようにするためと思われます。

InstanceDataの指定は`FStateTreeNodeBase`のGetInstanceDataType関数で行います。
`UStruct`を渡していますが、派生である`UClass`の指定も可能です

```cpp
/** @return Struct that represents the runtime data of the node. */
virtual const UStruct* GetInstanceDataType() const { return nullptr; };
```

ちなみに全てのパラメーターをInstanceDataに定義する必要はなく、
設定パラメーターなどRuntime中に変化しないものは、実処理側の宣言で問題ありません

### Property Bind

Evaluatorなどを作って頂くとわかりやすいですが、
StateTree内のEvaluatorやTaskなどのパラメーターを他のNodeで参照できる機能です。
![image (22).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/ba3d8618-6d7d-b864-d340-41a9421fc8ce.png)

この機能はNodeの種類によってバインドできる対象が異なります。

| Nodeの種類 | バインド可能なデータ |
| --- | --- |
| Condition(StateのEnter条件) | Globalなデータの他、親StateのTaskのパラメーター |
| Condition(Transitionの条件) | Globalなデータの他、親Stateと現在ActiveなStateのTaskのパラメーター |
| Task | Globalなデータの他、親StateのTask、現在ActiveなStateの自分より前に実行されるTaskのパラメーター |

親StateのTaskで処理した結果を子StateのEnter条件に使いたい、が可能ということです。
また、Propertyのカテゴリで以下の様にPropetyBindの制限をかけることもできます。

1. Categoryに”Input”を指定
   
    ```cpp
    // 例：DrawDebugTextTaskのReferenceActor
    USTRUCT()
    struct STATETREEMODULE_API FStateTreeDebugTextTaskInstanceData
    {
    	GENERATED_BODY()
    
    	/** Optional actor where to draw the text at. */
    	UPROPERTY(EditAnywhere, Category = "Input", meta=(Optional))
    	TObjectPtr<AActor> ReferenceActor = nullptr;
    };
    ```
    
    StateTree上の表示を見ると、バインドでのみ指定ができることが分かります。
    `DrawDebugTextTask`の場合はOptionalが設定されていますが、
    通常Inputカテゴリに指定されているパラメーターはバインドされていない時は
    エラーになりますのでご注意ください。
    ![image (24).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/66fa9e34-885b-0053-c1bc-aca48ab89f6d.png)
    
2. Categoryに”Output”を指定
例：Evaluator(BPで定義しているのに特に理由はありません)
    ![image (25).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/a18f00ac-68a5-f485-f190-bd49dd5c4416.png)
    ![image (26).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/73a2aaf6-a563-7ff0-24cf-b954898aeae0.png)
    
    Outputを指定すると、StateTree上ではBind出力専用になっており、    値を変更することはできません。
    ![image (27).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/f4f9d25b-c12f-1882-058f-e818b67ad30c.png)
    
3. 指定なし(or 上記以外)
例：DelayTask
    ```cpp
    USTRUCT()
    struct STATETREEMODULE_API FStateTreeDelayTaskInstanceData
    {
    	GENERATED_BODY()
    	
    	/** Delay before the task ends. */
    	UPROPERTY(EditAnywhere, Category = Parameter, meta = (EditCondition = "!bRunForever", ClampMin="0.0"))
    	float Duration = 1.f;
    
    	~略~	
    };
    ```
    
    StateTree内で設定もできますし、他のデータでバインドも可能です
    ![image (28).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/1f5f9664-3d86-077a-1709-5bf4a410d1d7.png)
    

### External Data(外部データの参照の設定)

Schemaの説明でも記載しましたが、
StateTree外の情報を簡単に参照できるようにするための機能です。
**※BPベースでは使用できません。**

使用方法は`FStateTreeNodeBase`のLink関数をオーバーライドして、
`TStateTreeExternalDataHandle`を使ってHandleを定義するだけです。

```cpp
struct FTestSTTask_Test : public FStateTreeTaskBase
{
		virtual bool Link(FStateTreeLinker& Linker) override;

		// ここで使用できる型はSchemaで指定した型のみ！
		TStateTreeExternalDataHandle<UStateTreeComponent> CompHandle;
};
```

```cpp
virtual bool FTestSTTask_Test::Link(FStateTreeLinker& Linker)
{
	Linker.LinkExternalData(CompHandle);
	return true;
}
```

あとは`FStateTreeExecutionContext`の`GetExternalData()`で参照するだけです。
ポインタも可能。

```cpp
EStateTreeRunStatus FTestSTTask_Test::EnterState(FStateTreeExecutionContext& Context,
	const FStateTreeTransitionResult& Transition) const
{	
	const UStateTreeComponent& Component = Context.GetExternalData(CompHandle);
	return FStateTreeTaskBase::EnterState(Context, Transition);
}
```

# **5-1. Task**

TaskはアクティブなState内で動作する通常のTaskと、
Stateの状態に関係なく動作するGlobalTaskの２種類があります。
こちらは呼び出し方が違うだけで、Task自体は共通で使用可能です。
![image (29).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/07bde2fe-bca0-192c-88e9-5a0fc3b752e8.png)

### Taskの処理のタイミング
GrobalTaskは基本的にStateTree実行中、常に実行されます。
通常のTaskでは以下のタイミング別に処理を呼び出すことができます
![image (30).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/ceb1d8b6-ed67-5ab1-fca3-802ec045343f.png)

![image (31).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/e9cf8972-6c39-a6d5-1587-64ada17458c5.png)
| イベント名 | タイミング |
| --- | --- |
| EnterState | Stateの開始時に呼ばれます |
| Tick | StateがActiveな時、毎Tick呼ばれます |
| ExitState | Stateの終了時に呼ばれます |
| StateCompleted | Stateが完了した時に呼ばれますが、
条件付きのTransitionによる遷移など特定の状況下では呼ばれないので
終了時の解放、クリア処理などを呼ぶのは避けた方が良いです。 |

また、タスクの処理タイミングは設定によっても変化するため注意が必要です。
![image (31).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/cd558f72-3cbd-eaae-f789-46f50bddf556.png)

- `bShouldStateChangeOnReselect`
trueの場合、タスクは所属しているStateが前にアクティブだった場合でも、EnterState/ExitState を呼び出します。
- `bShouldCallTick`
    Tickを呼ぶかどうかのフラグ
    ※falseだとバインドされているプロパティの情報が更新されないので注意してください
    
- `bShouldCallTickOnlyOnEvents`
    trueに設定すると、Tick()はイベントがあるときのみ呼び出されます。
    `bShouldCallTickState`がtrueの場合は効果なし。
    ※Tickしない場合はバインドプロパティの情報が更新されないので注意してください
    

### TaskはStateの終了判定に関係している

TaskはStateの完了判定に関わっており、StateのTransitionにある
- `OnStateCompleted`
- `OnStateSucceeded`
- `OnStateFailed`

上記タイミングはState内にあるTaskの終了に応じて発行されます
(複数ある場合はどれか1つが終了するとトリガーされます)
**※GlobalTaskの場合はStateTree自体の終了判定になります**


挙動としてはDelayTaskがわかりやすいです、
Durationで指定された時間が経過すると`OnStateSucceeded`で終了します。
![image (32).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/081ebbf7-d1d2-ace5-e199-2a259602f150.png)
ただし、全てのTaskがこの限りではありません。
下記画像で使用しているDebugTextTaskは終了しないTaskのため、
この場合はState1に留まり続けてしまうため注意が必要です。
![image (33).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/e0f628c8-0413-7949-be12-f0d3c7057931.png)

# **5-2. Evaluator**
ContextやStateTreeのParameter以外の、使用したい外部データを取得するのに使用します。
データの更新は以下のタイミングで行えるようになっています。
![image (34).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/028eec03-0b6d-b085-de0b-b8a8fc802515.png)

| 関数名 | タイミング |
| --- | --- |
| Tick | StateTree実行中毎Tick呼ばれる |
| TreeStart | StateTree開始時 |
| TreeStop | StateTree終了時 |

上記好きなタイミングで取得処理を記載し、EvaluatorのInstanceDataの変数に反映して
変数のUPropertyでOutputを指定すればStateTree内で参照が可能になります

# **5-3. Condition**
Stateの遷移に関連する場所で使用する判定を定義します。
使用箇所は以下

- StateのEnter条件
    ![image (35).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/9a08b2dc-62f7-fe5a-e507-c718253c436d.png)
    
- Transitionの遷移条件
    ![image (36).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/e43b9c9e-c9a4-605e-ec34-dce9d1dc362f.png)
    

Conditionは判定の結果を返す関数のみです。
![image (37).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/f03e5b51-ea25-7d6e-6f46-0c65eecd8a1a.png)

```cpp
struct STATETREEMODULE_API FStateTreeConditionBase : public FStateTreeNodeBase
{

	virtual bool TestCondition(FStateTreeExecutionContext& Context) const { return false; }
};
```

# **おまけ**

StateTreeにはデバッグ機能が存在しており、StateTreeの遷移を録画することが可能です。

表示されていない場合はツールバー>Window>Debuggerで表示してください
![image (38).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/7a972f3c-d302-d58d-665f-b6d039740801.png)
1. シュミレーションの再生、停止
2. StateTreeのトレース録画の開始、停止
3. 録画したトレースの削除
4. トレースした対象Actorと実行番号
5. 録画時のタイムラインとState表示
6. 選択している4と5のシークバーのタイミングにおけるStateの状態

その他、Stateにはブレークポイントも配置できます。
![Untitled (1).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/276335/dc269c95-122a-36d0-4ba2-55c11cf4054f.png)


# 最後に
次回があれば、今回はみでた`FStateTreeExecutionContext`と合わせて
StateTreeの進行について記事にできればと思います。