init

Plugins/CharacterControl/FEndpointState.md

@@ -0,0 +1,47 @@
+# FEndpointState
+
+## 基本信息
+- **类型**: USTRUCT(BlueprintType) with TStructOpsTypeTraits specialization
+- **父类**: (none)
+- **源文件**: Plugins/CharacterControl/Source/CharacterControl/Public/CommandEndpoint.h
+- **模块**: CharacterControl
+
+## 功能概述
+Full state and identity of a command endpoint. Contains EndpointGuid (FGuid, unique identity), InterestedTags (FGameplayTagContainer, subscription list), bIsActive, bIsContinuousFriendly, bIsAsynchronous flags. Custom operator= preserves GUID on copy while updating config fields. TStructOpsTypeTraits with WithCopy=true forces UE to use C++ copy path instead of memcpy.
+
+## 设计用意
+Solves endpoint identity problem in dynamic routing graph. Custom copy operator prevents CDO/Blueprint default overwriting of runtime-assigned GUID. Tag subscription model enables declarative routing (no hard references between producers/consumers).
+
+## 职责范围
+Identity and configuration for one endpoint in the routing graph. GUID serves as registry key in UCommandRouter. Tags determine which commands the endpoint receives.
+
+## 项目内依赖
+| 依赖项 | 关系 | 源文件 |
+|--------|------|--------|
+| (none) | | |
+
+## 对外接口
+FEndpointState 定义命令端点的完整身份和配置。在 UCommandRouter::EndpointState、UEndpointComponent::EndpointState、UEndpointDispatcher::CurrentState 中作为成员使用。
+
+- **EndpointGuid** (FGuid, VisibleAnywhere, BlueprintReadOnly): 端点的唯一标识符，自动初始化为 NewGuid()，路由注册表以此为 Key。自定义 operator= 在目标已有身份时保留 GUID，防止 CDO/蓝图赋值覆盖运行时身份
+- **InterestedTags** (FGameplayTagContainer, EditDefaultsOnly, BlueprintReadOnly): 端点订阅的命令标签集合，决定端点接收哪些命令
+- **bIsActive** (bool, EditDefaultsOnly, BlueprintReadOnly): 端点活跃开关，false 时 IsEndpointMatched 直接返回 false，端点不接收任何命令
+- **bIsContinuousFriendly** (bool, EditDefaultsOnly, BlueprintReadOnly): 是否接收连续命令，false 的端点不会被投递连续命令
+- **bIsAsynchronous** (bool, EditDefaultsOnly, BlueprintReadOnly): 异步端点标志，端点应在自身 ReceiveCommand 中自行调度异步执行以保证线程安全
+
+FEndpointState 有 TStructOpsTypeTraits<WithCopy=true> 特化，强制 UE 使用 C++ 拷贝路径（而非 memcpy），确保自定义 operator= 被正确调用。
+
+## 使用方法
+FEndpointState 在不同位置设定和使用：
+
+- **端点配置**: `Plugins/CharacterControl/Source/CharacterControl/Private/EndpointComponent.cpp:13` -- UEndpointComponent 构造函数中设置 `EndpointState.bIsActive = true`
+- **路由器配置**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:8-11` -- UCommandRouter 构造函数中设置 `bIsActive=true, bIsContinuousFriendly=true, bIsAsynchronous=false`
+- **注册时读取**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:52-53` -- RegisterEndpoint 读取 EndpointGuid 验证有效性和唯一性
+- **匹配时读取**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:266-298` -- IsEndpointMatched 读取 bIsActive 和 bIsContinuousFriendly 决定匹配结果
+- **状态变更**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:33-42` -- SetRouterState 只更新配置字段，保留 Guid 并广播 StateChangedDelegate
+
+## 用例
+- **GUID 保护机制**: `Plugins/CharacterControl/Source/CharacterControl/Public/CommandEndpoint.h:88-105` -- 自定义 operator= 通过 bGuidAssigned 标志判断：未分配时拷贝 GUID，已分配时保留现有 GUID。防止蓝图 CDO 属性灌装覆盖运行时赋予的唯一 ID
+- **端点注册验证**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:53-58` -- RegisterEndpoint 检查 EndpointGuid 有效性，无效时拒绝注册并输出警告
+- **自注册防护**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:65-69` -- 检查端点 GUID 是否等于路由器自身 GUID，防止拓扑环路
+- **匹配判断入口**: `Plugins/CharacterControl/Source/CharacterControl/Private/CommandRouter.cpp:268-271` -- bIsActive 为 false 时直接返回 false，快速短路所有匹配逻辑