init

Plugins/CharacterControl/FCommandPacket.md

@@ -0,0 +1,47 @@
+# 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），投递本地端点后再向上转发原始命令