小队、角色与单位参数

小队参数围绕“组织关系”展开：Definition 决定一种小队应该如何组成，SquadComponent 维护运行时成员和角色真源，UnitComponent 镜像自己在小队里的身份，slot assignment 和 Movement Intent 把组织关系连接到阵型与移动系统。

相关文档：小队功能与 Movement Intent 生成见小队系统，阵型空间与导航自适应见阵型系统，配置步骤见配置小队、阵型与槽位，二开入口见小队、角色与 AI 扩展点。

`UGAIS_SquadDefinition`

UGAIS_SquadDefinition 是一种小队类型的静态模板。它不保存运行时成员，而是定义小队宿主、默认单位、角色、可用阵型、行为基线、槽位评分和 Movement Intent 默认值。

参数	用途	何时调整	误配风险
`SquadActorClass`	小队运行时宿主 Actor，必须实现 `IGAIS_SquadActorInterface`。	每种小队需要不同宿主、组件组合或表现时。	未实现接口或缺少运行时组件会导致初始化契约失败。
`DefaultTeamId`	初始化时应用到小队宿主的默认队伍 ID。	小队有固定阵营，或生成时需要继承某个阵营语义。	与项目队伍真源冲突会影响过滤、敌我判断和 Tactical Assignment。
`AvailableFormations`	小队可使用的阵型列表，顺序影响 trait-query 优先匹配。	小队需要切换防御、推进、散开等阵型时。	为空或类加载失败会让 Formation ready 无法收敛。
`DefaultUnits`	创建或补齐小队时使用的单位模板。	通过 `CreateSquad` 自动生成固定编队，或补员时参考默认构成。	UnitClass 缺失、DesiredRole 不存在会导致空岗或角色填充失败。
`InitialFormation`	显式初始阵型；必须同时存在于 `AvailableFormations`。	小队初始站位不能只靠可用阵型顺序推断时。	不在可用列表中会导致初始化或编辑器校验问题。
`AvailableRoles`	小队可用角色列表；`RoleTag` 是唯一身份。	需要岗位容量、兵种限制、角色优先级和角色 StateTree 时。	角色缺失或重复会导致默认单位、角色分配和槽位匹配异常。
`DefaultSquadStateTree`	小队宿主自己的基线 StateTree。	小队整体需要巡逻、推进、撤退、切阵等高层行为时。	把单位执行细节塞入宿主 StateTree 会让职责混乱。
`DefaultUnitStateTree`	Unit 加入小队后可使用的默认 Squad 层行为回退。	角色没有专用 StateTree，但加入小队后仍需要统一行为时。	未配置回退会让部分单位加入小队后没有 Squad 层行为。
`SlotAssignmentSettings`	Unit 到 Formation Slot 的评分规则。	单位站位不符合语义、距离或稳定性预期时。	权重不平衡会造成频繁换位、错位或 `NoLegalSlot`。
`DefaultMovementIntentResponseSettings`	每个 Movement Intent draft 的默认起停、速度响应和预测参数。	调整跟随阵型的起停距离、速度和短时预测时。	起停阈值不合理会造成抖动、停滞或长期追赶。
`DefaultMovementIntentTags`	每个 Movement Intent draft 的默认项目语义标签。	Driver、动画或项目移动层需要识别“面向移动方向”“到位后朝向”等语义时。	标签语义不清会让 Driver 决策难以解释。
`MovementIntentDriver`	小队批量刷新 Intent 后应用到单位移动系统的策略对象。	希望 GAIS 自动把 Intent 写入 CharacterMovement、GMS、Mover 或自定义移动层时。	Driver 与项目移动真源抢控制会导致状态互相覆盖。

`FGAIS_SquadUnitInfo`

FGAIS_SquadUnitInfo 是默认单位模板。它用于“由 Definition 生成小队”或“按模板补齐小队”的场景。

参数	用途	何时调整	误配风险
`UnitClass`	期望生成或填充的单位 Actor 类。	小队创建时需要自动生成成员。	类未加载或没有 UnitComponent 会导致成员无效。
`DesiredRole`	该单位期望担任的初始角色。	固定编队希望单位出生就占据某个岗位。	角色不存在或资格不满足会被重分配、空置或触发缺失策略。
`OverrideRoleAI`	单位级角色 StateTree 覆盖。	同一角色下不同单位需要不同 Squad 层行为时。	覆盖过多会让角色默认 AI 难以维护。

`FGAIS_SquadRoleInfo`

角色配置决定“什么单位可以担任什么岗位，以及岗位在填充和槽位争用中的优先级”。它会影响角色占用、StateTree 分配、槽位语义匹配和重组策略。

