游戏 AI / 系统课时
让节点读取 Blackboard 值
让节点读取 Blackboard 值
本节让行为树中的条件和任务读取同一个 Blackboard Key:发现目标时进入追逐分支,目标丢失后恢复巡逻。你将配置键引用、编写一个可复用的 C++ Task,并在运行时确认键值变化如何触发分支切换。
学习目标
- 区分 Blackboard Decorator 的条件读取与 Task 的执行时读取。
- 使用 Key Selector 在自定义 Task 中获取 Actor 引用并处理空值。
- 配置观察与中断规则,验证追逐和巡逻的切换。
准备 Blackboard 和优先级分支
在 Unreal Engine 5 的 C++ 项目中创建 BB_Guard,定义 TargetActor(Object,Base Class 设为 Actor)和 PatrolPoint(Vector)。创建 BT_Guard 并指定 BB_Guard 为 Blackboard Asset;让对应 AIController 在控制角色后通过 RunBehaviorTree 启动它。
在根节点下添加 Selector,左侧为追逐 Sequence,右侧为巡逻分支。Selector 优先尝试左侧:追逐分支通过条件后先运行自定义读取 Task,再运行内置 Move To,其 Blackboard Key 选 TargetActor。右侧的 Move To 则选 PatrolPoint,需要事先写入可到达的位置并确保场景具有导航网格。
选中追逐 Sequence 并添加 Blackboard Decorator,在 Details 中设置 Blackboard Key = TargetActor、Key Query = Is Set、Observer Aborts = Both。条件检查的是键是否有值,不负责让感知系统自动写入键;需要在检测到目标时写入 Actor,丢失目标时清除该键。

在 Task 中读取选定的 Key
新建 C++ 类 BTTask_LogTarget,继承 UBTTask_BlackboardBase。确认游戏模块的 .Build.cs 已将 AIModule 加入依赖;以下两个文件放在同一模块的 Source 目录下。父类提供的 BlackboardKey 选择器允许在行为树里指定键,而不是把键名固定在代码里。
BTTask_LogTarget.h:
#pragma once
#include "CoreMinimal.h"
#include "BehaviorTree/Tasks/BTTask_BlackboardBase.h"
#include "BTTask_LogTarget.generated.h"
UCLASS()
class UBTTask_LogTarget : public UBTTask_BlackboardBase
{
GENERATED_BODY()
public:
UBTTask_LogTarget(const FObjectInitializer& ObjectInitializer);
protected:
// 由行为树执行器调用;通过 OwnerComp 取得当前 AI 的黑板。
virtual EBTNodeResult::Type ExecuteTask(
UBehaviorTreeComponent& OwnerComp, uint8* NodeMemory) override;
};BTTask_LogTarget.cpp:
#include "BTTask_LogTarget.h"
#include "BehaviorTree/BehaviorTreeComponent.h"
#include "BehaviorTree/BlackboardComponent.h"
#include "GameFramework/Actor.h"
UBTTask_LogTarget::UBTTask_LogTarget(const FObjectInitializer& ObjectInitializer)
: Super(ObjectInitializer)
{
NodeName = TEXT("Read TargetActor");
}
EBTNodeResult::Type UBTTask_LogTarget::ExecuteTask(
UBehaviorTreeComponent& OwnerComp, uint8* NodeMemory)
{
const UBlackboardComponent* BB = OwnerComp.GetBlackboardComponent();
if (!BB)
{
return EBTNodeResult::Failed;
}
// Key 名称来自当前 Task 节点的 Blackboard Key 选择项。
AActor* Target = Cast<AActor>(BB->GetValueAsObject(GetSelectedBlackboardKey()));
if (!IsValid(Target))
{
return EBTNodeResult::Failed;
}
UE_LOG(LogTemp, Display, TEXT("Read TargetActor: %s"), *Target->GetName());
return EBTNodeResult::Succeeded;
}编译后把 Read TargetActor 放在追逐 Sequence 的 Move To 之前,并在该 Task 的 Details 中将 Blackboard Key 指向 TargetActor。该 Task 只做一次读取和校验,成功即结束;真正的持续移动由后续 Move To 执行。
预期输出:当 TargetActor 指向有效 Actor 且 Task 被执行时,Output Log 中出现类似内容:
Read TargetActor: <ACTOR_NAME><ACTOR_NAME> 是实际运行时 Actor 的名称,随关卡实例变化;键为空或引用失效时 Task 返回 Failed,不会输出这行日志。
理解值变化、观察与中断
Blackboard Decorator 在分支入口判断条件,还可以监听键变化。Observer Aborts = Both 使条件失效时中断当前追逐分支,条件重新满足时又能打断右侧较低优先级的巡逻分支。配合 Selector 的左右优先级,便形成“有目标追逐、无目标巡逻”。

Notify Observer = On Result Change 适合当前 Is Set 条件,因为只需在“空与非空”之间切换;On Value Change 会在被观察的 Key 值变化时重新评估。注意:将目标 A 改成目标 B 时,Is Set 仍为真,不能仅凭重新评估就推断运行中的自定义 Task 一定会重新执行。持续任务如有换目标需求,应明确处理目标更新或重新进入任务。
运行时核验
- 确认 AIController 正在运行
BT_Guard,巡逻点有效,角色可在 NavMesh 上移动。 - 用现有感知回调给该 AI 的
TargetActor写入有效 Actor;在 PIE 中打开行为树调试器并选中正在运行的 AI 实例。 - 检查 Blackboard 面板中的
TargetActor、当前高亮分支及 Output Log。随后从同一 AI 的 Blackboard 清除TargetActor,观察是否切回巡逻。 - 额外测试 Actor 引用失效与错误 Key 类型,确认 Task 不会因空引用崩溃。
最终要明确区分三件事:感知逻辑负责写键,Decorator 决定分支能否运行并按设置触发中断,Task 则在执行时从当前 AI 的 Blackboard 读取实际对象。