unreal-behavior-trees

Unreal Behavior Trees

Blackboard によって駆動される Behavior Trees を使って、UE5 の NPC の意思決定を作成します。Composite でツリーを構成し、Decorator でブランチを制御し、Service で状態を最新に保ち、AIController から実行します。対象は UE 5.8 です。

使用する場面

• 敵や NPC の AI を構築する場合。BT_／BB_ アセットのペアを作成する、Selector／Sequence ブランチを構成する、Decorator（条件）や Service（定期的な更新）を追加する、カスタムの BTTask／BTService ノードを作成する、または AIController を接続してツリーを実行する場合に使用します。
• プロジェクトに Behavior Tree（BT_）および Blackboard（BB_）アセットと AAIController がある場合に使用します。

使用しない場面： AI の概念（FSM と BT の比較、ステアリング、エンジンをまたいだ内容）には game-ai を使用します。ナビゲーション／経路探索の計算のみを扱う場合は、エンジンのナビメッシュを使用します（BT の MoveTo はこれを使用します）。単純な単発のロジックは、完全なツリーより小さなステートマシンで実装するほうが効率的な場合があります。

Behavior Tree と StateTree のどちらを使うべきですか？ UE 5.8 には両方が含まれており、Behavior Tree は非推奨ではありません。StateTree は Epic の汎用階層型ステートマシンで、BT 形式の選択と、明示的な State および Transition を組み合わせています。プロジェクトですでに StateTree アセットを使用している場合や、AI が明確な遷移を持つモードの集合（patrol → alert → combat）として自然に表現できる場合は、Behavior Tree を追加する前にユーザーに確認してください。プロジェクトですでに BT_／BB_ アセットを使用している場合は、Behavior Trees を使い続けてください。

基本的なワークフロー

1. ペアを作成します： Blackboard（BB_）には型付きキー（AI の記憶である TargetActor、LastKnownLocation、bIsInvestigating）を格納します。Behavior Tree（BT_）はその Blackboard を参照します。
2. Possess して実行します。 AAIController が Pawn を Possess し、RunBehaviorTree(BT) を呼び出します。これにより、参照先の Blackboard も初期化されます。
3. Composite で構成します。 Selector は子ノードを左から右へ実行し、いずれかが成功するまで続けます（優先順位／フォールバック：「攻撃、そうでなければ追跡、そうでなければ巡回」）。Sequence は子ノードをいずれかが失敗するまで実行します（すべて実行：「遮蔽物へ移動 → リロード → 様子を見る」）。Simple Parallel は、1 つのメインタスクと並行して副タスクを実行します。
4. Blackboard のキーを読み取る Decorator でブランチを制御します（例：「ターゲットあり？」で戦闘ブランチを制御します）。キーが変化したときにツリーを再評価するよう、Observer Aborts を設定します。
5. ブランチにアタッチした Service で Blackboard を最新の状態に保ちます。Service はブランチがアクティブな間だけ定期的に実行されます（例：視認チェックで TargetActor を更新します）。
6. Task で処理を実行します。 Task は Succeeded、Failed、または InProgress を返します（MoveTo のような潜在 Task は後で完了します）。
7. 動作を確認します。 PIE 中に Behavior Tree デバッガーを使用すると、実行中のノードがハイライトされ、Blackboard のライブ値が表示されるため、どのブランチが実行されているかを正確に確認できます。

パターン

1. ツリーを実行する AIController（C++）

void AEnemyAIController::OnPossess(APawn* InPawn)
{
    Super::OnPossess(InPawn);
    if (BehaviorTree)                 // UPROPERTY(EditAnywhere) TObjectPtr<UBehaviorTree>
        RunBehaviorTree(BehaviorTree); // initializes & uses the Blackboard the BT references
}

2. 優先順位付きツリー（ノード構造）

ROOT
└── Selector (try combat, else investigate, else patrol)
    ├── Sequence            [Decorator: Blackboard 'TargetActor' Is Set, Observer Aborts: Both]
    │     ├── Task: MoveTo (TargetActor)          // latent: returns InProgress then Succeeded
    │     └── Task: Attack
    ├── Sequence            [Decorator: 'LastKnownLocation' Is Set]
    │     ├── Task: MoveTo (LastKnownLocation)
    │     └── Task: Wait (3s) + clear key
    └── Task: Patrol (BTTask_FindPatrolPoint -> MoveTo)

Observer Aborts: Both を設定すると、TargetActor が設定された瞬間に戦闘ブランチが巡回を中断し、クリアされたときに戦闘ブランチを終了します。これにより、AI がすばやく反応するようになります。

3. コードから Blackboard を更新する（例：プレイヤーを見つけたとき）

void AEnemyAIController::SetTarget(AActor* Target)
{
    if (UBlackboardComponent* BB = GetBlackboardComponent())
        BB->SetValueAsObject(TEXT("TargetActor"), Target);   // key name must match the BB asset
}
// Clear with BB->ClearValue(TEXT("TargetActor")); to drop back to a lower-priority branch.

よくある落とし穴

• AI が起動しない — ポーンが操作されていません（ポーンの Auto Possess AI を「Placed in World or Spawned」に設定し、AIController を割り当ててください）。または、RunBehaviorTree が呼び出されていません。
• MoveTo がすぐに失敗する — レベルに NavMesh がありません（Nav Mesh Bounds Volume を追加してください）。または、ターゲットが NavMesh の外にあります。
• ブランチが変更に反応しない — 条件となるデコレーターの Observer Aborts が None に設定されています。キーが変更されたときにツリーが再評価されるよう、Self／Lower Priority／Both に設定してください。
• タスクでツリーが停止する — カスタムタスクが InProgress を返した後、FinishLatentTask を呼び出していません。遅延タスクは必ず完了させてください。
• ブラックボードのキーの入力ミス — SetValueAsObject("Taget", ...) は何もせずに処理を終了します。キー名と型を正確に一致させるか、キャッシュ済みの FBlackboardKeySelector を使用してください。
• Sequence と Selector の混同 — Sequence = AND（最初の失敗で停止）、Selector = OR（最初の成功で停止）です。入れ替えると動作が逆になります。

参考資料

• カスタム C++ UBTTaskNode（EBTNodeResult を返す即時および遅延の ExecuteTask と、FBlackboardKeySelector）については、references/custom-bttask.md を参照してください。
• 主要ドキュメント：「Unreal Engine のビヘイビアツリー」 (https://dev.epicgames.com/documentation/en-us/unreal-engine/behavior-trees-in-unreal-engine)。

関連スキル

• game-ai — エンジンに依存しない AI 設計（FSM、BT、ステアリング、経路探索の選択）。
• unreal-cpp-gameplay — C++ での AIController とポーンクラス。
• fps-shooter／tower-defense — 敵 AI を組み込むジャンル。