参数	用途	何时调整	误配风险
`RoleTag`	稳定岗位身份，通常位于 `GAIS.Role`。	每个可被小队识别的岗位都需要一个稳定标签。	与 SlotTags 或 CommandIntent 标签混用会让语义边界模糊。
`AllowedClasses`	限制可担任该角色的 Actor 类。	只有特定兵种、载具或角色类能担任岗位时。	留空表示不限制；误填会让单位无法补位。
`RequiredTags` / `BlockTags`	通过 GameplayTags 限制角色资格。	按装备、Buff、职业、状态判断岗位资格时。	标签体系不一致会让 `IsQualifiedOfRole` 结果难以解释。
`MaxNum`	同时担任该角色的最大人数。	前排、远程、治疗等岗位有容量上限时。	与 DefaultUnits 数量冲突会导致多余单位无角色。
`Priority`	角色填充和槽位争用优先级；数值越高越先获得角色/槽位机会。	队长、护卫、治疗等角色需要优先稳定时。	过高会让普通角色长期拿不到更合适的槽位。
`bRequired`	小队期望该角色被填满。	缺少该岗位会影响小队能力但不一定立即崩溃时。	过度标 required 会让普通伤亡频繁触发补员或降级。
`StateTree`	担任该角色的默认 Squad 层 StateTree。	不同岗位需要不同行为时。	把完整战斗流程塞进角色 StateTree 会和 Command/Queue 产生职责重叠。

`UGAIS_SquadComponent`

UGAIS_SquadComponent 是运行时小队真源。它负责初始化 Definition、维护成员 FastArray、角色占用、容量状态、Formation ready 等待、槽位重分配、Movement Intent 刷新和成员事件。

参数或能力	用途	何时使用	误配风险
`bInitializeOnBeginPlay`	BeginPlay 时用配置的 Definition 自动初始化。	关卡中手摆小队宿主，进入游戏自动成队。	Definition 未配完整会在 BeginPlay 暴露初始化失败。
`GetMaxUnitCount` / `GetRemainingUnitCapacity` / `IsFull`	查询当前 Formation 槽位形成的硬容量、剩余容量和满员状态。	UI、调试或 AI 判断是否还能招募单位。	容量会随当前 Formation 槽位数变化；不要缓存旧值或只看角色容量。
`UnitsContainer`	小队成员运行时真源。	查询成员、复制成员变化、触发 add/remove/change 事件。	绕过 AddUnit/RemoveUnit 直接改会破坏镜像和事件。
`HasUnit` / `HasUnits` / `HasAnyUnit`	查询一个、全部或任一 Unit 是否存在于成员真值容器。	UI 启用操作、服务端授权检查、批量改编前。	`HasUnits` 对空输入或无效 Unit 返回 false；不要把“无输入”解读成“全部属于”。
`RoleContainer`	角色占用运行时真源。	判断角色是否填满、必需角色是否缺失。	和 Definition 的 `AvailableRoles` 不一致会导致补员策略错误。
`AddUnit` / `RemoveUnit` 及批量版	服务端增删成员。	权威逻辑处理招募、离队、死亡、召唤物加入。	客户端直接调用无效；绕过会导致 Unit 投影不同步。
`ServerAdd/RemoveUnit(s)`	由拥有小队宿主的客户端请求服务端改编。	玩家编队界面从 owning client 发起成员调整。	网络所有权不在调用客户端时，RPC 请求不会成为通用授权通道。
`AssignRoleToUnit(s)` / `RevokeRole...`	服务端调整一个或多个 Unit 的角色。	权威侧玩家换岗位、AI 重组、关键角色补位。	不触发后续刷新会让槽位和 StateTree 保持旧状态。
`ServerAssignRole...` / `ServerRevokeRole...`	由 owning client 请求服务端调整角色。	玩家可编辑自己拥有的小队角色时。	项目仍需在服务端保留授权规则，不应只依赖调用节点是否可见。
`GetInitializationState` / `IsSquadActive`	观察初始化处于未开始、等待空间上下文、Active 或失败等生命周期阶段。	创建小队后决定何时读取成员槽位、下发小队行为或显示就绪状态。	不要通过私有收敛函数或 Formation 是否非空猜测小队已经可用。
`OnInitializationStateChangedEvent` / `OnSquadActivatedEvent`	订阅初始化阶段变化和首次进入 Active。	UI、项目逻辑或测试需要事件驱动地等待小队可用时。	只轮询成员数量可能在 Formation 尚未 ready 时过早继续。
`IssueSquadCommand`	通过小队宿主 CommandSystem 下发命令。	玩家或 AI 把小队当成命令入口。	它不是绕过 CommandSystem 的执行路径。
`ServerDismiss` / `ServerChangeSquadTeamId` / `ServerIssueSquadCommand`	请求服务端解散、改队伍 ID 或下发小队命令。	操作从拥有小队宿主的客户端发起。	非拥有客户端应改走 PlayerController/项目 RPC，否则服务端不会得到可用请求。
`SetUnitSquadStateTree` / `ClearUnitSquadStateTree`	设置或清除 Unit 的 Squad 层行为。	单位加入/离开小队或角色变化时。	不清除 Squad 层会让离队单位继续被小队行为覆盖。

