命令定义与下发参数

本页只解释可配置类型和公开入口，不讲完整游戏流程。先从命令系统理解玩家/AI 到执行层的链路；要实际接入 AI Pawn，读接入最小命令单位。

UGAIS_CommandSystemComponent 是 UPawnComponent，所以它的配置与运行状态属于 Pawn。不要把下面的载荷或队列 API 理解为普通 Actor 或 Controller 的通用命令框架。

`UGAIS_CommandSystemComponent`

组件是权威命令入口和可复制观察状态的拥有者。它不保存完整执行历史，也不公开执行后端内部状态；项目 UI 应使用 Current、Queue、Last 与事件来显示命令反馈。

状态或事件	意图	使用时机	误配风险
`CommandState.CurrentCommand` / `GetCurrentCommandData`	当前正在追踪的命令载荷。	HUD、目标指示、StateTree 辅助读取。	非空不代表一定已产生可见行为；还要检查执行层与最近结果。
`CommandState.CommandQueue` / `GetCommandQueue`	当前命令后的有序等待投影。	显示 Shift 队列、调试插队顺序。	它不是永久历史；同步终结会让刚接受的项很快离开队列。
`LastCommand`、`LastResultTag`、`LastReasonTag`	最近一条终结命令和最终结果。	失败提示、动画/UI 反馈。	只保留最近一次，不能用于审计完整历史。
`OnCommandChanged`	CurrentCommand 已提交后的变化事件。	刷新当前目标、按钮状态。	不要在事件回调中假设旧执行层仍未收到取消。
`OnCommandQueueChanged`	等待队列投影变化。	显示队列排序。	它不是每个执行后端任务状态的事件。
`OnLastCommandResultChanged`	最近终结结果变化。	反馈成功、失败、取消及原因。	客户端合并复制更新时只会观察到最新结果。

`FGAIS_CommandData`

这是“这一次下发什么”的运行时载荷。它由输入、UI、脚本、网络请求和 Tactical Assignment 构造，随后由 CommandSystem 依据 Definition 的目标契约进行归一化和验证。

字段	用途	何时设置	误配风险
`Definition`	命令定义类。	每次请求都必须有效且非抽象。	空类或不支持的资产会被拒绝。
`Index`	MultiVariant 的数组变体下标；Simple 通常忽略。	选择 MultiVariant 具体配置时。	DebugName 不参与选择；数组重排会改变已有引用语义。
`Target`	Actor 目标。	命令的 TargetType 需要 Actor 时。	为无目标/位置命令强塞 Actor 会违反目标契约。
`bHasLocation` / `Location`	显式位置或方向数据。	Location/Direction 命令。	只填写 Location 而未设置 `bHasLocation` 不构成有效位置请求。

可用 MakeTargetless、MakeActorTarget、MakeLocationTarget 等构造辅助函数减少手填错误，但仍应让它们与 Definition 的 TargetType 对齐。

`UGAIS_SimpleCommandDefinition`

Simple 是最常用的命令资产基类：一份可保存的默认配置描述一个稳定命令。它适合 Move、Interact、Heal、普通 Attack 等不需要把多个独立变体塞在一个入口的能力。

配置	意图	何时调整	误配风险
`CommonData.CancellationPolicy`	当前命令是否允许被替换请求取消。	设计打断体验时。	把不可打断的蓄力配置为可取消，会让前插或替换破坏玩法。
`CommonData.TargetType`	请求必须提供的目标形态。	创建每种命令时。	与 CommandData 不一致会在执行前被拒绝。
`RequirementsData`	Source/Target 的标签需求与成功条件。	需要通用状态门槛、阵营/状态限制时。	把复杂空间或项目规则只塞入标签，会造成难解释的拒绝。
`DisplayData`	名称、说明、图标和固定按钮槽位。	UI 需要展示命令时。	展示正确不表示命令具备有效 Execution。
`ExecutionDefinition`	该命令选择的无状态执行适配器。	每条可执行命令。	空配置会使请求无法启动；不要在对象中保存每次执行状态。
`RequiredRange`	执行者与目标的期望距离，0 表示无明确要求。	StateTree/项目后端需要距离语义时。	它不是自动移动或合法性检查的替代品。
`AcquisitionRadius`	默认目标评分的距离尺度。	自动选择与战术评分需要距离偏好时。	不负责收集候选，也不等同最大攻击距离。
`bIsCreatingIndividualTargetLocations`	群体下发时是否为每个单位生成独立落点。	队形移动、散开部署。	未开启/未覆写时，默认所有单位共享目标点。

