UE AI感知失效排查：团队接口与碰撞配置详解

1. 项目概述：当AI的“眼睛”失灵时

在虚幻引擎（UE）里捣鼓AI行为树和感知系统，是每个想做点有挑战性玩法的开发者必经之路。你花了好几天，精心设计了敌人的巡逻路线、战斗逻辑，甚至给它们加上了酷炫的视觉和听觉感知组件（AIPerceptionComponent），满心期待着一场智能的遭遇战。结果呢？敌人像个木头桩子一样杵在原地，任凭玩家在它眼皮子底下蹦迪，它却“视而不见”。这种挫败感，我太懂了。问题往往就出在那个看似不起眼，却又至关重要的团队归属（Team）系统上，而它的核心接口IGenericTeamAgentInterface，正是排查“AI看不见”问题的第一站。

简单来说，UE的AI感知系统不是无差别扫描。它内置了一套高效的过滤机制，其中一个关键过滤器就是“团队关系”。默认情况下，一个AI的感知组件只会去“注意”那些被它视为“敌对团队”的Actor。如果你的玩家角色和AI敌人没有正确配置团队ID，或者压根就没实现这个团队接口，那么即使它们的物理碰撞体已经重叠，感知组件也会优雅地忽略对方，仿佛戴上了一副“选择性失明”的眼镜。这不仅仅是新手容易踩的坑，很多有经验的开发者在复用代码、迁移角色蓝图或者使用某些插件时，也可能会无意中破坏这个脆弱的关联。

所以，这篇指南的目的很明确：我们不谈高深的AI理论，就聚焦于解决“AI看不见敌人”这个具体又恼人的问题。我们将从IGenericTeamAgentInterface这个接口出发，像侦探一样，一步步排查线索，理解其工作原理，并给出从源码到蓝图、从配置到调试的完整解决方案。无论你是使用C++原生开发，还是纯蓝图爱好者，都能在这里找到答案。

2. 核心原理：团队接口如何成为感知的“门卫”

要解决问题，必须先理解问题背后的逻辑。UE的AI感知，尤其是视觉（Sight）感知，其工作流程远比一个简单的射线检测要复杂。它是一套由AIPerceptionSystem驱动的、基于订阅和通知的体系。而IGenericTeamAgentInterface在其中扮演了“守门人”和“分类器”的双重角色。

2.1 IGenericTeamAgentInterface 的角色与职责

这个接口的核心目的，是为游戏中的Actor（无论是Pawn、Character还是任意Actor）提供一个简单的“团队标识”。它只定义了两个关键函数：

1. FGenericTeamId GetGenericTeamId() const： 获取该Actor所属的团队ID。
2. ETeamAttitude::Type GetTeamAttitudeTowards(const AActor& Other) const： 获取本Actor对另一个Actor的团队态度（敌对、中立、友好）。

团队ID (FGenericTeamId) 本质上是一个简单的整数包装，但它有一个特殊值NoTeamId（通常为255），表示该Actor不属于任何团队，或者未设置团队。

团队态度 (ETeamAttitude) 是一个枚举，包含：

• Friendly： 友方，通常意味着忽略或协作。
• Neutral： 中立，取决于具体配置，可能被感知也可能被忽略。
• Hostile： 敌方，这是触发AI感知反应（如“OnTargetPerceptionUpdated”）的最常见条件。

为什么需要这个接口？想象一下在一个大型开放世界中，有成百上千个AI和玩家。如果每个AI的感知组件每一帧都对场景中的所有Actor进行昂贵的检测（如视锥体计算、射线追踪），性能将瞬间崩溃。因此，UE引入了“团队过滤器”作为最前置、最廉价的过滤手段。在感知系统决定是否要对一个Actor进行详细的感官检测（如计算是否在视野内、是否在可听范围内）之前，它会先询问：“这个Actor是我的敌人吗？” 这个问题的答案，就来自于GetTeamAttitudeTowards函数。

2.2 感知组件中的团队过滤器

