队伍身份与项目策略

队伍身份系统解决的是“GAIS 如何判断一个 Actor 属于哪一方、和另一个 Actor 是友方还是敌方、这些规则应该由 GAIS 还是项目已有系统负责”的问题。它让命令校验、Tactical Assignment、小队招募和调试都能回到同一套队伍查询策略。

这个系统解决什么问题

很多项目已经有自己的阵营、队伍、仇恨、玩家所有权或 GAS 关系规则。GAIS 不应该强迫项目把这些规则搬进插件内部。UGAIS_TeamAgentComponent 提供轻量默认真源，UGAIS_ProjectPolicy 提供项目级策略入口，让 GAIS 可以在默认模式和项目自定义队伍系统之间切换。

如果项目没有阵营系统，直接使用 TeamAgent 就能跑通敌我关系。如果项目已有成熟真源，就应该把 GAIS 通过 ProjectPolicy 接到那个真源，而不是维护第二套队伍状态。

运行原理和关键链路

UGAIS_TeamAgentComponent 是 GAIS 默认队伍身份真源。它持有复制的 TeamId，提供 SetTeamId、GetTeamId、HasValidTeamId 和 OnTeamIdChangedEvent。开启镜像后，它会把 TeamId 同步给 Owner 或关联 Controller 中实现 IGenericTeamAgentInterface 的对象。

UGAIS_ProjectPolicy 是项目级策略 CDO，用于统一查询和写入队伍身份。默认策略会按 Actor、Controller、Pawn、TeamAgent、IGenericTeamAgentInterface 等路径解析 TeamId；项目可以覆写 ResolveTeamAgent、HasGenericTeamId、GetGenericTeamId、SetGenericTeamId 和 GetGenericTeamQuerySource。

UGAIS_AIBlueprintHelperLibrary 是蓝图侧统一入口。GetGenericTeamId、SetGenericTeamId 和 GetTeamAttributeTowards 都通过当前 ProjectPolicy 工作，避免不同系统各查各的。

最小使用方式

如果项目还没有队伍系统，在 Pawn 或 Controller 上添加 UGAIS_TeamAgentComponent。
在服务端调用 SetTeamId 设置队伍；需要 Owner/Controller 镜像时保持 bApplyTeamIdToMirrors 开启。
如果项目已有队伍真源，创建 UGAIS_ProjectPolicy 子类，覆写队伍查询和写入逻辑。
在 UGAIS_DeveloperSettings.ProjectPolicyClass 指向项目策略类。
使用 UGAIS_AIBlueprintHelperLibrary::GetTeamAttributeTowards 或 GameplayDebugger 验证 ContextActor、CandidateActor、TargetActor 的敌我关系。

常用入口能做什么

入口	典型用途
`UGAIS_TeamAgentComponent::SetTeamId`	服务端设置 Actor 的复制队伍 ID。
`UGAIS_ProjectPolicy::SetGenericTeamId` / AI Blueprint Helper	在权威端写入项目策略解析出的队伍真源。
`GetTeamId` / `HasValidTeamId`	读取 TeamAgent 自身保存的队伍状态。
`OnTeamIdChangedEvent`	UI、视觉表现或调试状态响应队伍变化。
`UGAIS_ProjectPolicy::GetGenericTeamId`	按项目策略读取任意 Actor 的队伍 ID。
`SetGenericTeamId`	把队伍 ID 写回项目认可的队伍真源。
`GetGenericTeamQuerySource`	调试当前 TeamId 是从 self、controller、pawn 还是 interface 解析出来的。
`UGAIS_AIBlueprintHelperLibrary::GetTeamAttributeTowards`	蓝图侧查询两个 Actor 的敌我关系。

它影响哪些系统

CommandDefinition 可以用队伍关系判断目标是否有效，例如攻击命令通常只接受敌对目标，治疗命令通常只接受友方目标。

Tactical Assignment 的 Source 和 Filter 会用队伍关系缩小候选，例如只让友方单位参与分配，或只选择敌对 Actor 作为目标。

SquadSubsystem 在招募、重组和按队伍过滤单位时，会读取 Squad 与候选 Unit 的队伍态度。

GameplayDebugger 会显示队伍信息，帮助判断“为什么候选被过滤”或“为什么命令目标无效”。

常见配置入口

入口	作用
`UGAIS_TeamAgentComponent`	GAIS 默认队伍 ID 真源和镜像同步入口。
`UGAIS_ProjectPolicy`	项目级队伍查询、写入和策略适配入口。
`UGAIS_DefaultProjectPolicy`	未配置项目策略时的默认实现。
`UGAIS_DeveloperSettings.ProjectPolicyClass`	指定当前项目使用哪套策略。
`UGAIS_AIBlueprintHelperLibrary`	蓝图侧查询 TeamId、敌我关系、Blackboard 和导航相关辅助入口。

使用注意

建议在 Pawn/Controller 链上只放一个明确队伍真源。如果 Pawn 和 Controller 都有 TeamAgent，默认语义是 self-wins，不会自动合并或报警。这个规则能避免 GAIS 擅自改项目关系，但也意味着双真源歧义需要项目自己避免。

TeamAgent 和 ProjectPolicy 只解决身份查询，不直接实现仇恨、感知、伤害归属或 UI 阵营表现。那些系统可以读取同一 TeamId，但不应该把自己的状态偷偷写成第二套 GAIS 队伍真源。

接入已有项目阵营系统

项目已有队伍真源时，创建无状态 UGAIS_ProjectPolicy 子类并在 Settings 选择它。覆写 Resolve/Get/Set/Has TeamId，让 GAIS 读取已有 Pawn、Controller 或接口；不要把运行时 Actor 缓存在 Policy CDO。默认查询会区分 Self、Controller、Pawn 的 TeamAgent/接口来源，GetGenericTeamQuerySource 可用于调试实际命中的路径。

若采用 GAIS TeamAgent，选择 Pawn/Controller 链上唯一真正拥有身份的一侧，服务端用 SetTeamId 写入并让复制/镜像通知观察者。双侧都挂 TeamAgent 时是 self-wins，不会合并；这必须在项目架构中避免。

什么时候看后续文档

接入流程见接入队伍身份与阵营。字段细节见队伍身份与调试参数。如果要接项目阵营系统、覆写 ProjectPolicy、监听 TeamId 变化或集成 GAS，读队伍身份与 GAS 集成扩展点。队伍关系导致 Tactical Assignment 过滤异常时，读排错流程。

目录