`UGAIS_SquadSubsystem`

UGAIS_SquadSubsystem 是世界级小队注册表和创建辅助。它适合项目逻辑、蓝图或上层系统创建、查找和重组小队。

入口	用途	适用场景
`CreateSquad`	按 SquadDefinition 生成小队宿主，可选择生成默认单位。	固定编队、刷怪或运行时生产单位。
`CreateSquadFromActors`	创建小队宿主并原子招募已有 Actor。	玩家框选、剧情编队、关卡预放单位组队。
`CreateSquadFromNearbyUnits`	从附近未入队单位招募指定数量成员。	区域集结、临时战斗组、自动编队。
`GetUnassignedUnits`	查询当前无小队的已注册单位。	单位平时独立，之后可被小队吸收。
`GetAutomaticallyRecruitableUnits`	查询通过 Unit 自动招募策略的未入队单位。	自动补员、重组或区域招募前筛选候选。
`TryReorganizeSquad`	招募附近单位并尝试补齐缺失角色。	战斗中补员、残兵重整。
`MergeSquads`	主小队吸收副小队，主小队保留身份和高层语义。	两队会合、玩家合并选择组、AI 收编残余单位。

`UGAIS_UnitComponent`

UGAIS_UnitComponent 让 Actor 能被小队识别，并镜像小队分配结果。它也是默认命令意图解析器；最终命令必须通过候选 Pawn/Character 上的 UGAIS_CommandSystemComponent 执行。

参数	用途	何时调整或读取	误配风险
`CommandIntentMappings`	默认 IntentTag 到命令引用映射。	Tactical Assignment 产出命令意图后，需要 Unit 解析成具体命令。	未配置会导致 `NoResolvedCommand`。
`OwningSquad`	当前所属小队，由服务端复制。	UI、调试、移动 Driver 判断单位是否在队。	不应作为编辑期配置真源。
`CurrentRole`	从 Squad entry 镜像出的当前角色。	UI 显示岗位、移动/动画逻辑读取岗位。	直接写不会改变 SquadComponent 内部角色真源。
`AssignedSlotId`	从 Squad entry 镜像出的阵型槽位 ID。	UI、调试、移动系统读取当前站位。	直接写不会改变槽位分配。
`MovementIntent`	从 Squad entry 镜像出的最近移动建议。	外部移动系统消费期望位置、速度和朝向。	把它当移动真源会和 CharacterMovement/GMS 等系统冲突。
`ServerLeaveSquad`	由拥有 Unit Actor 或其 Owner 链的客户端请求离队。	玩家控制单位主动离队时。	对非拥有 Unit 调用时无法替代服务端授权逻辑。

`FGAIS_FormationSlotAssignmentSettings`

槽位分配设置决定 Unit 和 Formation Slot 如何匹配。输入包括 Unit/Actor tags、当前角色标签、槽位 SlotTags、槽位权重、单位到槽位距离和上一次槽位。

参数	用途	何时调整	误配风险
`SlotTagMatchPolicy`	决定 SlotTags 是只加分、要求任意匹配、要求全部匹配，还是忽略。	想让角色/单位必须站到指定语义槽位时。	RequireAll 过严会产生 `NoLegalSlot`；Ignore 会让语义标签失效。
`bUseHierarchicalTagMatching`	是否启用 GameplayTag 层级匹配。	使用父子标签组织角色和槽位语义时。	关闭后父子层级不再匹配，可能降低命中率。
`SlotWeightScoreMultiplier`	槽位 Weight 的评分倍率。	想让关键槽位优先被占用时。	过高会压过标签和距离。
`MatchingTagScore`	每个 Unit/Slot 标签匹配的加分。	想强化岗位与槽位语义匹配时。	过低会让标签看似配置了但不影响结果。
`DistanceCostPer100Units`	每 100 UU 距离扣分。	想减少远距离换位和穿插时。	过高会让单位贪近而站错语义位置。
`StableSlotScore`	保留原槽位的稳定性加分。	想减少频繁换位时。	过高会让阵型变化或角色变化后仍不愿重排。