在AIPerceptionComponent的配置中，有一个容易被忽略但至关重要的属性：“感知过滤器”。当你为AI添加一个“AI视觉”或“AI听觉”组件后，在细节面板中展开对应感知配置（如Sight Config），你会找到与团队相关的过滤选项。

默认的感知源（AISense_Sight）会使用一个内置的团队关系过滤器。其逻辑大致如下：

1. 感知系统获取到所有可能被感知的Actor列表（基于一些粗略的空间划分）。
2. 对于列表中的每个Actor，感知系统会检查感知者（AI）和被感知者（Actor）是否都实现了IGenericTeamAgentInterface。
3. 如果两者都实现了，则调用感知者的GetTeamAttitudeTowards(OtherActor)。
4. 如果返回Hostile，则该Actor有资格进入下一步的详细感官检测（如视野角度、距离判断）。如果返回Friendly或Neutral，则通常在此阶段就被过滤掉，根本不会进行视野计算，这就是“看不见”的根本原因。
5. 如果有一方没有实现该接口，那么默认行为是什么？这里就是最大的坑点之一。默认行为因引擎版本和配置而异，但常见的情况是：如果感知者没有实现接口，它可能无法正确识别团队；如果被感知者没有实现接口，它可能会被当作NoTeamId处理，而NoTeamId与任何团队的关系态度，取决于你在AIPerceptionSystem或项目设置中的全局配置，默认可能是“中立”。

注意： 很多开发者误以为只要在AI敌人身上挂载了AIPerceptionComponent并设置了视觉半径，它就能“看见”玩家。实际上，如果玩家角色Pawn没有正确实现IGenericTeamAgentInterface并返回一个与AI敌对的团队ID，那么AI的感知系统在第一步团队过滤时就会把玩家筛掉，后续的视野检测根本不会执行。

2.3 默认实现与常见陷阱

UE为一些常见的类提供了该接口的默认实现，但这正是混淆的来源：

• AController类（包括AAIController）： 这是关键！AController默认实现了IGenericTeamAgentInterface。它的GetGenericTeamId()默认返回FGenericTeamId::NoTeamId。AI的行为树、感知组件通常是挂在AAIController上的，而不是APawn。因此，AI的团队身份，默认由其控制器决定。
• APawn类：APawn本身没有默认实现这个接口。这意味着，如果你直接在你的玩家角色蓝图（继承自Character或Pawn）中寻找设置团队ID的地方，是找不到的。
• ACharacter类： 同APawn，没有默认实现。

陷阱1：混淆的归属对象最常见的错误是：开发者给AI的Pawn蓝图设置了团队ID，但AI的感知组件是挂在它的AIController上的。由于控制器默认实现了接口但返回NoTeamId，而Pawn没有实现，感知系统在判断时，会以控制器的团队ID为准。结果就是你明明在Pawn上设置了ID，却完全不起作用。

陷阱2：玩家团队的缺失对于玩家控制角色，通常我们不会给玩家分配一个AIController（除非是多人游戏中的AI队友）。玩家的控制器是APlayerController，它也继承自AController，因此默认实现了接口，但同样返回NoTeamId。如果你没有重写玩家控制器的团队逻辑，那么AI敌人（其控制器）在调用GetTeamAttitudeTowards(PlayerController)时，得到的可能就是中立或未定义的态度，导致过滤。

陷阱3：接口实现冲突如果你同时在Pawn和Controller上都实现了该接口，感知系统会以哪个为准？这取决于感知系统查询的对象。通常，感知系统会查询感知者（AI）和被感知者的“主导”接口实现。对于AI，这个主导者通常是它的Controller。对于玩家，如果没有特殊处理，也可能是Controller。但为了清晰和避免歧义，最佳实践是统一在Controller层级管理团队关系。

3. 排查流程：一步步揪出“失明”真凶

当你的AI对敌人视而不见时，不要盲目地去调整视野距离或角度。请按照以下系统性的流程进行排查，这能帮你节省大量时间。

