游戏 AI / 系统课时
运行第一个最小行为分支
运行第一个最小行为分支
本课让关卡中的敌人真正开始执行一棵 Behavior Tree:AI Controller 在占有 Pawn 后启动树,自定义 Task 写出一条日志,再由内置 Wait 控制重复间隔。你将通过 Output Log 和行为树调试器同时验证执行,而不是只看资产是否创建成功。
学习目标
- 连接敌人 Pawn、AI Controller 和 Behavior Tree 的启动路径。
- 实现一个返回明确执行结果的 C++ Task,并用 Wait 组成最小分支。
- 在 PIE 中通过日志与节点高亮定位未启动的问题。
先把树接到敌人控制器
在 UE5 C++ 项目中准备一个可放入关卡的 Character 蓝图 BP_Enemy。在内容浏览器通过 + Add → Artificial Intelligence 创建 Blackboard BB_Enemy 和 Behavior Tree BT_Enemy,打开 BT_Enemy,选中 Root,把 Blackboard Asset 设为 BB_Enemy。本课不会读取黑板键,暂时不必新增键。
- 创建继承自
AIController的蓝图BP_EnemyAIController,进入 Event Graph。 - 将
Event On Possess的执行引脚连到Run Behavior Tree,并把该节点的BTAsset设为BT_Enemy,编译保存。 - 打开
BP_Enemy的 Class Defaults,将AI Controller Class设为BP_EnemyAIController,Auto Possess AI设为Placed in World or Spawned。 - 把一个
BP_Enemy实例放进关卡,保存关卡。
On Possess 意味着 Controller 已取得 Pawn 的控制权;仅创建行为树或把它挂到 Root,并不会自动执行。此例没有 Move To,因此无需先布置导航网格。

编写一个可观察的 Task
采用原生 C++ Task,输出固定日志并立即返回 Succeeded。先确认项目的 <ProjectName>.Build.cs 在依赖模块中包含 AIModule,随后在项目模块的 Source 目录中新建以下两个文件并重新编译。这里的代码是完整的同模块类实现,不依赖未展示的自定义工具函数。
BTTask_Announce.h:
#pragma once
#include "CoreMinimal.h"
#include "BehaviorTree/BTTaskNode.h"
#include "BTTask_Announce.generated.h"
// 无需保存跨帧状态的瞬时行为树任务
UCLASS()
class UBTTask_Announce : public UBTTaskNode
{
GENERATED_BODY()
public:
UBTTask_Announce();
protected:
virtual EBTNodeResult::Type ExecuteTask(
UBehaviorTreeComponent& OwnerComp, uint8* NodeMemory) override;
};BTTask_Announce.cpp:
#include "BTTask_Announce.h"
#include "BehaviorTree/BehaviorTreeComponent.h"
#include "AIController.h"
UBTTask_Announce::UBTTask_Announce()
{
NodeName = TEXT("Announce");
}
EBTNodeResult::Type UBTTask_Announce::ExecuteTask(
UBehaviorTreeComponent& OwnerComp, uint8* NodeMemory)
{
const AAIController* Controller = OwnerComp.GetAIOwner();
// 没有有效的受控 Pawn,就不要报告任务成功。
if (!Controller || !Controller->GetPawn())
{
return EBTNodeResult::Failed;
}
UE_LOG(LogTemp, Display, TEXT("Enemy BT: Announce executed"));
// 立即完成,Sequence 才能继续执行后面的 Wait。
return EBTNodeResult::Succeeded;
}预期输出:当这项 Task 被行为树调度执行后,Output Log 中会出现包含以下文本的记录;引擎可能附带不同的时间或日志前缀。
Enemy BT: Announce executedExecuteTask 返回 Succeeded 表示当前叶子任务执行完毕;如果返回 InProgress,就必须在异步工作完成后显式结束任务,否则后面的节点可能无法继续。此示例没有等待异步事件,所以不要返回 InProgress。
还有一个容易忽略的限制:默认原生行为树节点对象可能被多个 AI 共享,不应直接修改 Task 对象上的成员变量来保存单个敌人的运行状态。本例只读取 Controller 并输出日志,不在节点对象中保存实例状态,因此可以安全地被多个敌人复用。
组织最小分支并运行
- 重新打开
BT_Enemy,从Root连接Sequence。 - 在
Sequence下按从左到右的顺序添加Announce和内置Wait。若新 C++ 节点未显示,先确认模块编译成功,必要时重启编辑器。 - 选择
Wait,设Wait Time = 2.0、Random Deviation = 0;保存行为树。 - 运行 PIE,打开
Tools→Debug→Output Log,检查日志。如果编辑器布局不同,也可以从菜单中搜索 Output Log。 - 游戏运行期间打开
BT_Enemy,在行为树调试器的调试对象下拉列表里选择关卡中的敌人 AI 实例,观察运行时分支和Wait高亮。
正常情况下,Announce 先输出一条日志并成功结束,接着 Wait 等待约两秒,整棵树完成后再次进入执行循环。因此日志大致每两秒出现一次,而不是每帧刷屏。编辑器帧率、调度与日志刷新会影响观察到的间隔,不把它当成精确定时器。
这里的 Sequence 只有两个叶子任务。如果 Announce 返回 Failed,Sequence 会直接失败,不会继续执行后面的 Wait。这个执行结果传播机制,也是后续增加移动、攻击或等待条件时必须理解的基础。
日志缺失时按执行链定位
先检查关卡实例是否使用 BP_EnemyAIController,以及 Auto Possess AI 是否覆盖放置到场景中的 Pawn。然后到 BP_EnemyAIController 确认 Event On Possess 确实连到 Run Behavior Tree,且 BTAsset 指向当前的 BT_Enemy。
如果控制器已经启动树,调试器却没有持续高亮,检查 Root → Sequence → Announce → Wait 连接是否完整,并确认原生 Task 已编译、没有返回 Failed。如果仅有一次日志,重点检查 Wait 和分支是否进入正常完成流程;如果日志密集刷屏,通常是忘记添加 Wait 或等待时间为零。
还要注意,Behavior Tree 调试器需要选择正在运行的具体 AI 实例。在关卡里有多个敌人时,查看错误的实例会让人误以为当前敌人的分支没有执行。验证时建议先只保留一个敌人实例,排除选择歧义。
验收标准是同一敌人实例能被调试器选中、Wait 周期性处于运行状态、Output Log 重复出现同一条 Task 日志。这三种证据共同说明控制器启动、任务执行、执行结果传递已经形成闭环。