`FGAIS_MovementIntentResponseSettings`

Movement Intent 响应设置决定小队如何把槽位目标转成移动建议。它不直接移动单位，而是为 Driver 或项目移动系统提供期望位置、速度、响应强度和到位状态。UGAIS_SquadDefinition.DefaultMovementIntentResponseSettings 会初始化每个 Unit 的 draft，随后 Squad/Unit Modifier 可以继续覆盖。

参数	用途	何时调整	误配风险
`MoveStartDistance`	静止单位超过该距离才开始移动。	避免单位因小误差频繁起步。	太小会抖动，太大导致明显偏离槽位仍不动。
`MoveStopDistance`	移动单位低于该距离停止并视为到位。	控制站位精度和停止条件。	大于 Start 或设置过大，会让单位停得太松。
`ResponseDistance`	距离误差达到该值时响应强度为 1。	调整追赶速度随距离变化的敏感度。	太小会快速满速，太大则追赶迟钝。
`ResponseCurve`	可选曲线，重映射响应强度。	需要更平滑或更激进的加速曲线时。	曲线输出不合理会造成速度跳变。
`NearDesiredSpeed` / `FarDesiredSpeed`	近处和远处期望速度。	调整接近槽位和远距追赶节奏。	Far 小于 Near 的预期不清会让速度曲线难调。
`MinDesiredSpeedWhenMoving`	移动时最低期望速度。	避免响应很低时移动系统停滞。	太高会让单位接近槽位时冲过头。
`DesiredLocationPredictionTime`	用小队平均速度预测目标位置。	小队宿主持续移动，单位需要前馈追随时。	太高会让单位追向过远的预测点。

Movement Intent Modifier 与最终 Intent

Formation 首先提供槽位世界位置和朝向，创建 FGAIS_MovementIntentResolveState；这个 draft 默认带上 Definition 的响应设置、默认标签和小队平均速度预测。随后系统先执行 Squad 级 Modifier，再执行 Unit 级 Modifier；同一 scope 内 PriorityWithinScope 越高越晚执行，因此更高优先级更适合做最终覆盖。

表面	用途	何时调整	误配风险
`UGAIS_MovementIntentModifierSet`	一组有序、不可变的 Modifier 模板，可作为共享资产或 Inline Set 使用。	多个状态或小队复用同一套移动语义时。	空集合或无效子对象会被运行时拒绝。
`UGAIS_MovementIntentModifier.ModifyMovementIntent`	纯函数式修改 draft。	冲锋、散开、守点、减速、暂停 Driver 等临时状态。	在回调里改成员、阵型、命令或再次 push/pop Modifier 会被拒绝或触发稳定性保护。
`PushSquadMovementIntentModifier`	给整支小队注册 Modifier，返回 `FGAIS_MovementIntentModifierHandle`。	StateTree 进入“冲锋/隐蔽/压制”这类小队状态时。	Owner 无效、非权威端、小队未 Active 或 Set 无效都会返回无效 Handle。
`PushUnitMovementIntentModifier`	给单个成员注册 Modifier。	某个单位被减速、眩晕、持盾或单独脱离队形时。	Unit 不属于该小队时注册失败。
`PopMovementIntentModifier` / `RemoveMovementIntentModifiersByOwner`	按 Handle 或 Owner 清理运行时绑定。	StateTree 退出状态、Actor EndPlay、技能结束或异常清理。	忘记清理会让旧状态继续影响最终 Intent。
`MovePolicy`	决定 `bShouldMove` 使用自动滞回、强制移动或强制停止。	冲锋强制推进、定点蓄力停住、普通跟随自动起停。	和 Driver/命令层控制权冲突会造成拉扯。
`DriverPolicy`	决定最终 Intent 是否交给 Driver 应用。	命令层或项目移动层临时接管移动时可设为 Suspended。	误挂 Suspended 会让 Intent 正确但单位不被 Driver 驱动。
`PredictionVelocity`	参与 `DesiredLocationPredictionTime` 的目标前推。	小队整体高速移动或需要前馈追随时。	预测过强会让单位追向过远点。
`MovementIntentTags`	传递给 Driver、动画或项目移动层的语义标签。	控制面向移动方向、到位后朝向、冲锋动画层等。	标签约定不统一会让消费端行为不稳定。

最终 FGAIS_SquadUnitMovementIntent 会记录 RawDesiredLocation、预测后的 DesiredLocation、DesiredOrientation、DesiredSpeed、DesiredVelocity、bShouldMove、bIsInDesiredLocation、MovementIntentTags 和 DriverPolicy。它会写回 Squad entry 并镜像到 UnitComponent。

目录