3.1 第一步：确认感知组件与团队接口的绑定对象

首先，打开你的AI角色蓝图或C++类。

1. 找到AIPerceptionComponent： 它应该在哪里？90%的情况下，它应该被添加在AI的Controller蓝图/类中，而不是Pawn中。这是因为感知、行为树等AI逻辑通常由Controller管理。检查你的AIController的组件列表。
2. 确认接口实现者： 选中这个AIPerceptionComponent所在的Actor（即AIController）。在细节面板的顶部，查看“类设置”。在“实现的接口”部分，你应该能看到GenericTeamAgentInterface。如果没有，你需要手动添加（蓝图）或继承（C++）。
3. 检查玩家方： 同样，找到玩家控制的Pawn和它的PlayerController。检查PlayerController是否实现了GenericTeamAgentInterface。通常需要手动添加。

3.2 第二步：检查团队ID的赋值与获取逻辑

团队关系要成立，双方都必须有一个有效的团队ID，并且逻辑能正确判断敌对关系。

对于AI敌人（AIController）：

• 蓝图： 在AIController蓝图的“事件开始运行”或初始化事件中，你需要调用“设置通用团队ID”节点，为其分配一个ID，例如1（敌方团队）。
• C++： 在你的自定义AAIController类的构造函数或BeginPlay中，调用SetGenericTeamId(FGenericTeamId(1))。
• 关键检查： 实现GetGenericTeamId函数/事件，确保它返回你设置的值。可以临时添加一个打印节点或UE_LOG来输出这个ID，确认赋值成功。

对于玩家（PlayerController）：

• 蓝图： 在PlayerController蓝图中，同样添加GenericTeamAgentInterface，并在初始化时“设置通用团队ID”，例如0（玩家团队）。
• C++： 在自定义APlayerController类中做类似设置。
• 另一种思路（更常见）： 有时我们不想动PlayerController。另一种方法是让玩家的Pawn实现IGenericTeamAgentInterface，并确保AI的感知团队过滤逻辑能正确查询到Pawn的接口。这需要你了解并可能自定义感知过滤逻辑，对新手而言复杂度较高。因此，修改PlayerController通常是更直接稳妥的方案。

3.3 第三步：验证团队态度判断逻辑

仅仅设置了ID还不够，必须确保GetTeamAttitudeTowards函数能正确返回Hostile。

默认逻辑：AController的默认实现（GenericTeamAgentImpl）提供了一套简单的态度判断逻辑：如果对方也有团队ID，且ID不同，则视为Hostile；如果ID相同，则视为Friendly；如果有一方是NoTeamId，则返回Neutral。

你需要验证：

1. AI敌人的团队ID是1。
2. 玩家控制器的团队ID是0。
3. 根据默认逻辑，ID不同，态度应为Hostile。

如何验证？

• 你可以在AI控制器的GetTeamAttitudeTowards函数/事件中插入调试打印。
• 或者，使用控制台命令ai.debug.teaminfo 1来在游戏中显示所有AI的团队信息（需要引擎源码版本支持某些调试功能，或自己实现调试绘制）。

3.4 第四步：调试感知系统本身

如果团队关系确认无误，但AI还是看不见，那么问题可能出在感知配置或更底层的检测上。

1. 开启感知调试： 在游戏运行时，按“~”键打开控制台，输入ai.debug.perception 1。这将在世界中可视化AI的感知状态：
   • 感知者周围会有一个球体表示感知范围。
   • 被成功感知到的Actor会被高亮（通常是红色或绿色）。
   • 你可以清晰地看到，玩家Actor是否进入了AI的“潜在感知列表”，以及是否通过了团队过滤，变成了“当前感知目标”。
