阵型、槽位与导航参数

FormationId

阵型稳定身份，不是本地化显示名。

UI 保存选择、调试输出、存档或数据表引用阵型时。

与显示名混用会导致本地化或重命名后引用失效。

DisplayName / Description / Icon

玩家或编辑器展示信息。

需要阵型选择面板、工具提示或调试摘要时。

只影响展示，不应被游戏逻辑当作身份。

FormationTraits

描述阵型整体战术语义。

StateTree、AI 或 UI 需要按“防御、推进、散开”等语义筛选阵型时。

和 SlotTags 混用会让“阵型整体语义”和“槽位局部语义”混乱。

bHasDirection

是否使用阵型整体方向作为单位朝向来源。

盾墙、楔形、行进队列通常开启；环形、包围、散点可关闭。

方向语义错误会导致单位朝向集体错误，或忽略槽位自身旋转。

SlotDefinitions

编辑期槽位列表，包含 SlotId、Weight、SlotTags、Location、Rotation。

每个阵型资产都必须配置。

SlotId 不稳定会破坏复制、重分配、Unit 镜像和调试定位。

SlotDefinitionMap

保存前生成的 SlotId 查询表。

只读理解即可，用于按 SlotId 查定义。

手动维护会造成数组和查询表不一致。

SlotId

槽位稳定身份，不等于数组下标。

任何可被单位分配、复制、保存、调试的槽位都需要稳定 ID。

重排数组后改 ID 会让单位保槽、调试和复制结果变得不可解释。

Weight

槽位重要性，会参与小队 slot assignment 评分。

前排中心位、护卫位、关键火力位需要更高优先级时。

权重过高会压过标签和距离，让不适合的单位抢关键槽。

SlotTags

槽位局部语义，通常位于 GAIS.Formation.Slot。

希望前排/后排/内圈/外圈/远程位与 Unit 或 Role 匹配时。

标签体系不清会造成 NoLegalSlot 或角色站错位置。

Location

相对阵型 pivot 的本地坐标。

调整阵型形状、单位间距和站位深度时。

间距过小会造成拥挤；过大则 Movement Intent 长期追赶。

Rotation

相对阵型 pivot 的本地旋转。

阵型无整体方向，或每个槽位需要独立朝向时。

与 bHasDirection 预期相反会导致单位看向错误方向。

AvailableFormations

当前宿主可切换的阵型列表。

小队或阵型宿主需要多种站位模式时。

列表为空会导致无法 EnsureCurrentFormation。

CurrentFormation

当前运行时阵型。

由服务端直接设置，或通过 Trait Query 选择。

试图在客户端直接改会无效；不在 AvailableFormations 中也不会切换。

ServerSetCurrentFormation / ServerSetCurrentFormationByTraitQuery

请求服务端按类或 Traits 切换阵型。

请求从拥有组件 Actor 或 Owner 链的客户端发起。

调用客户端没有网络所有权时，RPC 不能替代项目 PlayerController 转发和服务端授权。

FormationSpread

运行时缩放槽位本地坐标。

同一阵型要适配不同体型、人数规模或战斗距离时。

过大让单位追赶过久；过小造成碰撞拥挤。

Container

当前阵型的复制槽位运行时容器。

组件内部保存 SlotId、定义快照、导航偏移和预览变换时。

外部绕过查询 API 直接改容器会破坏事件和复制语义。

QuerySlots / FGAIS_FormationSlotQuery

按角色、标签、距离等条件查询不可变 runtime view。

蓝图、EQS、小队槽位分配或调试需要读槽位候选时。

把查询结果当成可写状态会破坏 FormationComponent 的单一真源。

FindSlotRuntimeView

按稳定 SlotId 读取单个槽位 runtime view。

Movement Intent、调试或 UI 需要定位某个成员的槽位。

找不到时应回到 Formation ready、SlotId 和布局版本排查。

FindAvailableFormationByTraitQuery

按 FormationTraits 查询阵型。

StateTree 或 AI 想按战术意图切阵时。

Traits 配置过宽会总是命中优先级靠前的阵型。

OnFormationReadyEvent

当前阵型槽位容器可供消费时广播。

小队初始化需要等待空间真源时。

忽略 ready 契约会让小队提前分配空槽位。

SlotId

当前运行时槽位身份。

Unit 镜像、调试、槽位查找。

不能假设它等于数组下标。

Definition

从阵型资产复制出的槽位定义。

读取 Weight、SlotTags 和本地布局语义。

不应在运行时把它当资产编辑入口。

WorldTransform

应用 pivot、spread 和导航偏移后的最终站位与朝向。

小队生成 Movement Intent、调试站位、可视化预览时。

直接使用 Definition.Location 会绕过导航自适应。

LocationOffset

导航投射产生的运行时局部偏移。

排查坡地、台阶、NavMesh 边缘站位时。

把它写回资产会污染设计期阵型。

bEnabled

是否启用运行时导航投射。

单位需要真实沿 NavMesh 到达槽位时建议开启。

关闭后槽位可能落在不可走区域。

UpdateIntervalSeconds

导航自适应脏检查间隔。

大阵型或频繁移动时用于控制查询成本。

太低会增加 NavMesh 查询；太高会让槽位位置滞后。

ReprojectionDistanceThreshold

pivot 移动超过距离后重投射。

阵型跟随移动宿主时。

太小会频繁投射；太大可能在地形变化处仍使用旧偏移。

ReprojectionYawThresholdDegrees

pivot Yaw 变化超过角度后重投射。

阵型旋转会显著改变槽位位置时。

太大可能转向后槽位仍停留在旧投射结果。

NavigationQueryFilterClass

投射使用的导航 QueryFilter。

不同单位、小队或地形规则有不同可走区域时。

Filter 不匹配会把槽位投到单位实际不可达的位置。

ProjectionStartHeightOffset

投射前抬高目标点。

地面高度变化或槽位可能略低于地表时。

太小容易投射失败；太大可能命中不期望的上层 NavMesh。

ProjectionQueryExtent

投射查询范围。

坡地、台阶、桥面、复杂地形中需要扩大 Z 或 XY 时。

范围过小找不到 NavMesh；过大可能投到错误区域。

ProjectedSlotZOffset

投射成功后的额外 Z 偏移。

预览点或移动目标需要略高于地面时。

过高会让可视化或移动目标悬空。

bUseFallbackProjection

投射失败时向阵型 root 方向尝试备用采样。

NavMesh 边缘、桥边、障碍旁建议开启。

关闭后失败槽位会更可能保留不可用偏移。

FallbackSearchRadius

备用采样允许移动的最大距离。

大阵型或地形破碎时可适当增大。

太大可能让槽位过度向中心收缩，破坏阵型形状。