48 lines
4.0 KiB
Markdown
48 lines
4.0 KiB
Markdown
# FCommandPacket
|
||
|
||
## 基本信息
|
||
- **类型**: USTRUCT(BlueprintType)
|
||
- **父类**: (none)
|
||
- **源文件**: Plugins/CharacterControl/Source/CharacterControl/Public/CommandEndpoint.h
|
||
- **模块**: CharacterControl
|
||
|
||
## 功能概述
|
||
Complete unified command message flowing through routing system. Composed of Meta (FCommandMeta), ContinuousPayload (for continuous commands), DiscretePayload (TInstancedStruct<FDiscreteMeta>, for discrete commands).
|
||
|
||
## 设计用意
|
||
Unified message envelope. All routers and endpoints share single ReceiveCommand(const FCommandPacket&) interface. TInstancedStruct for discrete payload enables future extensibility without changing packet layout.
|
||
|
||
## 职责范围
|
||
Carries ONE command through the routing system. Either continuous or discrete payload is valid (determined by Meta.bIsContinuous).
|
||
|
||
## 项目内依赖
|
||
| 依赖项 | 关系 | 源文件 |
|
||
|--------|------|--------|
|
||
| FCommandMeta | 包含 (成员) | Plugins/CharacterControl/Source/CharacterControl/Public/CommandEndpoint.h |
|
||
| FContinuousPayload | 包含 (成员) | Plugins/CharacterControl/Source/CharacterControl/Public/CommandEndpoint.h |
|
||
| FDiscreteMeta | 包含 (TInstancedStruct) | Plugins/CharacterControl/Source/CharacterControl/Public/CommandEndpoint.h |
|
||
|
||
## 对外接口
|
||
FCommandPacket 是贯穿整个路由系统的统一命令消息。所有路由器、端点组件、输入组件的 ReceiveCommand 接口都接收 `const FCommandPacket&`。三个 UPROPERTY(BlueprintReadWrite) 成员字段：
|
||
|
||
- **Meta** (FCommandMeta): 携带路由元数据（CommandID、HopLimit、bIsContinuous、bIsUpward）
|
||
- **ContinuousPayload** (FContinuousPayload): 连续命令的有效载荷，当 Meta.bIsContinuous 为 true 时有效
|
||
- **DiscretePayload** (TInstancedStruct<FDiscreteMeta>): 离散命令的有效载荷，当 Meta.bIsContinuous 为 false 时有效。使用 TInstancedStruct 支持未来扩展
|
||
|
||
命令包在 UCommandInputComponent::BuildPacket 中构建，通过 FOnCommandOutput 委托广播，最终到达所有匹配端点的 ReceiveCommand。路由过程中 Meta.HopLimit 被递减，但载荷内容保持不变。
|
||
|
||
## 使用方法
|
||
FCommandPacket 的生命周期：BuildPacket 构建 -> 委托广播 -> Router 接收分发 -> Endpoint 接收：
|
||
|
||
- **构建**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandInputComponent.cpp:41-80` -- BuildPacket 根据 FInputCommand 和 FInputActionInstance 构造完整的 FCommandPacket
|
||
- **广播**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandInputComponent.cpp:108-110` -- 在 BindAllCommands 的 lambda 中构建后通过 OnCommandOutput.ExecuteIfBound 广播
|
||
- **路由消费**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:13-31` -- ReceiveCommand 检查 HopLimit 后分发到 RouteContinuousCommand 或 RouteDiscreteCommand
|
||
- **端点消费**: `Plugins/CharacterControl/Source/CharacterControl/Private/EndpointComponent.cpp:16-19` -- ReceiveCommand 转调 OnCommandReceived 蓝图事件
|
||
- **蓝图桥接**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandEndpoint.cpp:23-26` -- ICommandEndpoint 默认实现通过 Execute_ReceiveCommand_BP 转发到蓝图
|
||
|
||
## 用例
|
||
- **BuildPacket 构造**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandInputComponent.cpp:41-80` -- 输入触发时，BuildPacket 从 FInputCommand 配置和 FInputActionInstance 运行时值构造完整的 FCommandPacket
|
||
- **BindAllCommands 中广播**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandInputComponent.cpp:106-111` -- 每次输入事件触发 lambda，BuildPacket 构造包，OnPacketBuilt 钩子执行后通过 OnCommandOutput 广播
|
||
- **路由器入口分发**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:13-31` -- ReceiveCommand 根据 bIsContinuous 分发到不同的路由路径
|
||
- **上行传播本地拷贝**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:151-153` -- 上行命令先做本地拷贝（清除 bIsUpward），投递本地端点后再向上转发原始命令
|