4.0 KiB
4.0 KiB
FCommandPacket
基本信息
- 类型: USTRUCT(BlueprintType)
- 父类: (none)
- 源文件: Plugins/CharacterControl/Source/CharacterControl/Public/CommandEndpoint.h
- 模块: CharacterControl
功能概述
流经路由系统的完整统一命令消息。由 Meta（FCommandMeta）、ContinuousPayload（用于连续命令）、DiscretePayload（TInstancedStruct）
设计用意
统一的消息信封。所有路由器和端点共享单一的 ReceiveCommand(const FCommandPacket&) 接口。离散载荷使用 TInstancedStruct 可在不改变数据包布局的情况下实现未来扩展。
职责范围
携带一个命令通过路由系统。Continuous 或 Discrete 载荷二者仅有一个有效（由 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): 离散命令的有效载荷，当 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），投递本地端点后再向上转发原始命令