游戏 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 的丢失事件误清空目标。

Sight 感知事件驱动 Blackboard 与行为树分支切换

这里要区分当前视线事实与历史位置记忆。如果失去视线时仍将旧 Actor 当作可见目标,Chase 可能继续对不可见对象执行;如果同时清空最后位置,Search 就失去可用目的地。对只有一个测试玩家的课程,直接以事件驱动这三个键即可。

实现控制器与更新逻辑

以下完整的 UE5 C++ 类使用 AIModule,需要在项目模块 .Build.cs 的依赖列表中加入它。分别保存为两个同名源文件,并在该类的蓝图子类默认值中指定 BehaviorTreeAsset = BT_Enemy。黑板初始化由 RunBehaviorTree 依据所选行为树的 Blackboard Asset 完成。

PerceptionBlackboardController.h:

cpp
#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:

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> 是运行时动态标识):

text
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;正式项目还应处理目标销毁和多目标重新选择。此示例有意限制为单目标演示,重点是让视觉事实与搜索记忆分别驱动正确的行为树分支。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

把感知结果写入 Blackboard

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通