2. 检查感知配置参数：
   • 视野半角： 不是360度。确保玩家在AI的前方锥形区域内。
   • 视线通道： 检查AISense_Sight配置中的“视线通道”。默认通常是Visibility和Camera。确保你的玩家角色碰撞体（至少是胶囊体）阻挡了这些通道。如果玩家角色的碰撞被设置为NoCollision或者忽略了这些通道，视线检测会直接穿透。
   • 关于网络热词ue mesh可以用setcollisionenabled(ecollisionenabled::nocollision)的警示： 如果你在代码或蓝图中对玩家的Mesh调用了SetCollisionEnabled(ECollisionEnabled::NoCollision)，这可能会禁用所有碰撞，包括视线检测所需的碰撞！视觉感知依赖于射线/形状检测命中目标Actor的碰撞体。如果Mesh的碰撞被关闭，而胶囊体又不够高（或者视线检测的起始点/终点设置问题），射线可能会从玩家身体“穿过去”而无法命中。解决方案： 对于需要被AI“看见”的角色，至少保留其胶囊体（CapsuleComponent）的碰撞，并确保其阻挡Visibility通道。或者，使用一个专门用于感知检测的简单碰撞体（如一个Box组件），并将其碰撞预设设置为阻挡视线通道。
3. 检查“OnTargetPerceptionUpdated”事件： 在AIPerceptionComponent上，确保你已经绑定了“On Target Perception Updated”事件。这个事件在感知状态改变（发现、丢失、伤害感知等）时触发。即使AI“看见”了，如果这个事件没被触发或没正确处理，行为树也可能没反应。添加一个简单的调试打印到这个事件中，确认它是否被触发。

4. 解决方案：C++与蓝图中的正确配置

理解了原理和排查方法后，我们来看看如何在不同开发模式下正确配置。

4.1 C++ 原生实现方案

对于C++项目，清晰和明确是关键。建议将所有团队逻辑集中在Controller基类中。

第一步：定义团队ID常量在某个全局头文件（如TeamDefinitions.h）中定义团队ID，避免魔法数字。

// TeamDefinitions.h #pragma once #include "GenericTeamAgentInterface.h" namespace ETeam { const FGenericTeamId PlayerTeam(0); const FGenericTeamId EnemyTeam(1); const FGenericTeamId NeutralTeam(2); }

第二步：实现自定义的AIController

// MyAIController.h UCLASS() class MYGAME_API AMyAIController : public AAIController { GENERATED_BODY() public: AMyAIController(const FObjectInitializer& ObjectInitializer = FObjectInitializer::Get()); virtual FGenericTeamId GetGenericTeamId() const override; virtual ETeamAttitude::Type GetTeamAttitudeTowards(const AActor& Other) const override; protected: FGenericTeamId MyTeamId; }; // MyAIController.cpp #include "MyAIController.h" #include "TeamDefinitions.h" #include "GameFramework/Controller.h" AMyAIController::AMyAIController(const FObjectInitializer& ObjectInitializer) : Super(ObjectInitializer) { // 在构造函数中设置默认团队，也可以在其他地方动态设置 MyTeamId = ETeam::EnemyTeam; SetGenericTeamId(MyTeamId); // 调用父类方法设置ID } FGenericTeamId AMyAIController::GetGenericTeamId() const { return MyTeamId; } ETeamAttitude::Type AMyAIController::GetTeamAttitudeTowards(const AActor& Other) const { // 首先，尝试获取其他Actor的团队接口。 // 注意：这里查询的是Other的Controller的团队接口，这是标准做法。 const IGenericTeamAgentInterface* OtherTeamAgent = Cast<IGenericTeamAgentInterface>(Other.GetInstigatorController()); if (OtherTeamAgent == nullptr) { // 如果Other没有Controller或Controller未实现接口，尝试直接Cast Other本身 OtherTeamAgent = Cast<IGenericTeamAgentInterface>(&Other); } if (OtherTeamAgent != nullptr) { // 使用FGenericTeamId::GetAttitude工具函数，它基于ID比较返回态度。 // 这是推荐的方式，遵循了默认的ID不同即敌对的逻辑。 return FGenericTeamId::GetAttitude(GetGenericTeamId(), OtherTeamAgent->GetGenericTeamId()); } // 如果对方根本不是团队代理，则返回中立 return ETeamAttitude::Neutral; }

