init

Plugins/CharacterControl/FCommandMeta.md

@@ -0,0 +1,43 @@
+# FCommandMeta
+
+## 基本信息
+- **类型**: USTRUCT(BlueprintType)
+- **父类**: (none)
+- **源文件**: Plugins/CharacterControl/Source/CharacterControl/Public/CommandEndpoint.h
+- **模块**: CharacterControl
+
+## 功能概述
+Metadata header for every command packet. Carries CommandID (int32, from UInputAction), HopLimit (uint8, mutable, decremented per router hop), bIsContinuous (bool, routing strategy selector), bIsUpward (bool, upward propagation flag).
+
+## 设计用意
+Routing envelope - decouples "what the command is" (payload) from "how it travels" (hop limit, direction). HopLimit prevents broadcast storms in router graphs. Upward flag supports parent-child router topologies.
+
+## 职责范围
+Carries routing metadata for one command packet. Embedded in FCommandPacket::Meta. Decremented at each router hop.
+
+## 项目内依赖
+| 依赖项 | 关系 | 源文件 |
+|--------|------|--------|
+| (none) | | |
+
+## 对外接口
+FCommandMeta 是嵌入在 FCommandPacket::Meta 中的数据容器，所有字段通过 UPROPERTY(BlueprintReadOnly) 暴露给蓝图。调用者不直接构造 FCommandMeta，而是由 UCommandInputComponent::BuildPacket 在输入事件触发时自动填充。路由过程中 UCommandRouter::ReceiveCommand 会递减 HopLimit。
+
+- **CommandID** (int32, BlueprintReadOnly): 由 BuildPacket 从 UInputAction::GetUniqueID() 填充，标识命令来源
+- **HopLimit** (uint8, mutable, BlueprintReadOnly): 每经过一层路由递减 1，耗尽则丢包。BuildPacket 对连续命令设为 3、离散命令设为 5
+- **bIsContinuous** (bool, BlueprintReadOnly): 决定路由分发策略（连续走 RouteContinuousCommand，离散走 RouteDiscreteCommand）
+- **bIsUpward** (bool, BlueprintReadOnly): 上行传播标志，在上级路由器中决定是否同时投递本地和向上转发
+
+## 使用方法
+FCommandMeta 作为 FCommandPacket 的成员由 BuildPacket 构建，在 CommandRouter 中消费：
+
+- **构建**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandInputComponent.cpp:70-72` -- BuildPacket 设置 CommandID、bIsContinuous、HopLimit（连续 3、离散 5）
+- **跳数递减**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:16-21` -- ReceiveCommand 检查 HopLimit 并在 >0 时递减
+- **上行传播跳数递减**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:155` -- 上行命令在路由器层面再递减一次
+- **路由策略选择**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:23-30` -- 根据 bIsContinuous 选择 RouteContinuousCommand 或 RouteDiscreteCommand
+
+## 用例
+- **BuildPacket 构建**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandInputComponent.cpp:70-72` -- 输入触发时根据 FInputCommand::bIsContinuous 设置 Meta 各字段，连续命令 HopLimit=3，离散命令 HopLimit=5
+- **HopLimit 防护**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:16-18` -- ReceiveCommand 入口处首先检查 HopLimit，<=0 直接丢包，防止广播风暴
+- **逐跳递减**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:21` -- 每经过一个路由器，mutable 的 HopLimit 减 1，确保命令不会无限传播
+- **上行转发**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:148-155` -- 当 bIsUpward 为 true 时，先投递本地（清除上行标志），再向上级路由器转发