游戏 AI / 系统课时
把感知结果写入 Blackboard
把感知结果写入 Blackboard
本课把 UE5 视觉感知事件转换为行为树可读取的 Blackboard 键值:看见玩家时设置目标与视线状态,丢失视线时清除当前目标但保留最后可见位置。完成后,追击和搜索分支就能依据数据变化切换,而不是在 Task 中反复扫描玩家。
学习目标
- 处理
OnTargetPerceptionUpdated并筛选玩家的 Sight 事件。 - 分开维护当前目标、视线布尔值和最后可见位置。
- 验证 Blackboard 更新能够触发行为树 Decorator 的分支切换。
准备黑板与分支
在 BB_Enemy Blackboard 资产中创建三个键,名称和类型必须与代码一致:
| 键名 | 类型 | 含义 |
|---|---|---|
| TargetActor | Object,Base Class 为 Actor | 当前仍能看见的目标 |
| HasLineOfSight | Bool | 是否仍能通过 Sight 看到目标 |
| LastKnownLocation | Vector | 最近一次成功看见目标的位置 |
创建 BT_Enemy,将 Blackboard Asset 设为 BB_Enemy。在 Selector 中安排高优先级 Chase(HasLineOfSight 为 true 且 TargetActor Is Set,Move To 使用 TargetActor)、较低优先级 Search(LastKnownLocation Is Set,Move To 使用此位置)和兜底 Wait。为 Chase 的观察条件设置 Observer Aborts: Both,让发现目标时可抢占搜索、丢失时可退出追击。搜索到达后应由相应任务清除旧位置,避免重复搜索。
玩家 Character 的 Actor Tags 加入 Player,并添加 AI Perception Stimuli Source,开启自动注册且将 AISense_Sight 加入刺激类型。敌人的 AI Controller Class 将使用下文的控制器,Auto Possess AI 设为 Placed in World or Spawned。
设计事件到决策的数据流
OnTargetPerceptionUpdated 把 Actor 和 FAIStimulus 交给 AIController。事件处理先检查 Actor 有效性、Player 标签和 Sight 类型,接着按 WasSuccessfullySensed() 写入不同键。成功时记录 StimulusLocation,失败时只处理当前正在追踪的目标,避免其他 Actor 的丢失事件误清空目标。