`UGAIS_MultiVariantCommandDefinition` 与 `Variants`

MultiVariant 把同一命令类下的多种稳定选择集中管理。Variants 数组的位置就是 FGAIS_CommandData.Index 与命令引用使用的运行时身份；DebugName 仅用于编辑器和调试显示。

变体字段	意图	何时不同	误配风险
`DebugName`	编辑器中的可读名称。	给近战、远程、技能等命名。	不能用它替代 Index 进行运行时选择。
`Common`	此变体的取消策略与目标类型。	近战需 Actor、闪避需 Location 等。	同一命令入口各变体目标形态不同，UI 必须据实际 Index 构造载荷。
`Requirements`	此变体的下发/成功条件。	职业、武器、状态或目标限制不同。	将阵营或资源规则遗漏在变体中，会出现“显示可用但被拒绝”。
`Display`	此变体的 UI 表现。	同一入口不同按钮说明/图标时。	Display 不决定实际执行后端。
`ExecutionDefinition`	此变体自己的执行适配器。	近战/远程进入不同 StateTree，或一个变体改走 Ability。	多变体不必共享同一个执行层；错误共享会让行为与目标规则不匹配。
`RequiredRange` / `AcquisitionRadius`	此变体的距离语义和评分尺度。	近战、远程、支援的范围不同。	不要把它当作候选收集或导航完成阈值。

`UGAIS_CommandExecutionDefinition`

执行定义是内联、无状态的适配器配置。它收到包含精确执行身份的 Context：StartExecution 负责建立异步路由，或同步回报；CancelExecution 负责释放仍由该次执行拥有的外部状态。每一条命令的临时任务、订阅和回调应属于后端运行时，而不是保存在 Definition 资产上。

入口/配置	意图	何时使用	误配风险
`StartExecution`	启动已接受的精确执行。	自定义 StateTree、Ability、Behavior Tree 或项目后端。	返回 false 或未建立完成回报会让命令以启动失败结束。
`CancelExecution`	停止这次执行仍拥有的外部状态。	命令替换、取消、EndPlay。	不能取消已替换进来的新执行；必须按 Context 身份清理。
`UGAIS_CommandExecutionDefinition_StateTree.StateTree`	完整 StateTree 引用，含参数和属性覆写。	大多数 AI Pawn 命令。	StateTree 无效、Pawn 为玩家控制、AIController/Stack 缺失都会导致默认后端失败。

请求、队列和取消入口

这些 Blueprint 入口均为权威端语义；拥有 Pawn 的客户端应调用对应 Server... RPC，非拥有客户端应由项目网络入口转发。

入口	意图	适合场景	误配风险
`IssueCommand`	立即开始/替换；不可取消当前命令时保留唯一等待替换项。	最新玩家指令、脚本强制切换。	会清空既有等待项，不适合 Shift 队列。
`EnqueueCommand`	空闲时开始，否则 FIFO 追加。	路点、连续交互。	`Queued` 只说明被接受，不保证返回后仍在队列中。
`InsertCommandAfterCurrentCommand`	放到等待队首，不打断当前。	当前动作结束后的高优先级下一步。	不会抢占当前执行。
`InsertCommandBeforeCurrentCommand`	中断可取消当前命令后先执行新命令。	紧急闪避、反应性动作。	当前为 `NonCancelable` 时会拒绝。
`CancelCommand`	取消当前可取消命令。	玩家停止、状态变化。	不会越过 NonCancelable 保护。
`ClearCommandQueue`	仅清空等待项。	取消追加路点，保留当前移动。	不会停止当前执行。
`ClearCommands`	取消当前并清空等待项。	完全放弃当前计划。	当前不可取消时不会强制破坏它。
`CompleteCommandExecution`	由执行后端报告终结结果。	自定义后端完成、失败或取消时。	只能回报当前、身份精确匹配的执行。

取消策略与请求结果

类型	值	设计含义
`EGAIS_CommandCancellationPolicy`	`Cancelable` / `NonCancelable`	是否允许替换和前插取消当前命令。
`EGAIS_CommandRequestResult`	`Rejected` / `NoChange` / `Started` / `Queued`	请求未修改状态、完全相同、立即开始、或进入等待队列。

取消后的队列是否继续取决于最终结果和命令的成功判定；不要把 Canceled 一律理解为“必定继续”或“必定停止”。

目录