第三步：实现自定义的PlayerController

// MyPlayerController.h UCLASS() class MYGAME_API AMyPlayerController : public APlayerController { GENERATED_BODY() public: AMyPlayerController(); virtual FGenericTeamId GetGenericTeamId() const override { return ETeam::PlayerTeam; } // GetTeamAttitudeTowards 可以继承AController的默认实现，通常就够用了。 }; // MyPlayerController.cpp #include "MyPlayerController.h" #include "TeamDefinitions.h" AMyPlayerController::AMyPlayerController() { SetGenericTeamId(ETeam::PlayerTeam); }

第四步：配置AIPerceptionComponent在你的AMyAIController::BeginPlay或构造函数中，确保创建并配置了UAIPerceptionComponent，并绑定了回调。

// 在头文件中声明 UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "AI") class UAIPerceptionComponent* AIPerceptionComp; // 在.cpp文件中 #include "Perception/AIPerceptionComponent.h" #include "Perception/AISenseConfig_Sight.h" AMyAIController::AMyAIController() { // ... 其他初始化 ... AIPerceptionComp = CreateDefaultSubobject<UAIPerceptionComponent>(TEXT("AIPerceptionComponent")); // 创建视觉配置 UAISenseConfig_Sight* SightConfig = CreateDefaultSubobject<UAISenseConfig_Sight>(TEXT("Sight Config")); if (SightConfig) { SightConfig->SightRadius = 2000.0f; SightConfig->LoseSightRadius = SightConfig->SightRadius + 500.0f; SightConfig->PeripheralVisionAngleDegrees = 60.0f; SightConfig->DetectionByAffiliation.bDetectEnemies = true; // 关键！必须设置为true SightConfig->DetectionByAffiliation.bDetectNeutrals = false; // 根据需求调整 SightConfig->DetectionByAffiliation.bDetectFriendlies = false; AIPerceptionComp->ConfigureSense(*SightConfig); } // 设置主导感知，通常是视觉 AIPerceptionComp->SetDominantSense(UAISense_Sight::StaticClass()); }

注意DetectionByAffiliation.bDetectEnemies = true这一行，这直接告诉感知系统：“请检测敌对团队的Actor”。这是团队过滤生效的配置开关。

4.2 纯蓝图项目实现方案

对于蓝图项目，操作更直观，但步骤必须完整。

第一步：为AIController蓝图添加接口和设置团队

1. 打开你的AI敌人对应的AIController蓝图（例如BP_EnemyAIController）。
2. 在“类设置”面板，点击“实现的接口”旁边的“+”号，添加“GenericTeamAgentInterface”。
3. 在事件图表中，找到“事件开始运行”节点。
4. 从引脚拉出搜索，调用“设置通用团队ID”节点。在“团队ID”输入引脚上创建一个整数常量（例如1），代表敌人团队。
5. （可选但推荐）为了调试，可以添加一个“获取通用团队ID”节点，连接一个“打印字符串”，在游戏开始时输出ID，确认设置成功。

第二步：为PlayerController蓝图添加接口和设置团队

1. 打开你的PlayerController蓝图（例如BP_PlayerController）。
2. 同样在“类设置”中添加“GenericTeamAgentInterface”。
3. 在“事件开始运行”中，调用“设置通用团队ID”，设置一个不同的整数（例如0）。

第三步：配置AI感知组件

1. 在BP_EnemyAIController的组件面板，确保有一个“AI感知”组件。
2. 选中该组件，在细节面板找到“AI感知”部分。
3. 点击“新增感知配置”，选择“AI视觉配置”。
4. 展开新添加的视觉配置，进行参数设置（半径、角度等）。
5. 关键步骤： 在视觉配置中，找到“检测通过关联”。展开后，确保“检测敌人”被勾选。根据你的游戏设计，决定是否勾选“检测中立者”和“检测友军”。
6. 在“AI感知”组件上，绑定“On Target Perception Updated”事件。这个事件会输出感知到的Actor和刺激类型（如“看见”）。你可以在这里触发行为树的“发现敌人”事件，或者设置黑板键值。