这里要区分当前视线事实与历史位置记忆。如果失去视线时仍将旧 Actor 当作可见目标,Chase 可能继续对不可见对象执行;如果同时清空最后位置,Search 就失去可用目的地。对只有一个测试玩家的课程,直接以事件驱动这三个键即可。
实现控制器与更新逻辑
以下完整的 UE5 C++ 类使用 AIModule,需要在项目模块 .Build.cs 的依赖列表中加入它。分别保存为两个同名源文件,并在该类的蓝图子类默认值中指定 BehaviorTreeAsset = BT_Enemy。黑板初始化由 RunBehaviorTree 依据所选行为树的 Blackboard Asset 完成。
PerceptionBlackboardController.h:
#pragma once
#include "CoreMinimal.h"
#include "AIController.h"
#include "Perception/AIPerceptionTypes.h"
#include "PerceptionBlackboardController.generated.h"
class UBehaviorTree;
class UAIPerceptionComponent;
class UAISenseConfig_Sight;
UCLASS()
class APerceptionBlackboardController : public AAIController
{
GENERATED_BODY()
public:
APerceptionBlackboardController();
protected:
// 在控制器占有敌人 Pawn 后启动行为树,完成黑板初始化。
virtual void OnPossess(APawn* InPawn) override;
UPROPERTY(EditDefaultsOnly, Category = "AI")
TObjectPtr<UBehaviorTree> BehaviorTreeAsset;
private:
UPROPERTY(VisibleAnywhere)
TObjectPtr<UAIPerceptionComponent> Listener;
UPROPERTY()
TObjectPtr<UAISenseConfig_Sight> SightConfig;
// AddDynamic 需要 UFUNCTION 作为事件回调。
UFUNCTION()
void HandlePerception(AActor* Actor, FAIStimulus Stimulus);
};PerceptionBlackboardController.cpp:
#include "PerceptionBlackboardController.h"
#include "BehaviorTree/BehaviorTree.h"
#include "BehaviorTree/BlackboardComponent.h"
#include "Perception/AIPerceptionComponent.h"
#include "Perception/AISense.h"
#include "Perception/AISense_Sight.h"
#include "Perception/AISenseConfig_Sight.h"
APerceptionBlackboardController::APerceptionBlackboardController()
{
Listener = CreateDefaultSubobject<UAIPerceptionComponent>(TEXT("SightListener"));
SightConfig = CreateDefaultSubobject<UAISenseConfig_Sight>(TEXT("SightConfig"));
// 与玩家刺激源配套的视觉范围和阵营过滤。
SightConfig->SightRadius = 1500.0f;
SightConfig->LoseSightRadius = 1800.0f;
SightConfig->PeripheralVisionAngleDegrees = 60.0f;
SightConfig->DetectionByAffiliation.bDetectNeutrals = true;
SightConfig->DetectionByAffiliation.bDetectEnemies = true;
SightConfig->DetectionByAffiliation.bDetectFriendlies = true;
Listener->ConfigureSense(*SightConfig);
Listener->SetDominantSense(UAISense_Sight::StaticClass());
SetPerceptionComponent(*Listener);
Listener->OnTargetPerceptionUpdated.AddDynamic(
this, &APerceptionBlackboardController::HandlePerception);
}
void APerceptionBlackboardController::OnPossess(APawn* InPawn)
{
Super::OnPossess(InPawn);
if (BehaviorTreeAsset)
{
RunBehaviorTree(BehaviorTreeAsset);
}
}
void APerceptionBlackboardController::HandlePerception(
AActor* Actor, FAIStimulus Stimulus)
{
// 只响应玩家的视觉事件,避免听觉等感知污染目标键。
if (!IsValid(Actor) || !Actor->ActorHasTag(TEXT("Player")) ||
Stimulus.Type != UAISense::GetSenseID<UAISense_Sight>())
{
return;
}
UBlackboardComponent* BB = GetBlackboardComponent();
if (!BB)
{
return;
}
const FName TargetKey(TEXT("TargetActor"));
UObject* CurrentTarget = BB->GetValueAsObject(TargetKey);
if (Stimulus.WasSuccessfullySensed())
{
// 已有目标时不被第二名玩家的感知事件覆盖。
if (CurrentTarget && CurrentTarget != Actor)
{
return;
}
BB->SetValueAsObject(TargetKey, Actor);
BB->SetValueAsBool(TEXT("HasLineOfSight"), true);
BB->SetValueAsVector(TEXT("LastKnownLocation"),
Stimulus.StimulusLocation);
UE_LOG(LogTemp, Warning, TEXT("Perception acquired: %s"),
*GetNameSafe(Actor));
}
else if (CurrentTarget == Actor)
{
// 失去视线仍保留上次可见位置,供搜索分支使用。
BB->SetValueAsBool(TEXT("HasLineOfSight"), false);
BB->ClearValue(TargetKey);
UE_LOG(LogTemp, Warning, TEXT("Perception lost: %s"),
*GetNameSafe(Actor));
}
}预期输出(玩家对象名称仅为示例,<ID> 是运行时动态标识):
LogTemp: Warning: Perception acquired: BP_Player_C_<ID>
LogTemp: Warning: Perception lost: BP_Player_C_<ID>验证分支与处理边界
在 PIE 中打开行为树调试器或 AI Debugger,选中敌人并观察 Blackboard。玩家从正面进入视野时,TargetActor 指向玩家、HasLineOfSight=true,追击分支具备执行条件;墙体阻断视线后,TargetActor 应变为空、HasLineOfSight=false,而 LastKnownLocation 保持先前坐标。随后 Search 可以移动到该位置;清理旧位置后才会回到 Wait。
如果日志出现但 Blackboard 不变化,优先检查控制器是否成功运行关联了 BB_Enemy 的 BT_Enemy、键名大小写是否一致以及玩家是否具有 Player 标签。如果 Blackboard 正确更新而分支没有切换,检查 Decorator 的比较条件与 Observer Aborts,而不是重复添加感知组件。
OnTargetPerceptionUpdated 不保证在目标对象已销毁后仍提供有效 Actor;正式项目还应处理目标销毁和多目标重新选择。此示例有意限制为单目标演示,重点是让视觉事实与搜索记忆分别驱动正确的行为树分支。