游戏 AI / 系统课时
用 Decorator 约束分支
用 Decorator 约束分支
本课为敌人的追逐与巡逻分支增加明确的准入条件:有目标且能量足够才追逐,条件失效则切换到巡逻。你会配置 Blackboard Decorator 的中断行为,再编写能监听能量键变化的 C++ 自定义 Decorator。
学习目标
- 用 Blackboard 键限制行为树分支的进入条件。
- 区分
Self、Lower Priority与Both的中断范围。 - 编写自定义 Decorator,并验证键值变化触发的分支切换。
让条件守住追逐分支
准备已由 AIController 启动的 Behavior Tree,根节点下使用 Selector:左侧是高优先级 Chase Sequence,右侧是 Patrol Sequence。Blackboard 声明 TargetActor(Object,Base Class 为 Actor)和 Energy(Float);感知逻辑负责设置或清除目标,角色能量系统负责更新能量值。
选中 Chase Sequence,添加内置 Blackboard Decorator,设置 Blackboard Key = TargetActor、Key Query = Is Set、Observer Aborts = Both、Notify Observer = On Value Change。这样目标出现时可以从右侧巡逻切回追逐,目标被清除时可以中止正在执行的追逐。无目标时不应进入 Chase。

中断模式控制何时切换
同样的条件可以用于“进入前检查”或“运行中打断”,差别由 Observer Aborts 决定。
| 模式 | 条件变化后的行为 |
|---|---|
None |
不主动中断正在运行的分支;后续搜索时仍会检查条件 |
Self |
条件不再满足时,可以中断自身及其子分支 |
Lower Priority |
条件满足时,可以中断右侧更低优先级分支 |
Both |
同时覆盖自身失效和高优先级重新满足两种方向 |
Notify Observer = On Value Change 监听所选 Blackboard 键的值变化;On Result Change 则关注条件真假是否变化。只有真正写入 Blackboard 的键值才能触发对应观察:修改 Pawn 上的普通变量却没同步到 Blackboard,不会让该 Blackboard Decorator 自动重评估。模式含义可对照 官方 Decorator 说明。
编写自定义能量 Decorator
内置 Blackboard Decorator 已能完成简单数值比较。这里为了学习扩展节点,编写 UBTDecorator_EnergyAtLeast:只允许选择 Float 键,并将当前值与可编辑阈值比较。继承 UBTDecorator_BlackboardBase,复用对选中 Blackboard 键的观察机制,而不是自行每帧轮询。
在 C++ 游戏模块的 Build.cs 中加入 AIModule 依赖;创建以下两个文件。
BTDecorator_EnergyAtLeast.h:
#pragma once
#include "CoreMinimal.h"
#include "BehaviorTree/Decorators/BTDecorator_BlackboardBase.h"
#include "BTDecorator_EnergyAtLeast.generated.h"
UCLASS()
class UBTDecorator_EnergyAtLeast : public UBTDecorator_BlackboardBase
{
GENERATED_BODY()
public:
UBTDecorator_EnergyAtLeast();
protected:
// 阈值属于节点配置;能量值从当前 AI 的 Blackboard 读取。
UPROPERTY(EditAnywhere, Category = "Condition", meta = (ClampMin = "0.0"))
float MinEnergy = 30.0f;
virtual bool CalculateRawConditionValue(
UBehaviorTreeComponent& OwnerComp, uint8* NodeMemory) const override;
};BTDecorator_EnergyAtLeast.cpp:
#include "BTDecorator_EnergyAtLeast.h"
#include "BehaviorTree/BehaviorTreeComponent.h"
#include "BehaviorTree/BlackboardComponent.h"
UBTDecorator_EnergyAtLeast::UBTDecorator_EnergyAtLeast()
{
NodeName = TEXT("Energy At Least");
// 编辑器中只显示 Float 类型的 Blackboard 键。
BlackboardKey.AddFloatFilter(
this, GET_MEMBER_NAME_CHECKED(UBTDecorator_EnergyAtLeast, BlackboardKey));
}
bool UBTDecorator_EnergyAtLeast::CalculateRawConditionValue(
UBehaviorTreeComponent& OwnerComp, uint8* NodeMemory) const
{
const UBlackboardComponent* BB = OwnerComp.GetBlackboardComponent();
const FName KeyName = GetSelectedBlackboardKey();
if (!BB || KeyName.IsNone())
{
return false;
}
// Decorator 只判断,不负责消耗或补充能量。
return BB->GetValueAsFloat(KeyName) >= MinEnergy;
}预期结果:编译后,Energy At Least 可作为 Decorator 使用;选择 Energy 并设置阈值 30 时,键值为 50 返回 true,键值为 10 返回 false。
把 Energy At Least 挂到 Chase Sequence,选中 Blackboard Key Energy,保持 Min Energy = 30,并设 Observer Aborts = Both。与 TargetActor Is Set 同时挂载时,两道条件都要满足才允许追逐。也可通过 Behavior Tree 编辑器的 New Decorator 创建 BTDecorator_BlueprintBase,在 Perform Condition Check AI 中返回布尔条件;如果需要随 Blackboard 变化及时中断,不要仅靠一次性的蓝图检查。
在运行中核对三个关键场景
在 AIController 初始化或角色能量逻辑中向 Blackboard 写入实际测试值,再通过 PIE 的 Behavior Tree 调试器观察活跃分支。预期结果如下:
TargetActor=有效 Actor,Energy=50:允许 Chase
TargetActor=有效 Actor,Energy=10:阻止或中断 Chase,转入 Patrol
TargetActor=未设置,Energy=50:阻止或中断 Chase,转入 Patrol第一次验证先保证 Patrol 有能持续运行的任务,例如 Wait,否则分支切换可能一闪而过。再分别修改目标和能量,确认不是把 Energy 写到了 Pawn 变量却忘记更新 Blackboard。若有条件消失后仍在移动,检查 Decorator 的 Observer Aborts,以及被中断的长时 Task 是否正确处理 AbortTask 或蓝图 Abort 事件。
Decorator 应保持无副作用:它只回答“现在能否走这条分支”,实际移动、扣能量或清理目标交由 Task、Service 或游戏逻辑负责。