第四步：验证玩家角色碰撞

1. 打开你的玩家角色蓝图（例如BP_PlayerCharacter）。
2. 选中角色的胶囊体组件（CapsuleComponent）。
3. 在细节面板的“碰撞”部分，检查“碰撞预设”。通常使用“Pawn”预设即可。
4. 点击“碰撞预设”旁边的“…”按钮，查看详细响应。确保至少“Visibility”通道的响应是“阻挡”。如果被设置为“忽略”，AI的视线将无法检测到玩家。

4.3 动态团队与复杂关系处理

有些游戏需要动态改变团队（如叛变、招募），或者有更复杂的多边关系（如A打B，B打C，C打A）。IGenericTeamAgentInterface的默认简单ID比较逻辑就不够用了。

解决方案：重写GetTeamAttitudeTowards无论是C++还是蓝图，你都可以完全重写这个函数，实现自定义的关系逻辑。

• C++： 就像前面示例中那样，重写虚函数，用你自己的规则（如查表、基于阵营声望计算等）返回ETeamAttitude。
• 蓝图： 在实现了接口的蓝图中，你可以重写“获取团队态度朝向”事件。该事件会提供“其他Actor”作为输入，你需要返回一个“团队态度”枚举值。你可以在这里编写复杂的蓝图逻辑来判断关系。

示例（蓝图动态团队）：假设有一个“声望系统”，AI对玩家的态度基于声望值。

1. 在AIController蓝图中，重写“获取团队态度朝向”事件。
2. 从“其他Actor”引脚，尝试转换为玩家Controller或Pawn。
3. 如果转换成功，获取该玩家相对于此AI的声望值。
4. 使用分支节点：如果声望< -50，返回“敌对”；如果声望> 50，返回“友好”；否则返回“中立”。
5. 这样，即使团队ID没有改变，AI的感知行为也会根据动态声望发生变化。但请注意：这需要你在感知配置中勾选“检测中立者”或“检测友军”，否则即使返回了对应态度，感知组件也可能因为配置而忽略。

5. 高级排查与常见陷阱深潜

即使按照上述步骤配置，一些隐蔽的问题仍可能导致感知失败。这里深入几个高级排查点。

5.1 感知更新的频率与性能优化

AIPerceptionSystem有一个全局的感知更新频率，并不是每帧检测所有AI。这可能导致发现目标有轻微延迟，但在极端情况下，如果更新间隔设置过长或性能受限，可能看起来像“没看见”。

• 控制台命令：ai.perception.system.interval可以查看或设置感知系统更新间隔（秒）。默认值通常是0.1秒（10Hz）。在开发阶段，可以临时设为0.0来获得即时更新，但发布前请恢复。
• 调试： 如果怀疑是更新频率问题，可以尝试在AIPerceptionComponent上调用ForceNetUpdate()或设置其PeripheralVisionAngleDegrees为一个极大值进行测试，但这并非根本解决之道。通常默认频率是足够的。

5.2 网络同步问题（多人游戏）

在多人游戏中，团队ID和感知状态需要在服务器和客户端之间同步。

• 团队ID同步：FGenericTeamId本身不是UPROPERTY，默认不会复制。如果你在客户端设置团队ID，服务器是不知道的。必须在服务器端设置团队ID。通常是在Controller的BeginPlay中，通过HasAuthority()判断是否为服务器端，再进行设置。
• 感知组件同步：UAIPerceptionComponent默认只在服务器端有效。AI的感知决策应该在服务器上进行，然后将结果（如发现目标）通过RPC或复制状态同步到客户端，用于播放动画、音效等表现。检查你的AI逻辑是否运行在服务器端。
• 客户端预测： 对于需要快速反应的AI（如FPS游戏的机器人），纯服务器感知可能有延迟。UE提供了UAIPerceptionComponent的客户端预测功能，但配置复杂。确保你了解其网络角色和复制设置。

5.3 与其他系统的冲突

• 行为树与黑板： AI“看见”了，但行为树没反应？检查“OnTargetPerceptionUpdated”事件是否正确地设置了黑板键值（如“TargetActor”）。同时，检查行为树中的“装饰器”（Decorator）是否对目标有额外的过滤条件（如距离、生命值等），可能感知到了，但被装饰器过滤掉了。
• 导航与寻路： 有时AI感知到了目标，但因为它当前的位置无法生成到达目标的导航路径（NavMesh缺失或阻挡），AI逻辑可能会清除目标。这看起来也像“丢失了感知”。使用ai.debug.navigation命令检查NavMesh覆盖情况。
• 插件影响： 一些AI或战斗插件可能会覆盖或修改默认的感知团队逻辑。检查你是否使用了此类插件，并查阅其文档。

5.4 针对网络热词的特别提醒

• ue mesh可以用setcollisionenabled(ecollisionenabled::nocollision)： 再次强调，这对AI感知是致命的。视觉感知需要碰撞查询。如果你因为渲染或物理原因必须禁用Mesh碰撞，请确保角色有一个替代的碰撞体用于感知检测，并正确设置其碰撞通道。
• ue subsystem： 如果你使用Gameplay Subsystem来管理全局团队关系，请确保在感知系统查询团队接口时，你的子系统逻辑能被正确访问到。团队接口的实现应尽可能轻量和直接，避免在GetTeamAttitudeTowards中做复杂的查询，因为该函数可能被高频调用。
• ue半透明材质显示穿透： 这与AI感知无关，是渲染问题。AI的视觉感知基于物理碰撞和几何体，与材质是否半透明、是否被渲染无关。一个完全透明的Actor，只要其碰撞体存在且阻挡Visibility通道，就能被AI“看见”。

6. 调试技巧与实用控制台命令

掌握一些内置的调试工具，能极大提升排查效率。

1. ai.debug.perception 1： 这是最重要的命令。显示所有AI的感知范围、当前感知到的目标（绿色=友好，红色=敌对，蓝色=中性）、以及感知刺激源。数字可以调整显示级别（如2显示更多细节）。
2. ai.debug.teaminfo 1： 在AI头顶显示其团队ID。对于验证团队ID是否正确设置非常有用。
3. ai.debug.navigation 1： 显示导航网格（NavMesh）边界和AI的当前路径。用于排除因寻路问题导致的行为异常。
4. DisplayAll和Stat AI： 在“统计”HUD中查看AI系统开销和数量。
5. 蓝图调试：
   • 在GetGenericTeamId和GetTeamAttitudeTowards事件中插入“打印字符串”节点。
   • 在“On Target Perception Updated”事件中，打印感知到的Actor名称和刺激类型（刺激.类型）。
   • 使用“调试摄像机”附着到AI控制器上，以AI的视角观察世界。
6. C++ 调试：
   • 在GetGenericTeamId和GetTeamAttitudeTowards函数中使用UE_LOG(LogTemp, Warning, TEXT("..."))。
   • 在UAIPerceptionComponent::OnPerceptionUpdated委托的绑定函数中打日志。

排查“AI看不见”问题，是一个从宏观到微观、从逻辑到配置的系统性过程。IGenericTeamAgentInterface是这道门的第一个锁匙。很多开发者，包括我自己在早期，都曾在这个问题上耗费数小时甚至数天，最终发现只是一个复选框没勾，或者团队ID设错了对象。希望这份从原理到实操、从排查到解决的指南，能帮你快速定位问题，让你的AI们拥有一双真正“明亮”的眼睛。记住，在UE的AI世界里，没有无缘无故的爱与恨，一切感知的背后，都是数据与规则的精确计算。