diff --git a/Content/Blueprints/ABP_TestChar.md b/Content/Blueprints/ABP_TestChar.md new file mode 100644 index 0000000..b07caea --- /dev/null +++ b/Content/Blueprints/ABP_TestChar.md @@ -0,0 +1,67 @@ +# ABP_TestChar + +## 基本信息 +- **类型**: AnimBlueprint (AnimInstance) +- **父类**: AnimInstance +- **源文件**: /Game/Blueprints/Anim/ABP_TestChar.ABP_TestChar +- **模块**: Content/Blueprints/Anim + +## 功能概述 +测试角色的动画蓝图，为 BP_NewChar/BP_TestChar 提供动画驱动。持有 5 个动画参数：As Character（角色引用）、Speed（速度）、Random（随机值）、TargetRandom（目标随机值）、IsFloating（是否浮空）。通过 AnimGraph 驱动混合空间 BS_Walk_Run 实现移动动画。 + +## 设计用意 +为测试角色提供基础动画控制，将移动速度映射到行走/奔跑混合空间，并通过 Random/TargetRandom 参数增加动画变化的随机性。 + +## 职责范围 +- 计算和更新 Speed、Random、IsFloating 等动画参数 +- 通过 AnimGraph 驱动 BlendSpace 和动画序列 +- 通过 EventGraph（3 事件, 28 节点）处理动画事件逻辑 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| 绑定好5 | 引用(骨骼网格体) | /Game/Arts/mx/Elsa/绑定好5 | +| 绑定好_Skeleton | 引用(骨骼) | /Game/Arts/mx/Elsa/绑定好_Skeleton | +| BS_Walk_Run | 引用(混合空间) | /Game/Blueprints/Anim/BS_Walk_Run | +| MOB1_Walk_F_Jump_RU_Air_IPC | 引用(动画序列) | /Game/Arts/动画/3/跳跃/MOB1_Walk_F_Jump_RU_Air_IPC | + +## 外部视角 + +ABP_TestChar 是 AnimInstance 的动画蓝图子类，从外部调用者视角： + +**动画参数（蓝图可读写，外部可通过 Get/Set 节点访问）** +- `As Character`（Character*）— 绑定的角色引用 +- `Speed`（double）— 移动速度，驱动 BlendSpace 混合 +- `Random` / `TargetRandom`（double）— 随机值及目标，用于增加动画变化的随机性 +- `IsFloating`（bool）— 是否浮空状态 + +**核心行为** +- AnimGraph 驱动 BS_Walk_Run 混合空间实现行走/奔跑动画混合 +- EventGraph 处理动画事件逻辑，更新上述参数 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件蓝图开始播放` | 原生覆盖 (BeginPlay) | 动画蓝图初始化时 | 获取 Pawn 拥有者 → Cast 到 Character → 存入 As Character 变量 → 设置定时器 5 秒循环触发 RandomIdle | +| `事件蓝图更新动画` | 原生覆盖 (Tick) | 每帧 | 验证 As Character 有效 → 获取速度 → 计算向量长度 → 更新 Speed 参数 → FInterpTo 插值 Random → 获取 Z 轴速度绝对值 → 判断 > 阈值 → 更新 IsFloating | +| `RandomIdle` | 自定义事件 | 定时器循环触发 | 生成 0-4 随机整数 → 切换设置 TargetRandom（0/50/75/100）→ Tick 中 Random 向 TargetRandom 插值 | + +**外部交互方式** +- 在 BP_NewChar / BP_TestChar 的动画蓝图插槽中指定 +- 外部系统通过 AnimInstance 引用读取/修改动画参数以控制角色动画表现 + +## 使用方法 + +ABP_TestChar 在项目中的典型调用流程： + +- **动画驱动流程** — 角色移动 → 引擎更新动画蓝图 Tick → 获取角色速度 → 计算向量长度 → 更新 Speed 参数 → AnimGraph 将 Speed 输入 BS_Walk_Run 混合空间 → 驱动骨骼姿势 +- **随机空闲动画流程** — 5 秒定时器触发 RandomIdle → 随机选择 TargetRandom（0-4 档位）→ Tick 中 FInterpTo 平滑过渡 → 影响 BlendSpace 混合位置 → 实现随机空闲姿态变化 +- **浮空检测流程** — Tick 获取 Z 轴速度 → 绝对值 > 阈值 → 设置 IsFloating=true → AnimGraph 切换到跳跃动画序列 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_TestChar | `/Game/Blueprints/BP_TestChar` | 作为动画蓝图，驱动角色移动动画 | +| BP_NewChar | `/Game/Blueprints/BP_NewChar` | 作为动画蓝图，驱动实验性角色动画 | diff --git a/Content/Blueprints/BP_Barrel.md b/Content/Blueprints/BP_Barrel.md new file mode 100644 index 0000000..5da7cdf --- /dev/null +++ b/Content/Blueprints/BP_Barrel.md @@ -0,0 +1,65 @@ +# BP_Barrel + +## 基本信息 +- **类型**: Blueprint (Actor) +- **父类**: Actor +- **源文件**: /Game/Blueprints/Playground/BP_Barrel.BP_Barrel +- **模块**: Content/Blueprints/Playground + +## 功能概述 +可交互的木桶 Actor，在 Playground 场景中作为可破坏或可互动物体。持有 BarrelWindow（WBP_Window）用于显示交互界面，与库存系统（BP_InventoryComp）和容器系统（BP_DefaultContainer）联动。 + +## 设计用意 +Playground 场景中的测试用互动物体，用于验证 Actor 与 HUD/库存系统的交互流程。通过 BarrelWindow 窗口展示容器内容，验证库存 UI 与场景物体的数据交互。 + +## 职责范围 +- 作为场景中的可互动物体持有 BarrelWindow 引用 +- 通过 EventGraph（4 事件, 24 节点）处理交互逻辑 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| BP_Hud | 引用 | /Game/Blueprints/BP_Hud | +| WBP_InventoryView | 引用 | /Game/Blueprints/UI/Item/WBP_InventoryView | +| WBP_Window | 包含(变量) | /Game/Blueprints/UI/WBP_Window | +| BP_TestCtl | 引用 | /Game/Blueprints/BP_TestCtl | +| BP_InventoryComp | 引用 | /Game/Blueprints/Playground/BP_InventoryComp | +| BP_DefaultContainer | 引用 | /Game/Blueprints/Playground/BP_DefaultContainer | + +## 外部视角 + +BP_Barrel 是 Actor 的子类，从外部调用者视角： + +**公开属性（蓝图可读写）** +- `BarrelWindow`（WBP_Window_C*）— 木桶交互界面的窗口 Widget + +**核心行为** +- 通过 BP_Hud 获取 InvView（WBP_InventoryView）显示木桶内物品 +- 通过 BP_InventoryComp / BP_DefaultContainer 管理木桶库存 +- 通过 BP_TestCtl 获取控制器引用 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | Actor 生成时由引擎自动触发 | 创建 BP_DefaultContainer → 通过 IItemContainer 创建随机数量的 TestItem → 遍历新物品 ID → 通过 IInventory 接收物品 | +| `事件Actor开始重叠` | 原生覆盖 (OnActorBeginOverlap) | 其他 Actor 进入重叠区域时 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | +| `On Clicked (Barrel)` | 组件绑定事件 | 玩家点击木桶碰撞体时 | 获取 PlayerController → GetHUD → Cast 到 BP_Hud → 创建 WBP_Window（设 IsTemp=true）和 WBP_InventoryView → BindToComp 绑定到木桶的 BP_InventoryComp → 作为子项添加到 HUD | + +**外部交互方式** +- 放置在 Playground 关卡中作为可交互场景物体 +- 玩家靠近/与木桶交互时，通过 HUD 显示库存界面 + +## 使用方法 + +BP_Barrel 在项目中的典型调用流程： + +- **木桶交互流程** — 玩家点击木桶碰撞体 → 触发 On Clicked (Barrel) → 获取 PlayerController → GetHUD → Cast 到 BP_Hud → 创建临时 WBP_Window 和 WBP_InventoryView → BindToComp 绑定到木桶的 BP_InventoryComp → 显示木桶库存 UI +- **木桶初始化流程** — BeginPlay → 创建 BP_DefaultContainer → 调用 CreateItem 生成随机数量 TestItem → 通过 IInventory 接口接收物品到木桶的 InventoryComp + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| Playground | `/Game/地图关卡/Playground` | 关卡中的可交互木桶，演示物品查看/拾取流程 | diff --git a/Content/Blueprints/BP_Bomb.md b/Content/Blueprints/BP_Bomb.md index 5462104..3400d1c 100644 --- a/Content/Blueprints/BP_Bomb.md +++ b/Content/Blueprints/BP_Bomb.md @@ -4,7 +4,7 @@ - **类型**: Blueprint (Actor) - **父类**: Actor - **源文件**: /Game/Blueprints/Playground/BP_Bomb.BP_Bomb -- **模块**: Content +- **模块**: Content/Blueprints/Playground ## 功能概述 BP_Bomb 是物品系统和追踪器系统的交互核心示例 Actor。它结合了 IItemContainer（物品容器接口）、UItemTracer（物品追踪器）和 Owner 检测，演示了物品在 Actor 之间的完整生命周期：创建、追踪、转移和响应。 @@ -21,26 +21,45 @@ BP_Bomb 负责演示物品+追踪器的完整交互流程，包括物品创建 | IItemContainer | 持有 (ItemContainer) | Item 插件 | | UItemTracer | 持有 (ItemLocation) | Item 插件 | -## 对外接口 -- **蓝图函数**： - - `GetContainer() -> TScriptInterface` -- 返回本 Actor 持有的物品容器接口，用于外部获取容器的物品操作能力 - - `FindActorInOuterChain(UObject* Obj) -> AActor*` -- 在给定对象的 Outer 链中查找第一个 AActor，蓝图版本的 Outer 遍历（等同于 C++ UItemTracer::FindActorInOuterChain 的蓝图实现） -- **蓝图变量**（均为 is_instance_editable）： - - `ItemContainer` (TScriptInterface) -- 物品容器接口引用，提供 CreateItem、MoveItem、GetItemViews 等所有物品操作 - - `Current Owner` (UObject*) -- 当前持有者对象引用，用于追踪物品在哪个 Actor 身上 - - `ItemLocation` (UItemTracer*) -- 物品追踪器引用，持有 `OnItemMoved` 委托（FOnItemMoved），用于监听物品位置变化 - - `Item ID` (FGuid) -- 追踪的物品 ID，用于跨容器识别和追踪物品 -- **EventGraph**：含 5 个事件和 44 个节点，处理物品生命周期演示逻辑 +## 外部视角 + +BP_Bomb 是 Actor 的子类，从外部调用者视角： + +**公开属性（蓝图可读写）** +- `ItemContainer`（IItemContainer 接口引用）— 持有的物品容器 +- `Current Owner`（Object*）— 当前拥有者 +- `ItemLocation`（UItemTracer*）— 物品位置追踪器 +- `Item ID`（Guid）— 追踪的物品 GUID + +**自定义函数** +- `GetContainer()` → `IItemContainer` — 获取当前持有的容器接口 +- `FindActorInOuterChain(Object*)` → `Actor*` — 沿 Outer 链向上查找 Actor + +**外部交互方式** +- 放置在 Playground 关卡中作为可交互对象 +- 演示物品系统核心流程：创建 → 追踪 → 转移 → 响应 +- 通过 ItemLocation（UItemTracer）绑定 OnItemMoved 委托，检测物品跨容器转移 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | Actor 生成时由引擎自动触发 | 通过 GetContainer 获取容器 → CreateItem 创建炸弹物品 → GetItemProperty 获取 ItemTracer → 存入 ItemLocation → 存入 ItemID | +| `事件Actor开始重叠` | 原生覆盖 (OnActorBeginOverlap) | 其他 Actor 进入重叠区域 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | Switch Has Authority → 服务器端逻辑处理 | +| `On Component Hit (Sphere)` | 组件绑定事件 | 球形碰撞体被击中时 | Switch Has Authority → 验证 ItemLocation 有效 → 按类获取 BP_InventoryComp → RequestMoveItem 请求物品移动 | +| `事件RequestMoveItem` | 接口事件 (来自 Inventory 系统) | Inventory 系统请求移动物品时 | 通过 GetContainer 获取容器 → ReceiveItem 接收物品 | ## 使用方法 -- 作为示例 Actor 放置到关卡中，演示物品系统的完整使用流程 -- 在蓝图编辑器中配置：创建 UDefaultContainer 作为 `ItemContainer`，通过 CreateItem 创建炸弹物品并记录 `Item ID` -- 创建 UItemTracer 实例并赋值给 `ItemLocation`，绑定 `OnItemMoved` 委托监听物品位置变化 -- `GetContainer()` 用于外部获取容器的物品操作接口 -- `FindActorInOuterChain()` 用于通过物品容器对象的 Outer 链查找实际持有该物品的 Actor -- 当 `ItemLocation.OnItemMoved` 触发时（物品转移到其他容器），通过 `FindActorInOuterChain` 检测新持有者，并触发相应的业务逻辑（如爆炸） -- 实现物品系统的完整交互演示：创建 -> 追踪 -> 转移检测 -> 响应 + +BP_Bomb 在项目中的典型调用流程： + +- **炸弹初始化流程** — BeginPlay → GetContainer → CreateItem（TestBomb）→ GetItemProperty（获取 ItemTracer）→ 存入 ItemLocation 和 ItemID → 追踪器绑定委托 +- **物品移动触发流程** — 玩家拾取炸弹 → 炸弹被移出容器 → On Component Hit → 验证 ItemLocation → 获取目标 BP_InventoryComp → RequestMoveItem → 接口事件触发 → ReceiveItem 接收物品到新容器 +- **追踪器响应流程** — ItemLocation（UItemTracer）检测到物品移动 → 触发 OnItemMoved 委托 → 执行爆炸/响应逻辑 ## 用例 -- 物品系统演示 Actor，展示 IItemContainer + UItemTracer 的完整交互流程 -- 放置于关卡中作为示例，演示物品创建、转移追踪、所有者检测等核心功能 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| Playground | `/Game/地图关卡/Playground` | 关卡中放置的交互示例，演示物品系统全流程 | diff --git a/Content/Blueprints/BP_CameraPawn.md b/Content/Blueprints/BP_CameraPawn.md index 1944c2c..c735e8a 100644 --- a/Content/Blueprints/BP_CameraPawn.md +++ b/Content/Blueprints/BP_CameraPawn.md @@ -4,7 +4,7 @@ - **类型**: Blueprint (Pawn) - **父类**: ACameraPawn - **源文件**: /Game/Blueprints/BP_CameraPawn.BP_CameraPawn -- **模块**: Content +- **模块**: Content/Blueprints ## 功能概述 BP_CameraPawn 是分离式第三人称摄像机的蓝图实现，继承 C++ 的 ACameraPawn。在蓝图层面配置摄像机参数（初始旋转、臂长范围、速度等），并提供编辑器内可视化调整能力。 @@ -20,33 +20,51 @@ BP_CameraPawn 负责摄像机参数的蓝图级配置和编辑器内可视化调 |--------|------|--------| | ACameraPawn | 父类 | C++ 源码 | -## 对外接口 -- **继承自 ACameraPawn 的 BlueprintCallable 函数**： - - `CameraZoom(const FInputActionValue& Value)` -- 摄像机缩放，调整 SpringArm 臂长 - - `CameraRotate(const FInputActionValue& Value)` -- 摄像机旋转，调整 SpringArm 的旋转偏移 - - `CameraMove(const FInputActionValue& Value)` -- 摄像机平移，调整 SpringArm 的 SocketOffset - - `CameraReset(const FInputActionValue& Value)` -- 重置摄像机到默认位置和旋转 -- **继承自 ACameraPawn 的 BlueprintReadOnly 属性**： - - `SpringArmComponent` (USpringArmComponent*) -- SpringArm 组件引用 - - `CameraComponent` (UCameraComponent*) -- Camera 组件引用 - - `FollowTarget` (APawn*) -- 跟随目标 Pawn（VisibleInstanceOnly） -- **蓝图可调的配置参数**（EditDefaultsOnly, BlueprintReadOnly）： - - `InitialRotation` = FRotator(-60, 0, 0) -- 初始俯仰角 - - `InitialArmLength` = 1200.0f -- 初始臂长 - - `RotateSpeed` = 2.0f -- 旋转速度 - - `ZoomSpeed` = 10.0f -- 缩放速度 - - `MoveSpeed` = 10.0f -- 平移速度 - - `MaxArmLength` = 3000.0f / `MinArmLength` = 300.0f -- 臂长范围 - - `CameraMoveClamp` = 800.0 -- 平移限制范围 +## 外部视角 + +BP_CameraPawn 是 ACameraPawn 的蓝图子类（自身不添加新变量或函数），从外部调用者视角，其接口全部继承自 C++ 父类： + +**组件（BlueprintReadOnly）** +- `SpringArmComponent`（USpringArmComponent*）— 弹簧臂组件，外部只读 +- `CameraComponent`（UCameraComponent*）— 摄像机组件，外部只读 +- `FollowTarget`（APawn*）— 当前跟随的目标 Pawn，外部只读 + +**配置参数（BlueprintReadOnly，可在蓝图默认值面板调整）** +- `InitialRotation`（FRotator，默认 -60°, 0°, 0°）— 初始摄像机旋转 +- `InitialArmLength`（float，默认 1200）— 初始臂长 +- `MinArmLength`（float，默认 300） / `MaxArmLength`（float，默认 3000）— 臂长范围 +- `RotateSpeed`（float，默认 2.0）— 旋转速度 +- `ZoomSpeed`（float，默认 10.0）— 缩放速度 +- `MoveSpeed`（float，默认 10.0）— 移动速度 +- `CameraMoveClamp`（double，默认 800.0）— 摄像机移动范围限制 + +**操作函数（蓝图可调用）** +- `CameraZoom(FInputActionValue)` — 根据输入值缩放臂长 +- `CameraRotate(FInputActionValue)` — 根据输入值旋转摄像机 +- `CameraMove(FInputActionValue)` — 根据输入值移动摄像机位置 +- `CameraReset(FInputActionValue)` — 重置摄像机到初始状态 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | Pawn 生成时由引擎自动触发 | 预留（当前无连线逻辑） | +| `事件Actor开始重叠` | 原生覆盖 (OnActorBeginOverlap) | 与其他 Actor 碰撞时 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | + +**外部交互方式** +- 通常通过 BP_TestChar 的 CameraActorClass 设置自动创建 +- C++ 层通过 `Cast` 获取引用并调用其操作函数 ## 使用方法 -- 通过 BP_TestChar (AMyCharacter) 的 `CameraActorClass` 属性配置，角色 Possess 时自动生成摄像机实例 -- 继承自 ACameraPawn，C++ 层提供了完整的 SpringArm+Camera 组件和变换逻辑 -- 蓝图层面可在 EventGraph 中响应事件（event_count=3，node_count=3） -- 配置参数均为 `EditDefaultsOnly`，在蓝图类默认值中调整摄像机行为，无需修改 C++ 代码 -- ACameraPawn 的 Tick() 处理每帧的臂长插值、旋转跟随和移动偏移，蓝图不参与底层变换 -- `FollowTarget` 在运行时由 SetFollowTarget 逻辑自动设置为当前控制的角色 + +BP_CameraPawn 在项目中的典型调用流程： + +- **摄像机初始化流程** — BP_TestChar 的 CameraActorClass 设为 BP_CameraPawn → BP_TestChar Possess 后自动生成 BP_CameraPawn 实例 → ACameraPawn 的 C++ 逻辑绑定 SpringArm + Camera 组件 → 读取蓝图配置的 InitialRotation/InitialArmLength 初始化 +- **摄像机控制流程** — 玩家输入 → Enhanced Input 系统 → ACameraPawn 的 CameraZoom/Rotate/Move/Reset 函数 → C++ 层处理 SpringArm 变换和臂长插值 ## 用例 -- BP_TestChar (AMyCharacter) 中 `CameraActorClass` 属性引用，作为角色的分离式摄像机 -- 被 Possess 角色时自动生成，跟随 `FollowTarget` Pawn + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_TestChar | `/Game/Blueprints/BP_TestChar` | 设为 CameraActorClass，在角色生成时自动创建分离式摄像机 | diff --git a/Content/Blueprints/BP_ControllerComp.md b/Content/Blueprints/BP_ControllerComp.md index 59cabcc..963174c 100644 --- a/Content/Blueprints/BP_ControllerComp.md +++ b/Content/Blueprints/BP_ControllerComp.md @@ -4,7 +4,7 @@ - **类型**: Blueprint (ActorComponent) - **父类**: BP_EndpointComp_C (即 UEndpointComponent) - **源文件**: /Game/Blueprints/Component/BP_ControllerComp.BP_ControllerComp -- **模块**: Content +- **模块**: Content/Blueprints/Component ## 功能概述 BP_ControllerComp 是自定义控制器端点组件，管理摄像机的缩放和跟随模式。持有多个摄像机相关配置参数：移动速度（MoveSpeed）、臂长范围（MinArmLength / MaxArmLength）、缩放速度（ZoomSpeed）、跟随模式开关（IsFollowMode）以及跟随目标角色引用（FollowedChar）。 @@ -22,34 +22,51 @@ BP_ControllerComp 负责摄像机控制参数的管理、跟随模式的切换 | UEndpointComponent | 祖父类 | CharacterControl 插件 | | ACharacter | 引用 (FollowedChar) | 引擎内置 | -## 对外接口 -- **蓝图函数**： - - `MoveController(A: GameplayTag, InVec: Vector)` -- 摄像机移动指令处理，接收 GameplayTag 和移动向量 - - `RotateController(A: GameplayTag, InVec: Vector)` -- 摄像机旋转指令处理 - - `ZoomCamera(A: GameplayTag, InVec: Vector)` -- 摄像机缩放指令处理，通过 InVec 中的值调整臂长 - - `ResetControllerLocation(DiscreteMeta: DiscreteMeta)` -- 摄像机位置重置，接收离散命令元数据 - - `TickFollowChar()` -- 跟随模式每帧更新，将摄像机位置锁定到 FollowedChar -- **蓝图变量**（均为 is_instance_editable）： - - `MoveSpeed` (double) -- 摄像机移动速度 - - `MinArmLength` (double) -- 最小臂长 - - `MaxArmLength` (double) -- 最大臂长 - - `ZoomSpeed` (double) -- 缩放速度 - - `IsFollowMode` (bool) -- 是否启用跟随模式 - - `FollowedChar` (Character*) -- 跟随目标角色引用 -- **继承自 (BP_EndpointComp_C / UEndpointComponent) 的接口**： - - `EndpointState` -- 端点状态，含 `InterestedTags` 配置摄像机控制相关标签 - - `OnCommandReceived` -- 收到指令时的处理入口 -- **EventGraph**：含 6 个事件和 27 个节点，处理摄像机控制的核心逻辑 +## 外部视角 + +BP_ControllerComp 是 BP_EndpointComp_C（即 UEndpointComponent）的蓝图子类，从外部调用者视角： + +**公开配置属性（蓝图可读写）** +- `MoveSpeed`（double）— 摄像机移动速度 +- `MinArmLength` / `MaxArmLength`（double）— 臂长最小/最大值 +- `ZoomSpeed`（double）— 缩放速度 +- `IsFollowMode`（bool）— 是否启用跟随模式 +- `FollowedChar`（Character*）— 跟随模式的目标角色 + +**自定义函数** +- `MoveController(GameplayTag, Vector)` — 处理摄像机移动指令 +- `RotateController(GameplayTag, Vector)` — 处理摄像机旋转指令 +- `ZoomCamera(GameplayTag, Vector)` — 处理摄像机缩放指令 +- `ResetControllerLocation(DiscreteMeta)` — 重置摄像机位置 +- `TickFollowChar()` — 每帧更新跟随目标位置 + +**外部交互方式** +- 作为 BP_TestChar 的组件自动创建 +- 指令系统通过 UCommandRouter 将摄像机控制指令路由到该组件 +- 外部系统可通过组件引用读取/修改其配置参数 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | 组件创建时由引擎自动触发 | 调用父类 BeginPlay | +| `事件Tick` | 原生覆盖 | 每帧 | 调用父类 Tick，然后调用 TickFollowChar 更新跟随目标位置 | +| `事件OnCommandReceived` | 委托事件 (EndpointComponent) | 收到指令路由系统派发的 CommandPacket | 解析 CommandPacket → 根据 GameplayTag 分发到 MoveController/RotateController/ZoomCamera（连续指令）或 ResetControllerLocation（离散指令） | +| `EnterFollowMode` | 自定义事件 | 外部系统通过指令或直接调用触发 | 设置 IsFollowMode=true → 获取 Owner → Cast 到 PlayerController → Cast 到 Character → 设为 FollowedChar | +| `EnterFreeMode` | 自定义事件 | 外部系统通过指令或直接调用触发 | 设置 IsFollowMode=false，解除跟随 | +| `DealWithCommand` | 自定义事件 | 收到指令时由组件内部逻辑调用 | 调用 DealWithCommand(CommandPacket) 函数进行指令处理分发 | ## 使用方法 -- 作为 ActorComponent 添加到 BP_TestChar -- 在组件实例上配置 `MoveSpeed`、`MinArmLength`、`MaxArmLength`、`ZoomSpeed` 等摄像机参数 -- 通过 `EndpointState.InterestedTags` 配置关注的摄像机控制 GameplayTag（如 "Camera.Move"、"Camera.Zoom"、"Camera.Rotate"、"Camera.Reset"） -- 开启 `IsFollowMode` 并设置 `FollowedChar` 可启用角色跟随模式 -- `MoveController`、`RotateController`、`ZoomCamera` 函数由 OnCommandReceived 事件根据指令标签分发调用 -- `TickFollowChar()` 在 EventGraph 的 Tick 事件中调用，实现每帧跟随 -- `UCommandRouterComponent` 自动发现并注册本组件 + +BP_ControllerComp 在项目中的典型调用流程： + +- **摄像机移动控制流程** — 外部输入 → UCommandRouter 派发 → `OnCommandReceived` 触发 → 解析 CommandPacket → 根据 GameplayTag 路由到 MoveController/RotateController/ZoomCamera → 更新摄像机位置/旋转/臂长 +- **跟随模式切换流程** — 外部系统调用 `EnterFollowMode` → 设置 IsFollowMode=true → 获取 Owner → Cast 到 PlayerController → Cast 到 Character 设为 FollowedChar → Tick 中 TickFollowChar 每帧更新摄像机位置跟随角色 +- **自由模式切换流程** — 外部系统调用 `EnterFreeMode` → 设置 IsFollowMode=false → TickFollowChar 不再更新摄像机位置 ## 用例 -- BP_TestChar 的组件，处理摄像机控制指令 -- 通过配置参数在运行时动态调整 ACameraPawn 的行为（臂长、速度、跟随目标） + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_TestChar | `/Game/Blueprints/BP_TestChar` | 作为端点组件添加到角色，处理摄像机控制指令 | +| BP_TestCtl | `/Game/Blueprints/BP_TestCtl` | 引用 BP_ControllerComp 用于摄像机控制 | diff --git a/Content/Blueprints/BP_DefaultContainer.md b/Content/Blueprints/BP_DefaultContainer.md index aac6955..beabedf 100644 --- a/Content/Blueprints/BP_DefaultContainer.md +++ b/Content/Blueprints/BP_DefaultContainer.md @@ -4,7 +4,7 @@ - **类型**: Blueprint (UObject) - **父类**: UDefaultContainer - **源文件**: /Game/Blueprints/Playground/BP_DefaultContainer.BP_DefaultContainer -- **模块**: Content +- **模块**: Content/Blueprints/Playground ## 功能概述 BP_DefaultContainer 是 UDefaultContainer 的蓝图子类，作为物品系统的默认容器在蓝图层中使用。无额外自定义变量，直接使用 C++ 父类的完整 IItemContainer 实现，提供 CreateItem、GetItemViews、MoveItem 等物品操作接口。 @@ -21,25 +21,36 @@ BP_DefaultContainer 作为物品容器的蓝图实例化版本，负责在编辑 | UDefaultContainer | 父类 | Item 插件 | | IItemContainer | 间接实现 | Item 插件 | -## 对外接口 -- **继承自 UDefaultContainer（即 IItemContainer 接口）的全部 BlueprintCallable 函数**： - - `GetItemViews() const -> TArray` -- 返回容器中所有物品视图列表 - - `GetItemViewByID(const FGuid& ItemID) const -> FItemView` -- 按物品 ID 获取单个物品视图 - - `GetItemCount() const -> int32` -- 返回当前容器中的物品数量 - - `MoveItem(const FGuid& ItemID, const TScriptInterface& TargetContainer) -> bool` -- 将物品移动到目标容器（BlueprintAuthorityOnly） - - `CreateItem(FName ItemType, TArray& NewItemIDs, int32 Count=1) -> bool` -- 按 ItemType 创建物品（BlueprintAuthorityOnly） - - `GetItemProperty(FGuid ItemID, FName PropertyName, int32& Value) -> bool` -- 读取物品动态属性（CustomThunk，属性类型自动匹配） - - `SetItemProperty(FGuid ItemID, FName PropertyName, int32 Value)` -- 写入物品动态属性（CustomThunk） -- **无自定义蓝图变量或函数**（MCP: variables=[], functions=[]）：纯父类能力透传，所有接口由 UDefaultContainer C++ 层实现 +## 外部视角 + +BP_DefaultContainer 是 UDefaultContainer（Item 插件 C++ 类）的蓝图子类，从外部调用者视角： + +**接口概览** +- 无自定义变量或函数，所有接口继承自 C++ 父类 UDefaultContainer +- UDefaultContainer 实现 IItemContainer 接口，提供：CreateItem、GetItemViews、MoveItem、RemoveItem 等物品操作 +- 本身是纯配置层——使 UDefaultContainer 在蓝图中可引用 + +**外部交互方式** +- 作为 BP_InventoryComp 的 DefaultContainer 变量默认实例 +- 其他蓝图通过 BP_InventoryComp 间接访问 BP_DefaultContainer 的物品操作接口 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| （无） | — | — | EventGraph 为空，所有功能由 C++ 父类实现 | ## 使用方法 -- 作为 UObject 资产创建并保存在 /Game/Blueprints/Playground/ 路径下 -- 被 BP_InventoryComp 的 `DefaultContainer` 变量引用，作为物品的实际存储容器 -- 通过 IItemContainer 接口的所有 BlueprintCallable 函数进行物品操作 -- 实际存储逻辑由 C++ 父类 UDefaultContainer 的 `TArray> Items` 处理 -- BP_DefaultContainer 存在的意义是提供一个蓝图可引用的资产版本，方便在编辑器中直接拖拽配置 -- 无需在蓝图层面编写任何逻辑（functions=[]），完全依赖父类实现 + +BP_DefaultContainer 在项目中的典型调用流程： + +- **初始化流程** — BP_InventoryComp.BeginPlay → 创建 BP_DefaultContainer 实例 → 存入 DefaultContainer 变量 → 外部系统通过 BP_InventoryComp 间接调用 IItemContainer 接口 ## 用例 -- BP_InventoryComp 的 `DefaultContainer` 变量默认值，作为库存组件的底层存储 -- 任何需要 IItemContainer 接口的地方均可引用此资产 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_InventoryComp | `/Game/Blueprints/Playground/BP_InventoryComp` | 作为默认容器实例，管理物品存储 | +| BP_Bomb | `/Game/Blueprints/Playground/BP_Bomb` | 容器引用，用于炸弹物品生命周期 | +| BP_ItemTrap | `/Game/Blueprints/Playground/BP_ItemTrap` | 容器引用，用于陷阱物品管理 | +| BP_Barrel | `/Game/Blueprints/Playground/BP_Barrel` | 容器引用，用于木桶物品管理 | diff --git a/Content/Blueprints/BP_DropItemInvComp.md b/Content/Blueprints/BP_DropItemInvComp.md index 61d2727..ee221b5 100644 --- a/Content/Blueprints/BP_DropItemInvComp.md +++ b/Content/Blueprints/BP_DropItemInvComp.md @@ -4,7 +4,7 @@ - **类型**: Blueprint (ActorComponent) - **父类**: BP_InventoryComp - **源文件**: /Game/Blueprints/Playground/BP_DropItemInvComp.BP_DropItemInvComp -- **模块**: Content +- **模块**: Content/Blueprints/Playground ## 功能概述 BP_DropItemInvComp 是掉落物品库存组件，继承 BP_InventoryComp 并增加了一个 FName 类型的 `Item` 变量，用于指定该掉落物包含什么物品类型。适用于可拾取的掉落物 Actor。 @@ -20,30 +20,39 @@ BP_DropItemInvComp 负责掉落物品的自动创建和作为可拾取物品容 |--------|------|--------| | BP_InventoryComp | 父类 | /Game/Blueprints/Playground/BP_InventoryComp | -## 对外接口 -- **蓝图变量**（is_instance_editable）： - - `Item` (FName) -- 掉落物品的类型名称，对应数据表中物品行的 RowName。在组件实例上设置，指定该掉落物包含什么物品 -- **继承自 BP_InventoryComp 的全部接口**： - - `DefaultContainer` -- 底层物品容器引用 - - `ViewCache` (TArray) -- 物品视图缓存 - - `OnViewChanged` -- 视图变化委托 - - `UpdateViewCache()` -- 刷新视图缓存 - - `CreateItemInternal(FName ItemType, int32 Count) -> bool` -- 创建物品 -- **继承自 BP_InventoryComp 的 IInventory 接口实现**： - - `GetItemViews()`、`GetItemViewByID()`、`GetItemCount()` -- 查询接口 - - `RequestMoveItem(ID, TargetInventory)` -- 请求移出物品（掉落物被拾取时调用） - - `ReceiveItem(ID, SourceContainer)` -- 从其他容器接收物品（拾取验证场景使用） -- **EventGraph**：含 2 个事件和 7 个节点，在 BeginPlay 时根据 `Item` 变量自动调用 CreateItemInternal +## 外部视角 + +BP_DropItemInvComp 是 BP_InventoryComp 的蓝图子类，从外部调用者视角： + +**新增属性（蓝图可读写）** +- `Item`（FName）— 掉落物包含的物品类型名称 + +**继承的行为** +- 继承 BP_InventoryComp 的全部接口：DefaultContainer、ViewCache、OnViewChanged、UpdateViewCache、CreateItemInternal +- 在 BeginPlay 时根据 Item 变量值自动调用 CreateItemInternal 创建对应物品 + +**外部交互方式** +- 作为 Actor 的组件（例如可拾取的掉落物 Actor） +- 玩家通过 IInventory 接口的 ReceiveItem 拾取物品 +- 外部系统通过父类 BP_InventoryComp 的接口操作 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | 组件创建时由引擎自动触发 | 调用父类 BeginPlay → Switch Has Authority → 读取 Item 变量 → 调用 CreateItemInternal 创建指定类型的掉落物品 | +| `事件Tick` | 原生覆盖 | 每帧 | 调用父类 Tick，无额外逻辑 | ## 使用方法 -- 作为 ActorComponent 添加到掉落物 Actor 上 -- 在组件实例上设置 `Item` 变量为数据表中物品的 RowName（FName 类型） -- 在 BeginPlay 事件中自动调用 `CreateItemInternal(Item, 1)` 创建物品，实现掉落物生成 -- 可以通过设置 `DefaultContainer` 覆盖默认的 BP_DefaultContainer -- 玩家拾取时，通过 IInventory::RequestMoveItem 将物品从掉落物容器转移至玩家库存 -- 掉落物的物理外观由所在的 Actor 负责，本组件仅处理物品数据的创建和转移 -- 继承自 BP_InventoryComp，所有库存管理功能均可用 + +BP_DropItemInvComp 在项目中的典型调用流程： + +- **掉落物初始化流程** — 掉落物 Actor 创建 → BP_DropItemInvComp.BeginPlay → 调用父类 BP_InventoryComp BeginPlay → 服务器端读取 Item 变量 → CreateItemInternal 创建指定类型的物品到容器 +- **玩家拾取流程** — 玩家与掉落物碰撞 → 通过 IInventory 接口 RequestMoveItem → DropItemInvComp 的 DefaultContainer 取出物品 → ReceiveItem 转移到玩家 InventoryComp ## 用例 -- 掉落物 Actor 的库存组件，在运行时自动生成配置的物品 -- 其父类 BP_InventoryComp 同时被 WBP_InventoryView 引用以显示物品列表 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| Playground | `/Game/地图关卡/Playground` | 关卡中掉落物 Actor 的组件，管理掉落物品 | +| BP_TestItem | `/Game/Blueprints/Playground/BP_TestItem` | 测试用物品管理组件 | diff --git a/Content/Blueprints/BP_Hud.md b/Content/Blueprints/BP_Hud.md index 15e7ad9..0f62da6 100644 --- a/Content/Blueprints/BP_Hud.md +++ b/Content/Blueprints/BP_Hud.md @@ -4,44 +4,64 @@ - **类型**: Blueprint (HUD) - **父类**: HUD - **源文件**: /Game/Blueprints/BP_Hud.BP_Hud -- **模块**: Content +- **模块**: Content/Blueprints ## 功能概述 -BP_Hud 是项目的 HUD 蓝图，管理三个 UI 窗口的引用：物品栏窗口（InvView，类型 WBP_InventoryView）、库存窗口（InventoryWindow）和提示窗口（HintWindow）。作为 UI 系统的"根"容器，持有并显示各种 Widget。 +游戏主 HUD，管理三个 UI 窗口的引用：物品栏视图（InvView → WBP_InventoryView）、库存窗口（InventoryWindow → WBP_Window）、提示窗口（HintWindow → WBP_Window），并在 EventGraph 中引用 BP_UniversalEndpointComp 处理端点通信。作为 UI 系统的根容器，负责 Widget 的创建和生命周期管理。 ## 设计用意 -BP_Hud 将 UI 管理集中在 HUD 中，而不是分散在各个 Widget 或 Controller 中。它将物品视图、库存窗口和提示窗口都集中持有在一个地方，作为 UI 系统的入口点，方便其他系统通过 HUD 访问和操作 UI。 +选择继承 Engine.HUD 而非在 PlayerController 或 Pawn 中管理 UI，是因为 HUD 是 UE 原生提供的 UI 渲染层入口，拥有独立的绘制生命周期（DrawHUD），且不干扰游戏逻辑层的更新频率。将三个核心窗口的引用集中到 HUD 后，其他系统只需要通过 PlayerController→GetHUD() 即可访问所有 UI 组件，避免了全局单例或漫长的引用传递链。 ## 职责范围 -BP_Hud 负责持有主要 UI 窗口引用并作为 UI 系统的入口点。具体的 UI 逻辑（物品列表渲染、窗口交互、提示显示）由各 Widget 自身负责，BP_Hud 仅提供引用的集中管理。 +- 在游戏初始化时创建 InvView、InventoryWindow、HintWindow 三个 Widget +- 持有这三个 Widget 的引用，作为其他系统获取 UI 实例的入口 +- 不介入各 Widget 内部的具体交互逻辑（物品渲染、窗口拖拽、提示内容由各自 Widget 负责） +- 不处理输入事件分发。 ## 项目内依赖 | 依赖项 | 关系 | 源文件 | |--------|------|--------| -| WBP_InventoryView | 引用 (InvView) | /Game/Blueprints/UI/Item/WBP_InventoryView | -| WBP_Window | 引用 (InventoryWindow, HintWindow) | /Game/Blueprints/UI/WBP_Window | +| WBP_InventoryView | 包含(变量InvView) | /Game/Blueprints/UI/Item/WBP_InventoryView | +| WBP_Window | 包含(变量InventoryWindow, HintWindow) | /Game/Blueprints/UI/WBP_Window | +| WBP_Hint | 引用(EventGraph) | /Game/Blueprints/UI/WBP_Hint | +| BP_UniversalEndpointComp | 引用(EventGraph) | /Game/Blueprints/Component/BP_UniversalEndpointComp | -## 对外接口 -- **蓝图可编辑变量**（均为 Instance Editable）： - - `InvView` (WBP_InventoryView_C*) -- 物品栏视图 Widget 引用，类型为 WBP_InventoryView - - `InventoryWindow` (WBP_Window_C*) -- 库存窗口 Widget 引用，类型为 WBP_Window - - `HintWindow` (WBP_Window_C*) -- 提示窗口 Widget 引用，类型为 WBP_Window -- **继承自 AHUD 的标准接口**： - - `DrawHUD()` -- HUD 绘制入口 - - `ReceiveDrawHUD(SizeX, SizeY)` -- 蓝图可覆盖的 UI 绘制事件 - - `GetOwningPlayerController()` -- 获取所属的 PlayerController - - HUD 生命周期事件（BeginPlay、EndPlay 等） -- **EventGraph**：含 4 个事件和 39 个节点，负责 Widget 的创建和初始化逻辑 +## 外部视角 + +BP_Hud 是纯蓝图 HUD（无 C++ 子类），从外部调用者视角： + +**公开 Widget 变量（蓝图可读写）** +- `InvView`（WBP_InventoryView_C*）— 物品栏视图 Widget 引用 +- `InventoryWindow`（WBP_Window_C*）— 库存窗口 Widget 引用 +- `HintWindow`（WBP_Window_C*）— 提示窗口 Widget 引用 + +上述三个变量均标记为 InstanceEditable，其他蓝图可通过 `GetPlayerController→GetHUD→Cast To BP_Hud_C` 访问。HUD 本身无自定义 BlueprintCallable 函数，所有交互通过操作这三个 Widget 引用间接完成。 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | HUD 创建时由引擎自动触发 | 创建 InventoryWindow、InvView、HintWindow 三个 Widget，添加到视口；绑定 BP_UniversalEndpointComp 的 Command Received 委托到 DealWithCommand | +| `DealWithCommand` | 自定义事件 | 收到 BP_UniversalEndpointComp 的指令数据包时 | 解析 CommandPacket → 提取 DiscreteMeta 中的 GameplayTag → 若匹配 "Gameplay.Action.UI.Hint" 则切换 HintWindow 显示/隐藏，否则切换 InventoryWindow 显示/隐藏 | + +**外部交互方式** +- 游戏模式在启动时自动创建 BP_Hud，并初始化三个子 Widget +- 外部系统获取 BP_Hud 实例后，通过读取其 Widget 变量访问 UI 组件 +- 指令路由系统通过 BP_UniversalEndpointComp 间接向 BP_Hud 发送 UI 控制指令 ## 使用方法 -- 在 BP_TestMode 中设置为 `HUDClass`，每次 PlayerController 初始化时自动创建 -- 在蓝图 EventGraph 中创建和初始化三个 Widget：`InvView`（物品栏）、`InventoryWindow`（库存窗口）、`HintWindow`（提示窗口） -- 三个 Widget 变量为 Instance Editable，可在编辑器中替换为不同的 Widget 子类 -- 其他系统通过 `PlayerController->GetHUD()` 获取 BP_Hud 实例，再通过变量访问各 Widget -- 作为 UI 系统的"根"容器，所有主要 UI 窗口的引用集中在此处管理 + +BP_Hud 是纯蓝图 HUD，在项目中通过以下调用链工作： + +- **游戏初始化流程** — 引擎启动游戏 → BP_TestMode 将 BP_Hud 设为 HUDClass → 生成 BP_Hud 实例 → 触发`事件开始运行` → 创建 InvView/InventoryWindow/HintWindow 三个 Widget 并添加到视口 +- **指令驱动的 UI 切换流程** — 外部系统（如 BP_ControllerComp）发送 CommandPacket → BP_UniversalEndpointComp 接收并派发 → BP_Hud 的 `DealWithCommand` 处理 → 解析 GameplayTag → 切换 HintWindow 或 InventoryWindow 的可见性 +- **外部访问 UI 组件流程** — 任何蓝图（如 BP_Barrel、BP_InventoryComp）→ GetPlayerController → GetHUD → Cast To BP_Hud_C → 直接读写 InvView/InventoryWindow/HintWindow 变量 ## 用例 -- BP_TestMode 的 `HUDClass`，玩家进入关卡时生成 -- `InvView` 变量引用 WBP_InventoryView，物品系统通过此引用更新物品列表 UI -- `InventoryWindow` 变量引用 WBP_Window，库存窗口的显示和隐藏通过此引用控制 -- `HintWindow` 变量引用 WBP_Window，提示信息的显示通过此引用控制 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_TestMode | `/Game/Blueprints/BP_TestMode` | 将 BP_Hud 设为 HUDClass，作为游戏全局 UI 根容器 | +| BP_TestCtl | `/Game/Blueprints/BP_TestCtl` | 通过 GetHUD 获取 BP_Hud，访问子 Widget | +| BP_Barrel | `/Game/Blueprints/Playground/BP_Barrel` | 通过 BP_Hud 获取 InventoryWindow 和 InvView，实现木桶 UI | +| BP_InventoryComp | `/Game/Blueprints/Playground/BP_InventoryComp` | 引用 BP_Hud 用于库存 UI 联动 | diff --git a/Content/Blueprints/BP_InventoryComp.md b/Content/Blueprints/BP_InventoryComp.md index d6f1d0e..f9a4467 100644 --- a/Content/Blueprints/BP_InventoryComp.md +++ b/Content/Blueprints/BP_InventoryComp.md @@ -4,7 +4,7 @@ - **类型**: Blueprint (ActorComponent) - **父类**: ActorComponent - **源文件**: /Game/Blueprints/Playground/BP_InventoryComp.BP_InventoryComp -- **模块**: Content +- **模块**: Content/Blueprints/Playground ## 功能概述 BP_InventoryComp 是库存管理组件，包装了一个 UDefaultContainer 实例，持有物品视图缓存和视图变化委托，提供物品创建和视图更新功能。它是物品系统与 Actor 之间的桥梁组件，也是 IInventory 接口的蓝图实现者。 @@ -23,32 +23,55 @@ BP_InventoryComp 负责持有并管理 UDefaultContainer 实例、维护 FItemVi | FItemView | 缓存 (ViewCache) | Item 插件 | | IInventory | 实现 | Item 插件 | -## 对外接口 -- **蓝图函数**： - - `UpdateViewCache()` -- 刷新 ViewCache，从 DefaultContainer 重新获取物品视图列表，同步缓存与底层容器状态 - - `CreateItemInternal(FName ItemType, int32 Count) -> bool` -- 内部物品创建函数，通过 DefaultContainer.CreateItem 创建物品后更新 ViewCache -- **蓝图变量**（均为 is_instance_editable）： - - `DefaultContainer` (DefaultContainer*/UDefaultContainer*) -- 底层物品容器引用，默认指向 BP_DefaultContainer - - `ViewCache` (TArray) -- 物品视图缓存数组，UI 从此读取显示数据，结构与 FItemView 一致（ItemID, ItemType, ItemName, ItemDescription, Icon, ItemDataText） - - `OnViewChanged` (动态多播委托) -- 视图变化通知委托，每次 ViewCache 更新时广播，供 UI 绑定自动刷新 -- **IInventory 接口实现**（BlueprintNativeEvent）： - - `GetItemViews() -> TArray` -- 返回所有物品视图 - - `GetItemViewByID(const FGuid& ItemID) -> FItemView` -- 按 ID 获取视图 - - `GetItemCount() -> int32` -- 物品数量 - - `RequestMoveItem(const FGuid& ItemID, const TScriptInterface& TargetInventory)` -- 请求移动物品到目标库存 - - `ReceiveItem(const FGuid& ItemID, const TScriptInterface& SourceContainer)` (BlueprintAuthorityOnly) -- 从源容器接收物品 -- **EventGraph**：含 7 个事件和 30 个节点，处理库存初始化和生命周期 +## 外部视角 + +BP_InventoryComp 是 ActorComponent 的子类（无 C++ 父类），从外部调用者视角： + +**公开属性（蓝图可读写）** +- `DefaultContainer`（UDefaultContainer*）— 关联的物品容器实例 +- `ViewCache`（TArray）— 物品视图缓存 + +**公开委托** +- `OnViewChanged`（多播委托）— 视图变化时广播，外部可绑定。触发时机：物品创建、移动、移除等导致 ViewCache 变更时 + +**自定义函数** +- `UpdateViewCache()` — 从 DefaultContainer 刷新 ViewCache 并触发 OnViewChanged +- `CreateItemInternal(FName ItemType, int32 Count)` → `bool` — 创建指定类型和数量的物品并放入容器 + +**外部交互方式** +- 作为组件添加到 Actor（如 BP_Barrel、BP_NewChar） +- UI 层（WBP_InventoryView）通过 Comp 变量引用，读取 ViewCache 渲染列表，绑定 OnViewChanged 监听变化 +- 其他系统通过组件引用的方式获取 BP_InventoryComp 并进行物品操作 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | 组件创建时由引擎自动触发 | 创建 BP_DefaultContainer → 判断网络权限：服务器端执行 GetOwner → Cast 到 Pawn → Controller → PlayerController → HUD → BP_Hud → InvView → BindToComp | +| `CreateItemRPCReplicated` | 自定义事件 (RPC, Server) | 客户端请求创建物品时 | 接收 ItemType 和 Count → 通过 IItemContainer 接口创建物品 | +| `MoveItemRPCReplicated` | 自定义事件 (RPC, Server) | 客户端请求移动物品时 | 接收 TargetInventory 和 ItemID → 通过 IInventory 接口移动物品到目标容器 | +| `UpdateViewCacheRPCReplicated` | 自定义事件 (RPC, Server) | 客户端请求刷新视图时 | 从 DefaultContainer 获取 ItemViews → 更新 ViewCache | +| `SyncViewCacheRPCReplicated` | 自定义事件 (RPC, All) | 服务器同步视图到所有客户端时 | 接收服务器端 ViewCache → 更新本地 ViewCache → 调用 OnViewChanged 委托通知 UI | +| `Client RPC` | 自定义事件 (RPC, Client) | 服务器通知客户端刷新 UI 时 | 获取 Owner → Cast 到 Pawn → Controller → PlayerController → HUD → BP_Hud → InvView → BindToComp | ## 使用方法 -- 作为 ActorComponent 添加到需要库存功能的 Actor 上 -- 设置 `DefaultContainer` 变量指向 BP_DefaultContainer 资产（或其他 IItemContainer 实现） -- UI (如 WBP_InventoryView) 绑定 `OnViewChanged` 委托，在库存变化时自动刷新 -- 调用 `CreateItemInternal(ItemType, Count)` 创建新物品，之后 ViewCache 自动更新 -- 通过 IInventory 接口与其他库存组件交互：`RequestMoveItem` 将物品移出，`ReceiveItem` 从其他容器接收物品 -- `UpdateViewCache` 在物品变化后同步缓存与底层容器的状态 -- 继承类 BP_DropItemInvComp 通过覆盖 BeginPlay 自动调用 CreateItemInternal + +BP_InventoryComp 在项目中的典型调用流程： + +- **库存初始化流程** — Actor（如 BP_Barrel）的 BP_InventoryComp 组件创建 → BeginPlay → 创建 BP_DefaultContainer → 服务端连接 HUD 的 InvView 绑定 UI +- **物品创建流程** — 客户端请求创建物品 → CreateItemRPCReplicated（RPC 到服务器）→ 通过 IItemContainer.CreateItem 创建 → 服务器触发 SyncViewCacheRPC → 更新所有客户端 ViewCache → OnViewChanged 通知 UI +- **UI 绑定流程** — WBP_InventoryView.BindToComp → 设置 Comp 变量引用 → 绑定 OnViewChanged 委托 → 库存变化时自动调用 UpdateListItems ## 用例 -- BP_DropItemInvComp 的父类，提供库存管理的通用基础 -- WBP_InventoryView 通过 `Comp` 变量引用此组件，读取 ViewCache 渲染物品列表 -- 添加到任何 Actor 上使其具备库存能力 + +BP_InventoryComp 被 11 个文件引用（项目内最广泛的组件之一），按用途分类： + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| WBP_InventoryView | `/Game/Blueprints/UI/Item/WBP_InventoryView` | 读取 ViewCache 渲染 UI，绑定 OnViewChanged 自动刷新 | +| BP_DropItemInvComp | `/Game/Blueprints/Playground/BP_DropItemInvComp` | 继承为掉落物组件，增加 Item 变量 | +| BP_Barrel | `/Game/Blueprints/Playground/BP_Barrel` | 组件实例，管理木桶内物品 | +| BP_InventoryDrop | `/Game/Blueprints/Playground/BP_InventoryDrop` | 组件实例，管理掉落物品 | +| BP_ItemTrap | `/Game/Blueprints/Playground/BP_ItemTrap` | 组件实例，管理陷阱物品 | +| BP_TestItem | `/Game/Blueprints/Playground/BP_TestItem` | 组件实例，测试物品管理 | +| BP_Bomb | `/Game/Blueprints/Playground/BP_Bomb` | 组件实例，管理炸弹物品 | diff --git a/Content/Blueprints/BP_InventoryDrop.md b/Content/Blueprints/BP_InventoryDrop.md new file mode 100644 index 0000000..03d756d --- /dev/null +++ b/Content/Blueprints/BP_InventoryDrop.md @@ -0,0 +1,56 @@ +# BP_InventoryDrop + +## 基本信息 +- **类型**: Blueprint (Actor) +- **父类**: Actor +- **源文件**: /Game/Blueprints/Playground/BP_InventoryDrop.BP_InventoryDrop +- **模块**: Content/Blueprints/Playground + +## 功能概述 +物品掉落物 Actor，在场景中代表可拾取的物品实体。没有自定义变量，通过 EventGraph（5 事件, 8 节点）处理与 BP_InventoryComp 的交互逻辑。 + +## 设计用意 +Playground 中用于测试物品掉落和拾取流程的 Actor，验证 Inventory 系统在场景物体层面的交互能力。 + +## 职责范围 +- 作为场景中的物品掉落实体存在 +- 通过 BP_InventoryComp 与库存系统交互 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| BP_InventoryComp | 引用 | /Game/Blueprints/Playground/BP_InventoryComp | + +## 外部视角 + +BP_InventoryDrop 是 Actor 的子类，从外部调用者视角： + +**接口概览** +- 无自定义变量 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | Actor 生成时 | 预留（当前无连线逻辑） | +| `事件Actor开始重叠` | 原生覆盖 (OnActorBeginOverlap) | 与其他 Actor 碰撞时 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | +| `On Component Begin Overlap (Box)` | 组件绑定事件 | 玩家进入掉落物触发区域时 | → 调用 ServerRPC | +| `ServerRPC` | 自定义事件 (RPC, Server) | 客户端触发拾取时 | 在服务器添加 BP_InventoryComp 组件 → 销毁自身 Actor | + +**外部交互方式** +- 放置在 Playground 关卡中作为可拾取的物品掉落实体 +- 通过 BP_InventoryComp 与库存系统交互（物品拾取） +- 无自定义公开函数，所有行为由事件驱动 + +## 使用方法 + +BP_InventoryDrop 在项目中的典型调用流程： + +- **物品拾取流程** — 玩家进入掉落物触发区域 → On Component Begin Overlap 触发 → 调用 ServerRPC（RPC 到服务器）→ 服务器端添加 BP_InventoryComp 组件并存入物品 → 销毁掉落物 Actor → 物品已转移到玩家库存 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| Playground | `/Game/地图关卡/Playground` | 关卡中的物品掉落物，演示拾取交互 | diff --git a/Content/Blueprints/BP_ItemTrap.md b/Content/Blueprints/BP_ItemTrap.md new file mode 100644 index 0000000..464a3b7 --- /dev/null +++ b/Content/Blueprints/BP_ItemTrap.md @@ -0,0 +1,65 @@ +# BP_ItemTrap + +## 基本信息 +- **类型**: Blueprint (Actor) +- **父类**: Actor +- **源文件**: /Game/Blueprints/Playground/BP_ItemTrap.BP_ItemTrap +- **模块**: Content/Blueprints/Playground + +## 功能概述 +物品陷阱 Actor，当触发时通过 GiveItems 函数向角色发放物品。持有 Container（interface 类型）变量引用容器接口，与 BP_DefaultContainer 和 BP_InventoryComp 协作。 + +## 设计用意 +Playground 中用于测试"触发式物品发放"机制的 Actor，验证容器接口（Container interface）在实际游戏物体上的挂载和调用流程。 + +## 职责范围 +- 持有容器接口引用（Container variable, interface 类型） +- 通过 GiveItems 函数发放物品 +- 通过 EventGraph（4 事件, 9 节点）处理触发逻辑 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| BP_NewChar | 引用 | /Game/Blueprints/BP_NewChar | +| BP_InventoryComp | 引用 | /Game/Blueprints/Playground/BP_InventoryComp | +| BP_DefaultContainer | 引用 | /Game/Blueprints/Playground/BP_DefaultContainer | + +## 外部视角 + +BP_ItemTrap 是 Actor 的子类，从外部调用者视角： + +**公开属性（蓝图可读写）** +- `Container`（IItemContainer 接口引用）— 关联的物品容器 + +**自定义函数** +- `GiveItems()` — 发放物品给目标角色 + +**核心行为** +- 被触发时调用 GiveItems 向 BP_NewChar 发放物品 +- 通过 Container 接口引用操作 BP_DefaultContainer + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | Actor 生成时由引擎自动触发 | 创建 BP_DefaultContainer → 存入 Container 变量 | +| `事件Actor开始重叠` | 原生覆盖 (OnActorBeginOverlap) | 其他 Actor 进入触发区域 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 调用 GiveItems 发放物品 | +| `事件RequestMoveItem` | 接口事件 (来自 Inventory 系统) | Inventory 系统请求移动物品时 | 通过 Container 获取容器 → ReceiveItem 接收物品 | + +**外部交互方式** +- 放置在 Playground 关卡中作为触发式陷阱 +- 玩家进入触发区域时自动发放物品 + +## 使用方法 + +BP_ItemTrap 在项目中的典型调用流程： + +- **陷阱初始化流程** — BeginPlay → 创建 BP_DefaultContainer → 存入 Container 变量 → 物品准备就绪 +- **物品发放流程** — Tick 每帧检测（或自定义触发）→ GiveItems → 从 Container 创建物品 → 通过 IInventory 接口发放到 BP_NewChar 的 InventoryComp + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| Playground | `/Game/地图关卡/Playground` | 关卡中的物品陷阱，演示触发式物品发放 | diff --git a/Content/Blueprints/BP_ItemViewDataView.md b/Content/Blueprints/BP_ItemViewDataView.md new file mode 100644 index 0000000..7663a68 --- /dev/null +++ b/Content/Blueprints/BP_ItemViewDataView.md @@ -0,0 +1,58 @@ +# BP_ItemViewDataView + +## 基本信息 +- **类型**: Blueprint (Object) +- **父类**: Object +- **源文件**: /Game/Blueprints/UI/Item/BP_ItemViewDataView.BP_ItemViewDataView +- **模块**: Content/Blueprints/UI/Item + +## 功能概述 +物品视图的数据视图对象，继承自 Object，作为物品展示的非 UI 数据层。持有 Index（int32）和 Inv（WBP_InventoryView_C*）两个变量，用于追踪当前视图索引和关联的库存视图。 + +## 设计用意 +将物品视图的数据逻辑与 UI 表现分离，作为 ViewModel 层存在。通过 Index 追踪当前浏览位置，通过 Inv 持有对 WBP_InventoryView 的引用以便更新 UI。 + +## 职责范围 +- 管理当前浏览物品的索引（Index） +- 持有库存视图引用（Inv）以便数据更新时同步 UI + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| WBP_InventoryView | 包含(变量) | /Game/Blueprints/UI/Item/WBP_InventoryView | + +## 外部视角 + +BP_ItemViewDataView 是 Object 的子类，从外部调用者视角： + +**公开属性（蓝图可读写）** +- `Index`（int32）— 当前浏览的物品索引位置 +- `Inv`（WBP_InventoryView_C*）— 关联的库存视图 Widget 引用 + +**接口概览** +- 无自定义函数，作为纯数据对象（ViewModel）存在 +- 通过 Index 追踪当前展示的物品位置 +- 通过 Inv 引用在数据更新时通知 WBP_InventoryView 刷新 UI + +**外部交互方式** +- 由 WBP_ItemViewBox 或 WBP_InventoryView 创建并使用 +- 外部系统可通过对象引用读取 Index 和 Inv + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| （无） | — | — | EventGraph 为空，作为纯数据对象 | + +## 使用方法 + +BP_ItemViewDataView 在项目中的典型调用流程： + +- **列表项绑定流程** — WBP_ItemViewBox 的列表项被设置 → BP_ItemViewDataView 对象传入 → 读取 Index 和 Inv → 从 InventoryComp 获取对应位置的物品数据 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| WBP_ItemViewBox | `/Game/Blueprints/UI/Item/WBP_ItemViewBox` | 引用作为物品视图的数据层 | +| WBP_InventoryView | `/Game/Blueprints/UI/Item/WBP_InventoryView` | 关联数据视图对象用于 UI 展示 | diff --git a/Content/Blueprints/BP_MoveInput.md b/Content/Blueprints/BP_MoveInput.md index 861e53e..2e9dd5a 100644 --- a/Content/Blueprints/BP_MoveInput.md +++ b/Content/Blueprints/BP_MoveInput.md @@ -4,7 +4,7 @@ - **类型**: Blueprint (ActorComponent) - **父类**: UEndpointComponent - **源文件**: /Game/Blueprints/Component/BP_MoveInput.BP_MoveInput -- **模块**: Content +- **模块**: Content/Blueprints/Component ## 功能概述 BP_MoveInput 是移动输入端点组件，持有对 CharacterMovementComponent 的引用（通过 CharMove 变量），将指令系统中的移动指令转化为实际的角色移动。 @@ -21,25 +21,40 @@ BP_MoveInput 负责接收移动指令并将其转换为 CharacterMovementCompone | UEndpointComponent | 父类 | CharacterControl 插件 | | UCharacterMovementComponent | 引用 (CharMove) | 引擎内置 | -## 对外接口 -- **蓝图变量**： - - `CharMove` (CharacterMovementComponent*) -- 持有对所属角色的 CharacterMovementComponent 引用，is_instance_editable，可在组件实例上配置 -- **继承自 UEndpointComponent 的接口**： - - `EndpointState` (FEndpointState) -- 端点状态，含 `InterestedTags` 配置关注的移动指令标签（如 "Command.Move"） - - `OnCommandReceived(const FCommandPacket& Command)` (BlueprintImplementableEvent) -- 收到移动指令时调用，在 EventGraph 中实现（node_count=22） - - `OnEndpointStateChanged` / `OnCommandOutput` -- 状态和输出委托 -- **通过 EventGraph 的行为**： - - 从 `Command.ContinuousPayload.ContinuousValue` 提取移动向量 (FVector3f) - - 调用 `CharMove` 的移动接口将向量转化为实际角色移动 +## 外部视角 + +BP_MoveInput 是 UEndpointComponent 的蓝图子类，从外部调用者视角： + +**公开属性（蓝图可读写）** +- `CharMove`（CharacterMovementComponent*）— 被控制的角色移动组件引用 + +**核心行为** +- 继承 UEndpointComponent 的 OnCommandReceived（BlueprintImplementableEvent），接收移动指令 +- 从 FCommandPacket.ContinuousPayload.ContinuousValue 中提取移动向量 +- 将移动向量应用至 CharMove 引用的 CharacterMovementComponent + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | 组件创建时由引擎自动触发 | 获取 Owner → 按类获取 CharacterMovementComponent → 存入 CharMove 变量 | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | +| `事件OnCommandReceived` | 委托事件 (EndpointComponent) | 收到指令路由系统派发的 CommandPacket | 解析 ContinuousPayload → 提取 ContinuousValue 向量 → 计算向前/向右移动分量 → 调用 CharacterMovementComponent.AddMovementInput | + +**外部交互方式** +- 作为 BP_TestChar 的组件自动创建 +- 指令系统通过 UCommandRouter 将匹配标签的指令路由到该组件 +- 不暴露自定义事件或委托 ## 使用方法 -- 作为 ActorComponent 添加到 BP_TestChar -- 设置 `CharMove` 变量指向所属角色的 `CharacterMovementComponent` -- 配置 `EndpointState.InterestedTags` 添加移动相关 GameplayTag（如 "Command.Move"） -- 设置 `EndpointState.bIsContinuousFriendly = true`（移动是连续指令） -- `UCommandRouterComponent` 自动发现并注册本组件为端点 -- 当 EnhancedInput 产生移动输入 -> UCommandInputComponent 生成 FCommandPacket -> UCommandRouterComponent 按标签匹配 -> 本组件的 OnCommandReceived 收到指令 -> 从 ContinuousPayload.ContinuousValue 提取 FVector3f -> 调用 CharacterMovementComponent 执行移动 + +BP_MoveInput 在项目中的典型调用流程： + +- **移动输入流程** — 指令系统派发移动指令 → OnCommandReceived 触发 → 解析 CommandPacket.ContinuousPayload.ContinuousValue → 提取移动向量 → 结合角色控制旋转计算前后/左右分量 → 调用 CharMove.AddMovementInput → CharacterMovementComponent 处理实际移动 ## 用例 -- BP_TestChar 的组件，处理移动指令 -- 通过 `CharMove` 变量连接 CharacterMovementComponent，实现指令到移动的桥接 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_TestChar | `/Game/Blueprints/BP_TestChar` | 作为端点组件添加到角色，执行移动指令 | +| BP_NewChar | `/Game/Blueprints/BP_NewChar` | 引用该组件处理角色移动输入 | diff --git a/Content/Blueprints/BP_NewChar.md b/Content/Blueprints/BP_NewChar.md new file mode 100644 index 0000000..456e9d8 --- /dev/null +++ b/Content/Blueprints/BP_NewChar.md @@ -0,0 +1,64 @@ +# BP_NewChar + +## 基本信息 +- **类型**: Blueprint (Character) +- **父类**: Character +- **源文件**: /Game/Blueprints/BP_NewChar.BP_NewChar +- **模块**: Content/Blueprints + +## 功能概述 +实验性角色蓝图，继承自 Character。作为一个轻量级角色模板，用于测试角色控制组件（BP_RouterComp）和移动输入组件（BP_MoveInput）的集成。不含自定义变量，仅包含 3 个事件和 3 个节点的简单事件图。 + +## 设计用意 +基础 Character 子类，作为角色控制功能（路由组件、移动输入）的挂载载体。不添加自定义逻辑，保持最小化以便在不同的测试场景中复用。 + +## 职责范围 +- 作为 Character 子类挂载 BP_RouterComp、BP_MoveInput、BP_SayHello 等组件 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| BP_RouterComp | 引用(组件) | /CharacterControl/BP_RouterComp | +| ABP_TestChar | 引用(动画) | /Game/Blueprints/Anim/ABP_TestChar | +| BP_MoveInput | 引用(组件) | /Game/Blueprints/Component/BP_MoveInput | +| BP_SayHello | 引用(组件) | /Game/Blueprints/Component/BP_SayHello | + +## 外部视角 + +BP_NewChar 是 Character 的子类，从外部调用者视角： + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | 角色生成时由引擎自动触发 | 预留（当前无连线逻辑） | +| `事件Actor开始重叠` | 原生覆盖 (OnActorBeginOverlap) | 与其他 Actor 碰撞时 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | + +**接口概览** +- 无自定义变量或公开函数 +- 极简事件图（3 事件, 3 节点） + +**组件装配** +- BP_RouterComp（来自 CharacterControl 插件）— 指令路由组件 +- BP_MoveInput — 移动输入端点组件 +- BP_SayHello — 指令测试端点组件 +- 动画蓝图类设为 ABP_TestChar + +**外部交互方式** +- BP_TestMode 可以在蓝图层将其设为默认 Pawn +- BP_ItemTrap 引用该角色，用于触发式物品发放的目标 + +## 使用方法 + +BP_NewChar 在项目中的典型调用流程： + +- **物品发放流程** — BP_ItemTrap 触发 → 通过 BP_NewChar 引用将物品发放到目标角色的 InventoryComp 中 +- **潜在游戏替换流程** — BP_TestMode 可替换 DefaultPawnClass 为 BP_NewChar → 引擎使用 BP_NewChar 替代 BP_TestChar 作为玩家角色 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_ItemTrap | `/Game/Blueprints/Playground/BP_ItemTrap` | 作为物品发放的目标角色引用 | +| BP_TestMode | `/Game/Blueprints/BP_TestMode` | 可能的 DefaultPawn 替代选择 | diff --git a/Content/Blueprints/BP_SayHello.md b/Content/Blueprints/BP_SayHello.md index d36839c..6676325 100644 --- a/Content/Blueprints/BP_SayHello.md +++ b/Content/Blueprints/BP_SayHello.md @@ -4,7 +4,7 @@ - **类型**: Blueprint (ActorComponent) - **父类**: UEndpointComponent - **源文件**: /Game/Blueprints/Component/BP_SayHello.BP_SayHello -- **模块**: Content +- **模块**: Content/Blueprints/Component ## 功能概述 BP_SayHello 是一个简单的测试/调试端点组件，用于验证 CharacterControl 指令路由系统是否正常工作。它没有任何自定义变量，仅覆盖 OnCommandReceived 事件输出 Hello 日志或消息。 @@ -20,24 +20,39 @@ BP_SayHello 负责验证指令路由系统的端到端工作流程，并作为 |--------|------|--------| | UEndpointComponent | 父类 | CharacterControl 插件 | -## 对外接口 -- **继承自 UEndpointComponent 的接口**： - - `EndpointState` (FEndpointState) -- 端点状态，含 `InterestedTags` 配置关注的指令标签 - - `OnCommandReceived(const FCommandPacket& Command)` (BlueprintImplementableEvent) -- 收到匹配指令时调用，在 EventGraph 中实现（4 个事件、27 个节点） - - `OnEndpointStateChanged` -- 状态变化委托 - - `OnCommandOutput` -- 命令输出委托 -- **无自定义蓝图变量**：纯行为型组件，不暴露状态数据 +## 外部视角 + +BP_SayHello 是 UEndpointComponent 的蓝图子类，从外部调用者视角： + +**接口概览** +- 无自定义变量或公开函数 +- 继承 UEndpointComponent 的 OnCommandReceived（BlueprintImplementableEvent），收到指令时输出日志 +- 纯测试/演示用途，不暴露可供外部调用的 API + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | 组件创建时由引擎自动触发 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | +| `事件OnCommandReceived` | 委托事件 (EndpointComponent) | 收到指令路由系统派发的 CommandPacket | 预留（当前无连线逻辑） | +| `Server RPC` | 自定义事件 (RPC, Server) | 客户端触发时 | 获取 Owner → 按类获取 BP_InventoryComp → 读取 ItemCount → 获取 ItemViews → 遍历输出物品信息到屏幕 | + +**外部交互方式** +- 作为 BP_TestChar 的组件自动创建 +- 指令系统通过 UCommandRouter 将匹配标签的指令路由到该组件 +- 外部系统无需直接与 BP_SayHello 交互 ## 使用方法 -- 作为 ActorComponent 添加到 BP_TestChar，用作测试端点 -- 配置 `EndpointState.InterestedTags` 添加测试用 GameplayTag（如 "Command.SayHello"） -- `OnCommandReceived` 事件在蓝图 EventGraph 中实现：收到指令后输出调试日志或 Hello 消息 -- 配合 EnhancedInput 的测试输入动作使用： - 1. EnhancedInput 产生输入 -> UCommandInputComponent 生成 FCommandPacket - 2. UCommandRouterComponent 按标签匹配路由到本组件 - 3. OnCommandReceived 触发，输出日志 -- 可作为新端点的实现模板：仅需在蓝图 EventGraph 中覆盖 `OnCommandReceived` 实现自定义行为 + +BP_SayHello 在项目中的典型调用流程： + +- **指令路由验证流程** — 测试输入触发 → UCommandRouter 路由指令到 BP_SayHello → OnCommandReceived 响应（当前未连线，为后续实现预留） +- **库存调试流程** — 客户端触发 Server RPC 事件 → 获取 Owner → 按类查找 BP_InventoryComp → 读取 ItemCount 和 ItemViews → 逐条打印物品 ID、类型、名称到屏幕 ## 用例 -- BP_TestChar 的组件，验证 CharacterControl 指令路由系统的端到端工作流程 -- 当 EnhancedInput 绑定到 "Command.SayHello" 指令时，输出响应消息 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_TestChar | `/Game/Blueprints/BP_TestChar` | 作为端点组件添加到角色，验证路由链路 | +| BP_NewChar | `/Game/Blueprints/BP_NewChar` | 引用该组件参与指令系统测试 | diff --git a/Content/Blueprints/BP_TestChar.md b/Content/Blueprints/BP_TestChar.md index d510066..9cddaa3 100644 --- a/Content/Blueprints/BP_TestChar.md +++ b/Content/Blueprints/BP_TestChar.md @@ -1,10 +1,10 @@ # BP_TestChar ## 基本信息 -- **类型**: Blueprint (Actor) +- **类型**: Blueprint (Character) - **父类**: AMyCharacter - **源文件**: /Game/Blueprints/BP_TestChar.BP_TestChar -- **模块**: Content +- **模块**: Content/Blueprints ## 功能概述 BP_TestChar 是玩家主角的蓝图实现，继承 C++ 的 AMyCharacter。它通过添加 CharacterControl 插件的路由组件来扩展角色能力，在蓝图层面组合移动、指令路由和摄像机控制。 @@ -18,7 +18,7 @@ BP_TestChar 是角色的蓝图配置层，负责添加并配置 CharacterControl ## 项目内依赖 | 依赖项 | 关系 | 源文件 | |--------|------|--------| -| AMyCharacter | 父类 | /Game/Blueprints/BP_TestChar (C++ 继承) | +| AMyCharacter | 父类 | Source/lonese/MyCharacter.h | | ACameraPawn | 间接（CameraActorClass） | /Game/Blueprints/BP_CameraPawn | | UCommandRouterComponent | 组件 | CharacterControl 插件 | | BP_UniversalEndpointComp | 组件 | /Game/Blueprints/Component/BP_UniversalEndpointComp | @@ -26,32 +26,43 @@ BP_TestChar 是角色的蓝图配置层，负责添加并配置 CharacterControl | BP_ControllerComp | 组件 | /Game/Blueprints/Component/BP_ControllerComp | | BP_SayHello | 组件 | /Game/Blueprints/Component/BP_SayHello | -## 对外接口 -- **继承自 AMyCharacter 的 BlueprintCallable 函数**： - - `Move(const FInputActionValue& Value)` -- 移动输入处理，供 EnhancedInput 绑定调用 - - `BeginRun(const FInputActionValue& Value)` / `StopRun(const FInputActionValue& Value)` -- 奔跑切换 - - `BeginCrouch(const FInputActionValue& Value)` / `StopCrouch(const FInputActionValue& Value)` -- 蹲伏切换 - - `IsRunning() const` / `IsCrouching() const` -- 状态查询 -- **继承自 AMyCharacter 的 BlueprintReadOnly 属性**： - - `DefaultMapping` (UInputMappingContext*) -- 默认输入映射上下文 - - `MoveAction`, `RunAction`, `CrouchAction`, `CameraMoveAction`, `CameraZoomAction`, `CameraResetAction`, `CameraRotateAction` -- 各输入动作引用 - - `CameraActorClass` (TSubclassOf) -- 摄像机 Pawn 类，设置为 BP_CameraPawn -- **身上的组件作为对外能力**： - - `UCommandRouterComponent` -- 指令路由中心，通过 RegisterEndpoint / InputCommand 接收和分发指令 - - `BP_UniversalEndpointComp` -- 通用端点，对外暴露 `CommandReceivedDispatcher` 动态多播委托 - - `BP_MoveInput` -- 移动端点，对外暴露 `CharMove` (CharacterMovementComponent*) 变量 - - `BP_ControllerComp` -- 摄像机控制端点，对外暴露 `MoveController`、`RotateController`、`ZoomCamera`、`ResetControllerLocation`、`TickFollowChar` 函数及摄像机配置参数 - - `BP_SayHello` -- 测试端点，验证指令路由系统 +## 外部视角 + +BP_TestChar 是 AMyCharacter 的蓝图子类，从外部调用者视角： + +**继承自 AMyCharacter 的配置属性（BlueprintReadOnly）** +- `DefaultMapping`（UInputMappingContext*）— 默认输入映射上下文 +- `MoveAction` / `RunAction` / `CrouchAction` / `CameraMoveAction` / `CameraZoomAction` / `CameraResetAction` / `CameraRotateAction`（UInputAction*）— 各输入动作 +- `CameraActorClass`（TSubclassOf）— 分离式摄像机类 + +**继承自 AMyCharacter 的操作函数（蓝图可调用）** +- `Move(FInputActionValue)` — 移动输入处理 +- `BeginRun` / `StopRun(FInputActionValue)` — 跑步状态切换 +- `BeginCrouch` / `StopCrouch(FInputActionValue)` — 蹲伏状态切换 +- `IsRunning()` / `IsCrouching()`（返回 bool）— 状态查询函数 + +**BP_TestChar 新增** +- 无自定义变量或公开函数。所有扩展能力通过组件化实现：4 个端点组件（UniversalEndpointComp/MoveInput/ControllerComp/SayHello）+ 1 个 UCommandRouterComponent +- CameraActorClass 在 Class Defaults 中设为 BP_CameraPawn + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | 角色生成时由引擎自动触发 | 预留（当前无连线逻辑） | +| `事件Actor开始重叠` | 原生覆盖 (OnActorBeginOverlap) | 角色与其他 Actor 碰撞时 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | ## 使用方法 -- 在 BP_TestMode 中设置为 `DefaultPawnClass`，作为项目的默认 Pawn -- 在蓝图编辑器中添加 CharacterControl 路由和端点组件：`UCommandRouterComponent` 作为指令路由器，`BP_UniversalEndpointComp`、`BP_MoveInput`、`BP_ControllerComp`、`BP_SayHello` 作为各类指令端点 -- 通过父类 AMyCharacter 的 `CameraActorClass` 属性指定 BP_CameraPawn 作为分离式摄像机 -- 配置父类的 InputAction 属性（MoveAction、RunAction 等）连接 EnhancedInput 系统 -- 各端点组件通过 `EndpointState.InterestedTags` 配置关注的 GameplayTag，UCommandRouterComponent 的 `AutoRegisterEndpoints` 在 BeginPlay 时自动注册所有组件上的端点 -- 指令链路：EnhancedInput -> UCommandInputComponent -> UCommandRouterComponent -> 匹配的端点组件 + +BP_TestChar 在项目中的典型调用流程： + +- **游戏初始化流程** — BP_TestMode 将 DefaultPawnClass 设为 BP_TestChar → 引擎在游戏启动时自动生成角色 → 初始化 4 个端点组件 + UCommandRouterComponent → 触发 BeginPlay +- **输入处理流程** — 玩家输入 → Enhanced Input 系统 → AMyCharacter::SetupPlayerInputComponent 绑定 Move/BeginRun/StopRun/BeginCrouch/StopCrouch → C++ 层处理移动和状态切换 +- **指令路由流程** — 外部指令 → UCommandRouterComponent → 路由到对应端点组件（如 BP_ControllerComp 处理摄像机控制、BP_MoveInput 处理移动指令） ## 用例 -- BP_TestMode 的 `DefaultPawnClass`，作为玩家进入关卡时的默认角色 -- 身上挂载的 `BP_UniversalEndpointComp`、`BP_MoveInput`、`BP_ControllerComp`、`BP_SayHello` 作为该角色的指令处理端点 -- `CameraActorClass` 属性引用 BP_CameraPawn，角色被 Possess 时自动生成摄像机 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_TestMode | `/Game/Blueprints/BP_TestMode` | 设为 DefaultPawnClass，作为玩家默认角色 | diff --git a/Content/Blueprints/BP_TestCtl.md b/Content/Blueprints/BP_TestCtl.md index 038ef03..0c5593e 100644 --- a/Content/Blueprints/BP_TestCtl.md +++ b/Content/Blueprints/BP_TestCtl.md @@ -4,7 +4,7 @@ - **类型**: Blueprint (PlayerController) - **父类**: AMyPlayerController - **源文件**: /Game/Blueprints/BP_TestCtl.BP_TestCtl -- **模块**: Content +- **模块**: Content/Blueprints ## 功能概述 BP_TestCtl 是项目的玩家控制器蓝图实现，继承 C++ 的 AMyPlayerController。它实现了 OnClientPossessFinished 事件用于 Possess 完成后的初始化，并提供 SetupControllingPawn 自定义函数用于控制权切换后的 Pawn 设置。 @@ -20,24 +20,41 @@ BP_TestCtl 负责 Possess 完成时的客户端初始化和控制权切换后的 |--------|------|--------| | AMyPlayerController | 父类 | C++ 源码 | -## 对外接口 -- **继承自 AMyPlayerController 的 BlueprintCallable 函数**： - - `GetOwnedPawn()` -- 获取当前控制的 Pawn，返回 APawn*，供蓝图查询当前 Possess 目标 -- **继承自 AMyPlayerController 的 BlueprintImplementableEvent 事件**： - - `OnClientPossessFinished(APawn* P)` -- 客户端 Possess 完成时调用，在 BP_TestCtl 的 EventGraph 中实现，客户端收到 Possess 确认后的初始化入口（EventGraph 中 event_count=3） -- **蓝图自定义函数**： - - `SetupControllingPawn()` -- 控制权切换后的 Pawn 设置函数，无参数，在 EventGraph 的 18 个节点中被调用 -- **继承自 APlayerController 的标准接口**：所有 APlayerController 的标准事件和函数均可用（如 OnPossess、OnUnPossess、GetPlayerViewPoint 等） +## 外部视角 + +BP_TestCtl 是 AMyPlayerController 的蓝图子类，从外部调用者视角： + +**继承自 AMyPlayerController 的公开接口** +- `GetOwnedPawn()`（BlueprintCallable）— 获取当前控制器拥有的 Pawn 实例，C++ 默认实现 +- `OnClientPossessFinished(APawn* P)`（BlueprintImplementableEvent）— Possess 完成时的客户端初始化事件，蓝图可选择性实现 + +**BP_TestCtl 新增** +- `SetupControllingPawn`（EventGraph 中定义的自定义函数）— 控制权切换后调用，用于初始化被控制 Pawn 的状态。无公开 BlueprintCallable 标注，在蓝图层内部调用 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | 控制器创建时由引擎自动触发 | 延迟 0.2 秒 → 显示鼠标光标 → 设置视图目标为自引用的 Possessed Pawn → 获取 HUD → Cast 到 BP_Hud → 获取 CommandRouter → 注册内部路由端点 | +| `事件OnClientPossessFinished` | 原生覆盖 | 客户端 Possess 流程完成后 | 调用 SetupControllingPawn → 获取 BP_Controller 组件 → 调用 ResetControllerLocation | +| `UpdateInvComp_RPCReplicated` | 自定义事件 (RPC) | 客户端库存变化时 | 接收 BP_InventoryComp 引用 → 调用服务器端 UpdateViewCache, 客户端 UpdateViewCacheRPC | + +**外部交互方式** +- 引擎通过 GameMode 的 PlayerControllerClass 设置自动创建实例（BP_TestMode 中配置） +- C++ 层通过 `Cast` 获取引用 +- 蓝图层通过 `GetPlayerController` 节点获取 ## 使用方法 -- 在 BP_TestMode 中设置为 `PlayerControllerClass`，作为项目的默认玩家控制器 -- 父类 AMyPlayerController 重写了 `CalcCamera`（空操作），禁用默认摄像机计算，配合 ACameraPawn 的分离式摄像机设计 -- 父类 AMyPlayerController 重写了 `AcknowledgePossession`，在 Possess 确认后触发 `OnClientPossessFinished` 事件 -- `OnClientPossessFinished` 在蓝图 EventGraph 中实现，用于客户端在 Possess 完成后的初始化逻辑 -- `SetupControllingPawn` 在控制权切换时调用，设置新的受控 Pawn 所需的配置（如 UI 绑定、输入上下文切换等） -- 作为薄蓝图层，主要职责是将 C++ 层的控制器能力暴露给蓝图系统 + +BP_TestCtl 在项目中的典型调用流程： + +- **游戏初始化流程** — BP_TestMode 将 PlayerControllerClass 设为 BP_TestCtl → 引擎自动实例化 → 触发 BeginPlay → 延迟后显示鼠标光标、设置视图目标、从 HUD 获取 CommandRouter 并注册端点 +- **Possess 完成流程** — 引擎 Possess Pawn 完成后 → 触发 OnClientPossessFinished → SetupControllingPawn → 获取 BP_ControllerComp → 调用 ResetControllerLocation 重置摄像机 +- **库存同步流程** — 客户端库存变化 → UpdateInvComp_RPCReplicated 触发 → 服务器端更新 ViewCache → 客户端同步刷新 ## 用例 -- BP_TestMode 的 `PlayerControllerClass`，每次玩家加入时实例化 -- `OnClientPossessFinished` 事件连接客户端 Possess 完成的初始化流程 -- `SetupControllingPawn` 在角色切换时重新配置 Pawn 资源 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_TestMode | `/Game/Blueprints/BP_TestMode` | 设为 PlayerControllerClass，游戏启动时自动实例化 | +| BP_Barrel | `/Game/Blueprints/Playground/BP_Barrel` | 引用 BP_TestCtl 用于木桶交互 | diff --git a/Content/Blueprints/BP_TestItem.md b/Content/Blueprints/BP_TestItem.md new file mode 100644 index 0000000..7e6f9d2 --- /dev/null +++ b/Content/Blueprints/BP_TestItem.md @@ -0,0 +1,58 @@ +# BP_TestItem + +## 基本信息 +- **类型**: Blueprint (Actor) +- **父类**: Actor +- **源文件**: /Game/Blueprints/Playground/BP_TestItem.BP_TestItem +- **模块**: Content/Blueprints/Playground + +## 功能概述 +Playground 中的测试用物品 Actor，用于验证物品系统的基础功能。通过 EventGraph（4 事件, 23 节点）处理与 BP_InventoryComp 和 BP_DropItemInvComp 的交互逻辑。 + +## 设计用意 +Playground 场景中的通用测试物品载体，用于验证物品的生成、持有、丢弃等基础流程。作为物品系统在场景中的最小可测试单元。 + +## 职责范围 +- 作为场景中的测试物品 Actor 存在 +- 通过 BP_InventoryComp 和 BP_DropItemInvComp 与库存系统交互 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| BP_InventoryComp | 引用 | /Game/Blueprints/Playground/BP_InventoryComp | +| BP_DropItemInvComp | 引用 | /Game/Blueprints/Playground/BP_DropItemInvComp | + +## 外部视角 + +BP_TestItem 是 Actor 的子类，从外部调用者视角： + +**接口概览** +- 无自定义变量 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | Actor 生成时 | 预留（当前无连线逻辑） | +| `事件Actor开始重叠` | 原生覆盖 (OnActorBeginOverlap) | 与其他 Actor 碰撞时 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | +| `On Component Begin Overlap (Collison)` | 组件绑定事件 | 玩家进入物品触发区域时 | 检查 BP_DropItemInvComp 有效 → 获取 ItemCount → 获取 ItemViews → 打印物品名称和数量 → 延迟 → 通过 BP_DropItemInvComp.RequestMoveItem 转移物品 → 销毁自身 | + +**外部交互方式** +- 放置在 Playground 关卡中作为测试物品实体 +- 通过 BP_InventoryComp 和 BP_DropItemInvComp 与库存系统交互 +- 由 BP_TestItemCluster 生成和管理 + +## 使用方法 + +BP_TestItem 在项目中的典型调用流程： + +- **物品拾取流程** — 玩家进入测试物品触发区域 → On Component Begin Overlap → 验证 DropItemInvComp 有效 → 打印物品信息到屏幕 → RequestMoveItem 转移物品到玩家库存 → 延迟后销毁自身 Actor +- **批量生成流程** — BP_TestItemCluster 在场景中生成多个 BP_TestItem 子 Actor → 每个作为独立物品实例 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| Playground | `/Game/地图关卡/Playground` | 关卡中的测试物品，验证物品系统基础流程 | +| BP_TestItemCluster | `/Game/Blueprints/Playground/BP_TestItemCluster` | 作为模板批量生成测试物品 | diff --git a/Content/Blueprints/BP_TestItemCluster.md b/Content/Blueprints/BP_TestItemCluster.md new file mode 100644 index 0000000..a96c0c8 --- /dev/null +++ b/Content/Blueprints/BP_TestItemCluster.md @@ -0,0 +1,54 @@ +# BP_TestItemCluster + +## 基本信息 +- **类型**: Blueprint (Actor) +- **父类**: Actor +- **源文件**: /Game/Blueprints/Playground/BP_TestItemCluster.BP_TestItemCluster +- **模块**: Content/Blueprints/Playground + +## 功能概述 +物品簇 Actor，在场景中生成一组测试物品。通过 EventGraph（4 事件, 15 节点）管理多个 BP_TestItem 的生成和排列，用于测试场景中大量物品的呈现效果。 + +## 设计用意 +Playground 中用于测试批量物品生成和布局的 Actor，依赖 BP_TestItem 作为子物品模板，验证物品在场景中的集群表现。 + +## 职责范围 +- 生成和管理多个 BP_TestItem 实例 +- 控制物品簇在场景中的布局 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| BP_TestItem | 引用(子物品) | /Game/Blueprints/Playground/BP_TestItem | + +## 外部视角 + +BP_TestItemCluster 是 Actor 的子类，从外部调用者视角： + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | Actor 生成时 | 设置定时器 → 10秒后触发 Resume | +| `事件Actor开始重叠` | 原生覆盖 (OnActorBeginOverlap) | 与其他 Actor 碰撞时 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | +| `Resume` | 自定义事件 | 定时器触发时 | 获取 DefaultSceneRoot 的子组件 → ForEach → Cast 到 ChildActorComponent → 验证 ChildActor 存在 → 取反销毁标记 → 设置新的 ChildActorClass | + +**接口概览** +- 无自定义变量或公开函数 + +**外部交互方式** +- 放置在 Playground 关卡中，在场景中生成一组 BP_TestItem 实例 +- 外部系统不直接与 BP_TestItemCluster 交互，通过关卡引用访问 + +## 使用方法 + +BP_TestItemCluster 在项目中的典型调用流程： + +- **物品簇生成流程** — BeginPlay → 设置 Resume 定时器（10秒循环）→ 定时器触发 → 遍历子 ChildActorComponent → 随机切换子 Actor 类 → 测试不同物品类型的批量展示 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| Playground | `/Game/地图关卡/Playground` | 关卡中的物品簇，演示批量物品生成和布局 | diff --git a/Content/Blueprints/BP_TestMode.md b/Content/Blueprints/BP_TestMode.md index c857d2a..80438f3 100644 --- a/Content/Blueprints/BP_TestMode.md +++ b/Content/Blueprints/BP_TestMode.md @@ -4,7 +4,7 @@ - **类型**: Blueprint (GameMode) - **父类**: GameModeBase - **源文件**: /Game/Blueprints/BP_TestMode.BP_TestMode -- **模块**: Content +- **模块**: Content/Blueprints ## 功能概述 BP_TestMode 是项目的 GameMode 蓝图，配置默认的 Pawn、PlayerController 和 HUD 类，将项目的所有核心类串联起来。 @@ -22,26 +22,38 @@ BP_TestMode 负责配置默认游戏类和串联项目核心类型之间的关 | BP_TestCtl | PlayerController | /Game/Blueprints/BP_TestCtl | | BP_Hud | HUD | /Game/Blueprints/BP_Hud | -## 对外接口 -- **继承自 AGameModeBase 的标准接口**： - - GameMode 生命周期事件：`InitGame`、`PreLogin`、`PostLogin`、`Logout`、`RestartPlayer`、`SpawnDefaultPawnAtTransform` 等，均可在蓝图 EventGraph 中覆盖（EventGraph 中 event_count=2, node_count=2） - - `GetDefaultPawnClassForController` -- 返回配置的 DefaultPawnClass - - GameMode 的标准函数和事件均继承可用 -- **编辑器配置属性**（通过 GameMode 基类继承）： - - `DefaultPawnClass` = BP_TestChar -- 默认 Pawn 类型 - - `PlayerControllerClass` = BP_TestCtl -- 玩家控制器类型 - - `HUDClass` = BP_Hud -- HUD 类型 - - 其他 GameMode 标准配置属性（GameStateClass、SpectatorClass 等） +## 外部视角 + +BP_TestMode 是 GameModeBase 的蓝图子类，从外部调用者视角： + +**核心配置（Class Defaults 中设置）** +- `DefaultPawnClass` = BP_TestChar — 玩家生成时使用的默认 Pawn +- `PlayerControllerClass` = BP_TestCtl — 玩家控制器类 +- `HUDClass` = BP_Hud — 游戏 HUD 类 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | GameMode 创建时由引擎自动触发 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | + +**无自定义公开接口** +BP_TestMode 不添加自定义函数或变量，所有行为通过引擎框架的 GameMode 生命周期事件驱动。 + +**外部交互方式** +- 关卡地图在 World Settings 中选择 BP_TestMode 作为默认 GameMode +- 引擎在游戏启动时自动读取其 Class Defaults 配置并实例化引用类 ## 使用方法 -- 在关卡的世界设置（World Settings）中将 `GameMode Override` 设置为 BP_TestMode -- 或在项目设置中将其设为默认 GameMode，应用于所有关卡 -- 配置三个核心 class 属性，将 BP_TestChar、BP_TestCtl、BP_Hud 串联为一个完整游戏框架 -- EventGraph 中无额外蓝图逻辑（node_count=2），纯配置型蓝图，所有替换只需修改此文件中的属性值 -- 项目有且仅有一个 GameMode，所有核心类型的替换集中在此处管理 + +BP_TestMode 在项目中的典型调用流程： + +- **游戏启动流程** — 关卡（Map_City/Playground）在 World Settings 中引用 BP_TestMode → 引擎读取 Class Defaults → 自动创建 BP_TestChar（DefaultPawn）、BP_TestCtl（PlayerController）、BP_Hud（HUDClass）→ 三者自动配对 ## 用例 -- 关卡 World Settings 的 `GameMode Override`，引擎启动时加载 -- `DefaultPawnClass=BP_TestChar` -- 新玩家进入时自动生成该 Pawn -- `PlayerControllerClass=BP_TestCtl` -- 新玩家连接时自动创建该控制器 -- `HUDClass=BP_Hud` -- 创建控制器时自动生成该 HUD + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| Map_City | `/Game/地图关卡/Map_City` | 设为关卡的默认 GameMode，驱动该地图运行时配置 | +| Playground | `/Game/地图关卡/Playground` | 设为关卡的默认 GameMode，驱动该地图运行时配置 | diff --git a/Content/Blueprints/BP_Trap.md b/Content/Blueprints/BP_Trap.md new file mode 100644 index 0000000..65503fe --- /dev/null +++ b/Content/Blueprints/BP_Trap.md @@ -0,0 +1,56 @@ +# BP_Trap + +## 基本信息 +- **类型**: Blueprint (Actor) +- **父类**: Actor +- **源文件**: /Game/Blueprints/Playground/BP_Trap.BP_Trap +- **模块**: Content/Blueprints/Playground + +## 功能概述 +陷阱 Actor，在 Playground 场景中作为危险区域。通过 EventGraph（5 事件, 10 节点）处理玩家进入/触发逻辑。无自定义变量，无项目内依赖。 + +## 设计用意 +Playground 中用于测试陷阱触发机制的 Actor，验证角色与场景危险物体的碰撞和反馈交互。 + +## 职责范围 +- 作为场景中的陷阱区域，处理触发检测逻辑 +- 不依赖其他项目内资产，独立运作 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| （无） | — | — | + +## 外部视角 + +BP_Trap 是 Actor 的子类，从外部调用者视角： + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | Actor 生成时 | 预留（当前无连线逻辑） | +| `事件Actor开始重叠` | 原生覆盖 (OnActorBeginOverlap) | 其他 Actor 进入触发区域 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | +| `On Component Begin Overlap (Collision)` | 组件绑定事件 | 玩家碰撞体进入陷阱区域时 | 按类获取 CharacterMovementComponent → 调用 LaunchActorRPC | +| `LaunchActorRPC` | 自定义事件 (RPC, Server) | 客户端触发时 | 获取 Owner → Cast 到 Character → 调用 LaunchCharacter（向上弹射 1000 单位） | + +**接口概览** +- 无自定义变量、无公开函数、无项目内依赖 + +**外部交互方式** +- 放置在 Playground 关卡中作为危险区域 +- 玩家进入触发区域时处理伤害/反馈逻辑 +- 外部系统无需直接与 BP_Trap 交互 + +## 使用方法 + +BP_Trap 在项目中的典型调用流程： + +- **陷阱触发流程** — 玩家进入陷阱碰撞区域 → On Component Begin Overlap → 获取 CharacterMovementComponent → 调用 LaunchActorRPC（RPC 到服务器）→ Cast 到 Character → LaunchCharacter（向上弹射） + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| Playground | `/Game/地图关卡/Playground` | 关卡中的陷阱区域，演示碰撞触发交互 | diff --git a/Content/Blueprints/BP_UniversalEndpointComp.md b/Content/Blueprints/BP_UniversalEndpointComp.md index 6ce3723..4ccd1fd 100644 --- a/Content/Blueprints/BP_UniversalEndpointComp.md +++ b/Content/Blueprints/BP_UniversalEndpointComp.md @@ -4,7 +4,7 @@ - **类型**: Blueprint (ActorComponent) - **父类**: UEndpointComponent - **源文件**: /Game/Blueprints/Component/BP_UniversalEndpointComp.BP_UniversalEndpointComp -- **模块**: Content +- **模块**: Content/Blueprints/Component ## 功能概述 BP_UniversalEndpointComp 是通用指令端点组件，继承 CharacterControl 的 UEndpointComponent。它添加了 `CommandReceivedDispatcher` 事件分发器委托，让其他蓝图可以动态绑定到该端点的指令接收事件，无需创建新子类。 @@ -20,25 +20,40 @@ BP_UniversalEndpointComp 负责提供外部的指令接收委托，将内部事 |--------|------|--------| | UEndpointComponent | 父类 | CharacterControl 插件 | -## 对外接口 -- **蓝图变量**： - - `CommandReceivedDispatcher` (动态多播委托) -- 指令接收事件分发器，is_instance_editable，其他蓝图可绑定此委托接收指令通知 -- **继承自 UEndpointComponent 的接口**： - - `EndpointState` (FEndpointState) -- 端点状态，含 `EndpointGuid`、`InterestedTags` (FGameplayTagContainer)、`bIsActive`、`bIsContinuousFriendly`、`bIsAsynchronous` - - `OnCommandReceived(const FCommandPacket& Command)` (BlueprintImplementableEvent) -- 收到匹配指令时调用，可在蓝图子类或本蓝图 EventGraph 中实现 - - `OnEndpointStateChanged` (FOnEndpointStateChanged) -- 状态变化委托 - - `OnCommandOutput` (FOnCommandOutput) -- 命令输出委托 -- **继承自 ICommandEndpoint 接口**： - - `ReceiveCommand_BP(const FCommandPacket& Command)` (BlueprintNativeEvent) -- 蓝图版本的指令接收入口 - - `GetEndpointDispatcher_BP()` (BlueprintNativeEvent) -- 获取端点分发器 +## 外部视角 + +BP_UniversalEndpointComp 是 UEndpointComponent 的蓝图子类，从外部调用者视角： + +**公开属性（蓝图可读写）** +- `CommandReceivedDispatcher`（多播委托）— 指令接收事件分发器 + +**核心行为** +- 继承 UEndpointComponent 的 OnCommandReceived（BlueprintImplementableEvent），在收到指令时触发 +- 在 OnCommandReceived 实现中将指令转发为 CommandReceivedDispatcher 广播 +- 外部蓝图可通过 Bind Event 节点绑定到 CommandReceivedDispatcher，无需新建 Endpoint 子类 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件开始运行` | 原生覆盖 (BeginPlay) | 组件创建时 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | +| `事件OnCommandReceived` | 委托事件 (EndpointComponent) | 收到指令路由系统派发的 CommandPacket | 调用 CommandReceivedDispatcher 广播给所有绑定的外部蓝图 | + +**外部交互方式** +- 作为 BP_TestChar 的组件自动创建 +- 外部蓝图通过组件引用的方式获取实例，绑定 CommandReceivedDispatcher ## 使用方法 -- 作为 ActorComponent 添加到 BP_TestChar 等需要通用指令处理的 Actor 上 -- 配置 `EndpointState.InterestedTags` 指定该端点关注的 GameplayTag 集合 -- 外部蓝图通过绑定 `CommandReceivedDispatcher` 委托来监听指令，无需创建新的端点子类 -- EventGraph 中当 `OnCommandReceived` 触发时，自动广播 `CommandReceivedDispatcher`，将内部事件转发为外部委托 -- `UCommandRouterComponent` 在 BeginPlay 时通过 `AutoRegisterEndpoints` 自动发现并注册本组件 + +BP_UniversalEndpointComp 在项目中的典型调用流程： + +- **指令转发流程** — UCommandRouter 派发指令 → OnCommandReceived 触发 → 调用 CommandReceivedDispatcher 广播 → 所有绑定了该委托的外部蓝图（如 BP_Hud 的 DealWithCommand）同时收到指令 +- **事件绑定流程** — 外部蓝图（如 BP_Hud 的 BeginPlay）→ 获取 BP_UniversalEndpointComp 引用 → Bind Event to CommandReceivedDispatcher → 创建自定义事件处理指令 ## 用例 -- BP_TestChar 的组件，作为通用指令端点接收路由来的指令 -- 外部蓝图通过绑定 `CommandReceivedDispatcher` 订阅指令事件 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_TestChar | `/Game/Blueprints/BP_TestChar` | 作为端点组件添加到角色，接收并转发指令 | +| BP_Hud | `/Game/Blueprints/BP_Hud` | 在 EventGraph 中引用，用于端点通信 | diff --git a/Content/Blueprints/WBP_ChoiceButton.md b/Content/Blueprints/WBP_ChoiceButton.md new file mode 100644 index 0000000..c29b05b --- /dev/null +++ b/Content/Blueprints/WBP_ChoiceButton.md @@ -0,0 +1,61 @@ +# WBP_ChoiceButton + +## 基本信息 +- **类型**: WidgetBlueprint (UserWidget) +- **父类**: UserWidget +- **源文件**: /Game/Blueprints/UI/Dialog/WBP_ChoiceButton.WBP_ChoiceButton +- **模块**: Content/Blueprints/UI/Dialog + +## 功能概述 +对话选项按钮 Widget，用于对话框系统中的分支选择。持有 Executor（interface）、Name（FName）、ButtonText（FText）三个变量。InitButton 函数初始化按钮的 executor、名称和文本，Get_Text_Text 返回按钮显示文本。 + +## 设计用意 +对话框系统中用于呈现玩家可选分支的 UI 按钮，通过 Executor 接口与对话执行器通信，Name 标识选项标识符。 + +## 职责范围 +- 渲染对话框分支选项按钮 +- 通过 Executor 接口将选项选择结果传递给对话执行系统 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| （无） | — | — | + +## 外部视角 + +WBP_ChoiceButton 是 UserWidget 的子类，从外部调用者视角： + +**公开属性（蓝图可读写）** +- `Executor`（接口引用）— 对话执行器接口 +- `Name`（FName）— 选项标识符 +- `ButtonText`（FText）— 按钮显示文本 + +**自定义函数** +- `InitButton(InEx(接口), InName(FName), InText(FText))` — 初始化按钮的执行器、名称和文本 +- `Get_Text_Text()` → `FText` — 返回按钮的显示文本（用作绑定） + +**外部交互方式** +- 由 WBP_TestUI（对话框 UI）在 SummonChoiceButtons 中动态创建 +- 点击按钮时通过 Executor 接口将选择结果传递给对话执行系统 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件预构造` | 原生覆盖 (PreConstruct) | Widget 创建时 | 预留（当前无连线逻辑） | +| `事件构造` | 原生覆盖 (Construct) | Widget 创建完成后 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | +| `On Clicked (MainButton)` | 组件绑定事件 | 用户点击按钮时 | 获取 Executor → 获取 Name → 通过 UDialogPresentationSubsystem 调用 ShowDialog 传递选择结果 | + +## 使用方法 + +WBP_ChoiceButton 在项目中的典型调用流程： + +- **选项生成流程** — WBP_TestUI.SummonChoiceButtons → 动态创建 WBP_ChoiceButton 实例 → InitButton 设置 Executor/Name/ButtonText → 挂接到面板 +- **选项选择流程** — 用户点击按钮 → On Clicked (MainButton) → 获取 Executor 接口和 Name → 通过 UDialogPresentationSubsystem.ShowDialog 传递选择 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| WBP_TestUI | `/Game/Blueprints/UI/Dialog/WBP_TestUI` | 动态生成并初始化，用于玩家对话分支选择 | diff --git a/Content/Blueprints/WBP_Circle.md b/Content/Blueprints/WBP_Circle.md new file mode 100644 index 0000000..a2e7777 --- /dev/null +++ b/Content/Blueprints/WBP_Circle.md @@ -0,0 +1,59 @@ +# WBP_Circle + +## 基本信息 +- **类型**: WidgetBlueprint (UserWidget) +- **父类**: UserWidget +- **源文件**: /Game/Blueprints/UI/Dialog/WBP_Circle.WBP_Circle +- **模块**: Content/Blueprints/UI/Dialog + +## 功能概述 +环形进度条 Widget，用于显示精度/进度值。提供 `设置精度条(Value: float)` 函数设置进度值。EventGraph 含 3 个事件和 3 个节点。 + +## 设计用意 +对话框系统中的 UI 辅助组件，以环形进度条形式展示某个数值状态（如对话计时、资源进度等）。 + +## 职责范围 +- 渲染环形进度条 +- 通过 `设置精度条` 函数更新当前进度值 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| 血条框1 | 引用(纹理) | /Game/Arts/UI/纹理/血条框1 | +| 环型血条_Inst | 引用(材质) | /Game/Arts/UI/血条/环型血条_Inst | + +## 外部视角 + +WBP_Circle 是 UserWidget 的子类，从外部调用者视角： + +**自定义函数** +- `设置精度条(Value: float)` — 更新环形进度条的当前值 + +**接口概览** +- 无公开变量 +- 仅提供单个公开函数用于更新进度值 +- EventGraph 极简（3 事件, 3 节点），无额外事件处理 + +**外部交互方式** +- 由 WBP_Module1 创建并嵌入 +- 外部通过 Widget 引用调用 `设置精度条` 更新进度显示 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件预构造` | 原生覆盖 (PreConstruct) | Widget 创建时 | 预留（当前无连线逻辑） | +| `事件构造` | 原生覆盖 (Construct) | Widget 创建完成后 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | + +## 使用方法 + +WBP_Circle 在项目中的使用方式： + +- **WBP_Module1**（`/Game/Blueprints/UI/WBP_Module1`）— 作为子 Widget 嵌入，在 UI 模块中显示环形进度 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| WBP_Module1 | `/Game/Blueprints/UI/WBP_Module1` | 嵌入作为对话框环形进度显示组件 | diff --git a/Content/Blueprints/WBP_Hint.md b/Content/Blueprints/WBP_Hint.md new file mode 100644 index 0000000..a8498b6 --- /dev/null +++ b/Content/Blueprints/WBP_Hint.md @@ -0,0 +1,58 @@ +# WBP_Hint + +## 基本信息 +- **类型**: WidgetBlueprint (UserWidget) +- **父类**: UserWidget +- **源文件**: /Game/Blueprints/UI/WBP_Hint.WBP_Hint +- **模块**: Content/Blueprints/UI + +## 功能概述 +提示信息 Widget，用于在游戏中显示浮层提示。持有 EndpointD（EndpointDispatcher*）变量，可能用于处理与端点调度器的通信。EventGraph 含 3 个事件和 3 个节点。 + +## 设计用意 +作为游戏中的通用提示 UI，通过 EndpointD 与 EndpointDispatcher 对接，接收并显示来自命令系统的提示信息。 + +## 职责范围 +- 显示提示信息 +- 通过 EndpointD 与命令端点系统通信 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| （无） | — | — | + +## 外部视角 + +WBP_Hint 是 UserWidget 的子类，从外部调用者视角： + +**公开属性（蓝图可读写）** +- `EndpointD`（EndpointDispatcher*）— 端点调度器引用，用于接收并显示来自命令系统的提示信息 + +**接口概览** +- 无自定义公开函数 +- EventGraph（3 事件, 3 节点）处理提示事件 +- 通过 EndpointD 与端点调度器对接 + +**外部交互方式** +- 由 BP_Hud 创建并持有（HintWindow 变量） +- 通过 EndpointD 接收指令系统的提示信息并显示 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件预构造` | 原生覆盖 (PreConstruct) | Widget 创建时 | 预留（当前无连线逻辑） | +| `事件构造` | 原生覆盖 (Construct) | Widget 创建完成后 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | + +## 使用方法 + +WBP_Hint 在项目中的使用方式： + +- **BP_Hud**（`/Game/Blueprints/BP_Hud`）— 存储在 HintWindow 变量中，作为游戏 HUD 的提示浮层 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_Hud | `/Game/Blueprints/BP_Hud` | 作为 HintWindow 子 Widget，显示提示信息 | diff --git a/Content/Blueprints/WBP_InventoryView.md b/Content/Blueprints/WBP_InventoryView.md index 41ff29f..5130cbf 100644 --- a/Content/Blueprints/WBP_InventoryView.md +++ b/Content/Blueprints/WBP_InventoryView.md @@ -1,10 +1,10 @@ # WBP_InventoryView ## 基本信息 -- **类型**: Widget Blueprint (UserWidget) +- **类型**: WidgetBlueprint (UserWidget) - **父类**: UserWidget - **源文件**: /Game/Blueprints/UI/Item/WBP_InventoryView.WBP_InventoryView -- **模块**: Content +- **模块**: Content/Blueprints/UI/Item ## 功能概述 WBP_InventoryView 是物品列表显示 Widget，持有 BP_InventoryComp 组件的引用，负责将库存中的物品视图列表渲染到 UI。通过 UpdateListItems 函数刷新列表显示，使用 WBP_ItemViewBox 作为单个物品视图框的子 Widget。 @@ -22,28 +22,45 @@ WBP_InventoryView 负责显示物品列表 UI、监听库存变化并自动刷 | FItemView | 显示数据 | Item 插件 | | WBP_ItemViewBox | 子 Widget | /Game/Blueprints/UI/Item/WBP_ItemViewBox | -## 对外接口 -- **蓝图函数**： - - `UpdateListItems()` -- 刷新物品列表显示，从 `Comp` (BP_InventoryComp) 的 ViewCache 读取 FItemView 数据并更新 UI 列表 -- **蓝图变量**（均为 is_instance_editable）： - - `Bo` (bool) -- 布尔标志位，用于控制 UI 显示/隐藏或其他状态 - - `Comp` (BP_InventoryComp_C*) -- 目标库存组件引用，指向要显示的 BP_InventoryComp 实例。UI 从此组件的 ViewCache 读取物品数据 -- **通过 Comp 变量访问的 BP_InventoryComp 接口**： - - `ViewCache` (TArray) -- 物品视图缓存，包含 ItemID、ItemType、ItemName、ItemDescription、Icon、ItemDataText - - `OnViewChanged` (动态多播委托) -- 绑定此委托实现库存变化时自动调用 UpdateListItems - - `CreateItemInternal` -- 可用于触发物品创建（通常不直接从此 Widget 调用） -- **EventGraph**：含 5 个事件和 8 个节点 +## 外部视角 + +WBP_InventoryView 是 UserWidget 的子类，从外部调用者视角： + +**公开属性（蓝图可读写）** +- `Comp`（BP_InventoryComp_C*）— 关联的库存组件引用 +- `Bo`（bool）— 内部状态标记 + +**自定义函数** +- `UpdateListItems()` — 从 Comp 的 ViewCache 刷新物品列表显示 + +**外部交互方式** +- 作为 BP_Hud 的子 Widget 创建，存放于 InvView 变量 +- 通过 Comp 变量引用 BP_InventoryComp，读取其 ViewCache 获取物品视图数据 +- 绑定 Comp 的 OnViewChanged 委托，在库存变化时自动调用 UpdateListItems +- 列表项使用 WBP_ItemViewBox 作为子 Widget 渲染单个物品 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件预构造` | 原生覆盖 (PreConstruct) | Widget 创建时 | 预留（当前无连线逻辑） | +| `事件构造` | 原生覆盖 (Construct) | Widget 创建完成后 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | +| `BindToComp` | 自定义事件 | 外部系统（如 BP_Hud/BP_Barrel）调用时 | 接收 BP_InventoryComp 引用 → 存入 Comp 变量 → 绑定 Comp 的 OnViewChanged 委托到 UpdateListItems_Event | +| `UpdateListItems_Event` | 自定义事件 | Comp 的 OnViewChanged 触发时 | 调用 UpdateListItems 刷新物品列表 UI | ## 使用方法 -- 作为 UMG UserWidget，被 BP_Hud 的 `InvView` 变量引用（类型为 WBP_InventoryView_C*） -- 设置 `Comp` 变量指向目标 Actor 上的 BP_InventoryComp 实例，建立 UI 到数据的绑定 -- 在 EventGraph 中绑定 `Comp.OnViewChanged` 委托，每次库存变化时自动调用 `UpdateListItems` 刷新列表 -- `UpdateListItems` 从 `Comp.ViewCache` 读取 FItemView 数组，遍历创建 WBP_ItemViewBox 子 Widget 填充列表 -- WBP_ItemViewBox 作为单个物品的视图框，显示物品图标、名称、描述等信息 -- `Bo` 布尔变量用于控制 ListView 的条件显示（如空库存时隐藏列表） -- 物品系统的数据流向：UDefaultContainer (存储) -> BP_InventoryComp (管理+ViewCache) -> WBP_InventoryView (显示) + +WBP_InventoryView 在项目中的典型调用流程： + +- **库存 UI 绑定流程** — BP_Hud/BARREL 创建 WBP_InventoryView → 调用 BindToComp → 传入 BP_InventoryComp 引用 → 绑定 OnViewChanged → 库存变化时自动触发 UpdateListItems_Event → UpdateListItems 从 ViewCache 刷新 UI +- **手动刷新流程** — 外部系统直接调用 UpdateListItems → 从 Comp.ViewCache 读取当前物品列表 → 遍历渲染 WBP_ItemViewBox 子 Widget ## 用例 -- BP_Hud 的 `InvView` 变量引用，作为物品栏 UI 界面 -- 通过 `Comp` 变量绑定 BP_InventoryComp，显示玩家或掉落物的物品列表 -- 使用 WBP_ItemViewBox 作为子 Widget 渲染单个物品视图 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_Hud | `/Game/Blueprints/BP_Hud` | 作为 InvView 子 Widget，显示物品栏 | +| BP_Barrel | `/Game/Blueprints/Playground/BP_Barrel` | 通过 HUD 访问，展示木桶库存 | +| BP_ItemViewDataView | `/Game/Blueprints/UI/Item/BP_ItemViewDataView` | 引用用于数据视图绑定 | +| WBP_ItemViewBox | `/Game/Blueprints/UI/Item/WBP_ItemViewBox` | 作为列表项模板引用 | diff --git a/Content/Blueprints/WBP_ItemViewBox.md b/Content/Blueprints/WBP_ItemViewBox.md new file mode 100644 index 0000000..c7d653f --- /dev/null +++ b/Content/Blueprints/WBP_ItemViewBox.md @@ -0,0 +1,60 @@ +# WBP_ItemViewBox + +## 基本信息 +- **类型**: WidgetBlueprint (UserWidget) +- **父类**: UserWidget +- **源文件**: /Game/Blueprints/UI/Item/WBP_ItemViewBox.WBP_ItemViewBox +- **模块**: Content/Blueprints/UI/Item + +## 功能概述 +物品视图盒子 Widget，用于在 UI 中展示单个物品的图标/外观。持有 ItemView（ItemView 类型）变量，GetBrush 函数返回 SlateBrush 用于渲染。4 个事件, 11 个节点。 + +## 设计用意 +物品 UI 系统中的单个物品展示组件，通过 BP_ItemViewDataView 获取数据，通过 WBP_InventoryView 与库存视图联动。 + +## 职责范围 +- 渲染单个物品的图标 +- 通过 GetBrush 提供当前物品的 SlateBrush + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| WBP_InventoryView | 引用 | /Game/Blueprints/UI/Item/WBP_InventoryView | +| BP_InventoryComp | 引用 | /Game/Blueprints/Playground/BP_InventoryComp | +| BP_ItemViewDataView | 引用 | /Game/Blueprints/UI/Item/BP_ItemViewDataView | + +## 外部视角 + +WBP_ItemViewBox 是 UserWidget 的子类，从外部调用者视角： + +**公开属性（蓝图可读写）** +- `ItemView`（FItemView 结构体）— 当前显示的物品视图数据 + +**自定义函数** +- `GetBrush()` → `FSlateBrush` — 返回当前物品的 SlateBrush，用于渲染物品图标 + +**外部交互方式** +- 由 WBP_InventoryView 创建，作为物品列表中的单个条目 +- 通过 BP_ItemViewDataView 获取物品数据 +- 通过 BP_InventoryComp 获取物品视图数据 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件预构造` | 原生覆盖 (PreConstruct) | Widget 创建时 | 预留（当前无连线逻辑） | +| `事件构造` | 原生覆盖 (Construct) | Widget 创建完成后 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | +| `事件列表项目对象集上` | 接口事件 (UserListEntry) | 列表项数据绑定时 | 接收 BP_ItemViewDataView 对象 → Cast → 读取 Index → 从 WBP_InventoryView 的 Comp 获取 ItemViews → GET 对应索引 → 设置 ItemView | + +## 使用方法 + +WBP_ItemViewBox 在项目中的典型调用流程： + +- **列表项渲染流程** — WBP_InventoryView.UpdateListItems → 创建 WBP_ItemViewBox 作为列表子项 → 触发 OnListItemObjectSet → 从 BP_ItemViewDataView 读取 Index → 从 InventoryComp.GetItemViews 获取对应索引的 FItemView → 存入 ItemView 变量 → GetBrush 返回 SlateBrush 渲染图标 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| WBP_InventoryView | `/Game/Blueprints/UI/Item/WBP_InventoryView` | 作为列表项模板，渲染单个物品图标 | diff --git a/Content/Blueprints/WBP_Module1.md b/Content/Blueprints/WBP_Module1.md new file mode 100644 index 0000000..6b9ac51 --- /dev/null +++ b/Content/Blueprints/WBP_Module1.md @@ -0,0 +1,53 @@ +# WBP_Module1 + +## 基本信息 +- **类型**: WidgetBlueprint (UserWidget) +- **父类**: UserWidget +- **源文件**: /Game/Blueprints/UI/WBP_Module1.WBP_Module1 +- **模块**: Content/Blueprints/UI + +## 功能概述 +模块 UI Widget，关联对话框系统中的 WBP_Circle。EventGraph 含 3 个事件和 3 个节点。无自定义变量，结构简单。 + +## 设计用意 +对话框 UI 的模块容器之一，用于承载和显示与 WBP_Circle 相关的对话框界面。 + +## 职责范围 +- 作为对话框系统的子 UI 模块，嵌入 WBP_Circle + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| WBP_Circle | 引用 | /Game/Blueprints/UI/Dialog/WBP_Circle | + +## 外部视角 + +WBP_Module1 是 UserWidget 的子类，从外部调用者视角： + +**接口概览** +- 无自定义变量或公开函数 +- EventGraph（3 事件, 3 节点）— 极简事件图 +- 内嵌 WBP_Circle 作为子 Widget + +**外部交互方式** +- 作为对话框系统的 UI 模块容器，承载 WBP_Circle +- 无公开 API，外部通过对话框系统间接使用 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件预构造` | 原生覆盖 (PreConstruct) | Widget 创建时 | 预留（当前无连线逻辑） | +| `事件构造` | 原生覆盖 (Construct) | Widget 创建完成后 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | + +## 使用方法 + +WBP_Module1 在项目中的使用方式： + +- 作为对话框 UI 的环形进度模块，嵌入 WBP_Circle 进度条显示 +- 项目内无其他蓝图直接引用（MCP 未发现引用者） + +## 用例 + +（项目内暂无其他蓝图直接引用） diff --git a/Content/Blueprints/WBP_Module2.md b/Content/Blueprints/WBP_Module2.md new file mode 100644 index 0000000..2efab81 --- /dev/null +++ b/Content/Blueprints/WBP_Module2.md @@ -0,0 +1,53 @@ +# WBP_Module2 + +## 基本信息 +- **类型**: WidgetBlueprint (UserWidget) +- **父类**: UserWidget +- **源文件**: /Game/Blueprints/UI/WBP_Module2.WBP_Module2 +- **模块**: Content/Blueprints/UI + +## 功能概述 +模块 UI Widget，关联对话框系统中的 WBP_Resources。EventGraph 含 3 个事件和 3 个节点。无自定义变量，结构简单。 + +## 设计用意 +对话框 UI 的模块容器之一，用于承载和显示与 WBP_Resources 相关的资源展示界面。 + +## 职责范围 +- 作为对话框系统的子 UI 模块，嵌入 WBP_Resources + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| WBP_Resources | 引用 | /Game/Blueprints/UI/Dialog/WBP_Resources | + +## 外部视角 + +WBP_Module2 是 UserWidget 的子类，从外部调用者视角： + +**接口概览** +- 无自定义变量或公开函数 +- EventGraph（3 事件, 3 节点）— 极简事件图 +- 内嵌 WBP_Resources 作为子 Widget + +**外部交互方式** +- 作为对话框系统的 UI 模块容器，承载 WBP_Resources 资源显示 +- 无公开 API，外部通过对话框系统间接使用 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件预构造` | 原生覆盖 (PreConstruct) | Widget 创建时 | 预留（当前无连线逻辑） | +| `事件构造` | 原生覆盖 (Construct) | Widget 创建完成后 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | + +## 使用方法 + +WBP_Module2 在项目中的使用方式： + +- 作为对话框 UI 的资源展示模块，嵌入 WBP_Resources 资金显示 +- 项目内无其他蓝图直接引用（MCP 未发现引用者） + +## 用例 + +（项目内暂无其他蓝图直接引用） diff --git a/Content/Blueprints/WBP_Resources.md b/Content/Blueprints/WBP_Resources.md new file mode 100644 index 0000000..cac567d --- /dev/null +++ b/Content/Blueprints/WBP_Resources.md @@ -0,0 +1,55 @@ +# WBP_Resources + +## 基本信息 +- **类型**: WidgetBlueprint (UserWidget) +- **父类**: UserWidget +- **源文件**: /Game/Blueprints/UI/Dialog/WBP_Resources.WBP_Resources +- **模块**: Content/Blueprints/UI/Dialog + +## 功能概述 +资源显示 Widget，用于在对话框界面中展示资金/资源信息。EventGraph 含 3 个事件和 3 个节点。无自定义变量。 + +## 设计用意 +对话框系统中的资源状态显示组件，展示玩家当前持有的资金等数值信息。 + +## 职责范围 +- 渲染资源/资金信息的 UI 显示 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| Vector | 引用(纹理) | /Game/Arts/UI/纹理/Vector | +| 资金底框 | 引用(纹理) | /Game/Arts/UI/纹理/资金底框 | + +## 外部视角 + +WBP_Resources 是 UserWidget 的子类，从外部调用者视角： + +**接口概览** +- 无自定义变量或公开函数 +- EventGraph（3 事件, 3 节点）— 极简事件图 +- 引用 Arts 纹理（Vector、资金底框）用于 UI 渲染 + +**外部交互方式** +- 由 WBP_Module2 创建并嵌入 +- 无公开 API，作为纯展示组件存在 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件预构造` | 原生覆盖 (PreConstruct) | Widget 创建时 | 预留（当前无连线逻辑） | +| `事件构造` | 原生覆盖 (Construct) | Widget 创建完成后 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | + +## 使用方法 + +WBP_Resources 在项目中的使用方式： + +- **WBP_Module2**（`/Game/Blueprints/UI/WBP_Module2`）— 嵌入作为对话框资源/资金显示组件 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| WBP_Module2 | `/Game/Blueprints/UI/WBP_Module2` | 嵌入作为资源展示子 Widget | diff --git a/Content/Blueprints/WBP_TestUI.md b/Content/Blueprints/WBP_TestUI.md index e694a7b..d020284 100644 --- a/Content/Blueprints/WBP_TestUI.md +++ b/Content/Blueprints/WBP_TestUI.md @@ -1,10 +1,10 @@ # WBP_TestUI ## 基本信息 -- **类型**: Widget Blueprint (UserWidget) +- **类型**: WidgetBlueprint (UserWidget) - **父类**: UserWidget - **源文件**: /Game/Blueprints/UI/Dialog/WBP_TestUI.WBP_TestUI -- **模块**: Content +- **模块**: Content/Blueprints/UI/Dialog ## 功能概述 WBP_TestUI 是对话演示脚本的显示/执行 Widget，实现了 IPresentationScriptExecutor 接口。它接收 FDialogPresentationScriptData，解析其中的 JSON 命令，构建 UI 选择按钮，驱动演示脚本的执行流。同时持有 Ultra Dynamic Sky 引用以支持环境变化命令。 @@ -23,35 +23,49 @@ WBP_TestUI 负责演示脚本的接收和执行、对话 UI 的生成和更新 | IPresentationScriptExecutor | 实现接口 | Dialog 插件 | | UDialogPresentationSubsystem | 调用 | Dialog 插件 | -## 对外接口 -- **蓝图函数**： - - `ExecuteScript(FDialogPresentationScriptData InScript)` -- 启动演示脚本，接收脚本数据并开始执行流程 - - `ProcessScript(FDialogPresentationScriptCommand Presentation)` -- 处理单条脚本命令，逐条执行演示命令 - - `ExecuteNextScript(FName Name)` -- 跳转到指定名称的下一个脚本，实现脚本流程控制 - - `SummonChoiceButtons(FDialogPresentationScriptData Data)` -- 根据脚本数据中的 Choices 字段动态生成选择按钮 UI - - `SetNextScritp(FDialogPresentationScriptData Data)` -- 设置下一个要执行的脚本（通过 NextScriptName 变量） - - `Get_MainText_Text() -> FText` -- 数据绑定函数，返回主文本框的对话文本内容 -- **蓝图变量**（均为 is_instance_editable）： - - `NextScriptName` (FName) -- 存储下一个脚本的名称，用于流程跳转 - - `Sky` (Ultra_Dynamic_Sky_C*) -- Ultra Dynamic Sky 引用，用于执行环境变化命令（如改变天气、时间） -- **IPresentationScriptExecutor 接口实现**（BlueprintNativeEvent）： - - `ExecutePresentationScript(const FDialogPresentationScriptData& ScriptStruct)` -- 执行演示脚本 - - `PlugStrategyIn(FName StrategyName, const TScriptInterface& NewStrategy)` -- 插件式注入策略 - - `UnplugStrategy(FName StrategyName)` -- 移除策略插件 -- **EventGraph**：含 5 个事件和 8 个节点 +## 外部视角 + +WBP_TestUI 是 UserWidget 的子类，实现 IPresentationScriptExecutor 接口，从外部调用者视角： + +**公开属性（蓝图可读写）** +- `NextScriptName`（FName）— 下一条要执行的脚本名称 +- `Sky`（Ultra_Dynamic_Sky_C*）— 超动态天空引用，用于环境变化命令 + +**实现接口（IPresentationScriptExecutor）** +- `ExecuteScript(FDialogPresentationScriptData InScript)` — 启动一条演示脚本 +- `ProcessScript(FDialogPresentationScriptCommand Presentation)` — 逐条解析并执行脚本命令 +- `ExecuteNextScript(FName Name)` — 跳转到指定名称的脚本段 + +**UI 管理函数** +- `SummonChoiceButtons(FDialogPresentationScriptData Data)` — 动态生成对话选项按钮（WBP_ChoiceButton） +- `SetNextScritp(FDialogPresentationScriptData Data)` — 设置下一条脚本的目标 +- `Get_MainText_Text()` → `FText` — 绑定主文本显示 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件预构造` | 原生覆盖 (PreConstruct) | Widget 在蓝图编辑器中放置或运行时创建时 | 预留（当前无连线逻辑） | +| `事件构造` | 原生覆盖 (Construct) | Widget 创建完成后 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 预留（当前无连线逻辑） | +| `事件ExecutePresentationScript` | 接口事件 (IPresentationScriptExecutor) | UDialogPresentationSubsystem 调用时 | 接收 FDialogPresentationScriptData → 调用 ExecuteScript 启动脚本执行 | +| `On Clicked (Next)` | 组件绑定事件 | 用户点击"下一步"按钮时 | 读取 NextScriptName → 调用 ExecuteNextScript 跳转脚本 | + +**外部交互方式** +- 由 UDialogPresentationSubsystem 创建并调用 ExecuteScript +- 通过 IPresentationScriptExecutor 接口与 Dialog 插件通信 +- 通过 WBP_ChoiceButton 动态生成选项按钮 ## 使用方法 -- 作为 UserWidget 创建并添加到视口，通常由 UDialogPresentationSubsystem 管理 -- 实现 IPresentationScriptExecutor 接口，作为 Dialog 插件的脚本执行器 -- UDialogPresentationSubsystem 调用 `ExecutePresentationScript` 投递脚本，本 Widget 通过 `ExecuteScript` 启动执行 -- `ProcessScript` 逐条解析脚本命令：通过 UPresentationJsonLibrary 解析 JSON 命令字符串，识别 CommandName 和 Params -- `SummonChoiceButtons` 根据 Choices 数据动态创建选项按钮列表，按钮绑定 `ExecuteNextScript` 处理选择 -- `SetNextScritp` / `ExecuteNextScript` 控制脚本流程的线性或分支推进 -- `Get_MainText_Text` 作为 UMG 数据绑定函数，连接 UI 文本框显示对话内容 -- `Sky` 变量用于连接到场景中的 Ultra Dynamic Sky Actor，脚本命令可改变天气/时间等环境效果 -- 策略插件通过 `PlugStrategyIn` / `UnplugStrategy` 动态注入，支持在运行时扩展脚本命令的处理策略 + +WBP_TestUI 在项目中的典型调用流程： + +- **对话脚本执行流程** — UDialogPresentationSubsystem 加载 DataTable → 收到对话触发信号 → 调用 ExecuteScript（通过接口事件 `ExecutePresentationScript`）→ WBP_TestUI 的 ProcessScript 逐条解析 JSON 命令 → 更新 MainText 显示文本 +- **选项分支流程** — ProcessScript 遇到选项命令 → 调用 SummonChoiceButtons → 动态生成 WBP_ChoiceButton 并挂接到面板 → 用户选择一个选项 → 更新 NextScriptName +- **下一步跳转流程** — 用户点击"下一步"按钮 → 触发 `On Clicked (Next)` → 读取 NextScriptName → 调用 ExecuteNextScript → 跳转到 FDialogPresentationScriptData 中对应名称的脚本段 ## 用例 -- Dialog 系统的 UI 执行器，实现 IPresentationScriptExecutor 接口 -- 由 UDialogPresentationSubsystem 调用，作为对话脚本的显示和交互界面 -- 通过 `Sky` 变量连接 Ultra Dynamic Sky，支持演示脚本中的环境效果命令 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| DialogTest | `/Game/地图关卡/DialogTest` | 在该关卡中执行对话演示脚本 | diff --git a/Content/Blueprints/WBP_Window.md b/Content/Blueprints/WBP_Window.md new file mode 100644 index 0000000..bee6c98 --- /dev/null +++ b/Content/Blueprints/WBP_Window.md @@ -0,0 +1,66 @@ +# WBP_Window + +## 基本信息 +- **类型**: WidgetBlueprint (UserWidget) +- **父类**: UserWidget +- **源文件**: /Game/Blueprints/UI/WBP_Window.WBP_Window +- **模块**: Content/Blueprints/UI + +## 功能概述 +可拖拽窗口 Widget，实现了一个具有标题栏的基本窗口 UI。支持鼠标拖拽移动（通过 On_Title_Bar_MouseButtonDown/Up 和 UpdatePosition 函数），持有 IsDragging（bool）、DragStartPoint（Vector2D）、WidgetStartPoint（Vector2D）、IsTemp（bool）四个变量管理拖拽状态。 + +## 设计用意 +提供一个可复用的通用窗口 UI 组件，支持标题栏拖拽移动。作为游戏内各类面板的基础容器，被 BP_Hud、BP_Barrel 等持有使用。 + +## 职责范围 +- 渲染窗口标题栏和内容区域 +- 管理窗口的拖拽移动逻辑 +- 标识是否为临时窗口（IsTemp） + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| （无） | — | — | + +## 外部视角 + +WBP_Window 是 UserWidget 的子类，从外部调用者视角： + +**公开属性（蓝图可读写）** +- `IsDragging`（bool）— 当前是否在拖拽状态 +- `DragStartPoint`（Vector2D）— 拖拽起始鼠标位置 +- `WidgetStartPoint`（Vector2D）— 拖拽起始 Widget 位置 +- `IsTemp`（bool）— 是否为临时窗口 + +**公开函数** +- `On_Title_Bar_MouseButtonDown(Geometry, PointerEvent)` → `FEventReply` — 标题栏按下，启动拖拽 +- `On_Title_Bar_MouseButtonUp(Geometry, PointerEvent)` → `FEventReply` — 标题栏释放，结束拖拽 +- `UpdatePosition()` — 根据拖拽偏移更新 Widget 位置 + +**外部交互方式** +- 由 BP_Hud 或 BP_Barrel 创建并持有，作为通用窗口容器 +- 外部系统通过 Widget 引用设置内容或控制显示/隐藏 + +**EventGraph 事件** + +| 事件 | 类型 | 触发时机 | 行为 | +|------|------|----------|------| +| `事件预构造` | 原生覆盖 (PreConstruct) | Widget 在编辑器中放置或运行时创建时 | 预留（当前无连线逻辑） | +| `事件构造` | 原生覆盖 (Construct) | Widget 创建完成后 | 预留（当前无连线逻辑） | +| `事件Tick` | 原生覆盖 | 每帧 | 如果 IsDragging=true → 调用 UpdatePosition 更新窗口位置 | +| `On Clicked (Button_61)` | 组件绑定事件 | 用户点击关闭按钮时 | 如果 IsTemp=true → 从父项中移除（销毁临时窗口），否则 → 设置可视性为 Hidden（隐藏持久窗口） | + +## 使用方法 + +WBP_Window 在项目中的典型调用流程： + +- **窗口拖拽流程** — 用户按住标题栏 → On_Title_Bar_MouseButtonDown 记录拖拽起始位置 → Tick 检测 IsDragging → UpdatePosition 根据鼠标偏移移动 Widget → 释放 → On_Title_Bar_MouseButtonUp 结束拖拽 +- **临时窗口关闭流程** — 用户点击关闭按钮 → On Clicked (Button_61) → 判断 IsTemp → 临时窗口直接从父项移除，持久窗口仅隐藏 +- **HUD 窗口创建流程** — BP_Hud.BeginPlay → 创建 WBP_Window（InventoryWindow/HintWindow）→ 添加到视口 → 外部通过 BP_Hud 变量访问 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_Hud | `/Game/Blueprints/BP_Hud` | 作为 InventoryWindow/HintWindow 窗口容器 | +| BP_Barrel | `/Game/Blueprints/Playground/BP_Barrel` | 作为 BarrelWindow 木桶交互窗口 | diff --git a/Content/Blueprints/_relationships.md b/Content/Blueprints/_relationships.md index 16ea43e..854800d 100644 --- a/Content/Blueprints/_relationships.md +++ b/Content/Blueprints/_relationships.md @@ -28,6 +28,20 @@ | BP_TestMode | DefaultPawnClass | BP_TestChar | Content/Blueprints | | BP_TestMode | PlayerControllerClass | BP_TestCtl | Content/Blueprints | | BP_TestMode | HUDClass | BP_Hud | Content/Blueprints | +| **BP_NewChar** | 引用(动画) | **ABP_TestChar** | Content/Blueprints | +| **BP_Barrel** | 引用 | **WBP_InventoryView** | Content/Blueprints | +| **BP_Barrel** | 包含(变量) | **WBP_Window** | Content/Blueprints | +| **BP_ItemTrap** | 引用 | **BP_NewChar** | Content/Blueprints | +| **BP_TestItemCluster** | 引用(子物品) | **BP_TestItem** | Content/Blueprints | +| **BP_ItemViewDataView** | 包含(变量) | **WBP_InventoryView** | Content/Blueprints | +| **WBP_Module1** | 引用 | **WBP_Circle** | Content/Blueprints | +| **WBP_Module2** | 引用 | **WBP_Resources** | Content/Blueprints | +| **WBP_ItemViewBox** | 引用 | **WBP_InventoryView** | Content/Blueprints | +| **WBP_ItemViewBox** | 引用 | **BP_ItemViewDataView** | Content/Blueprints | + +**新增（10 条）：** 加粗标记的行为阶段 1 新增的 17 个文档中提取的模块内引用关系。 +**无依赖：** BP_Trap、WBP_Hint、WBP_Window、WBP_ChoiceButton 不引用模块内其他资产。 +**Arts 引用：** WBP_Circle、WBP_Resources、ABP_TestChar 引用了 /Game/Arts/ 下的纹理/材质/骨骼资源，不属于 Content/Blueprints 模块。 ## 关键依赖链 @@ -41,4 +55,15 @@ Item Pipeline: BP_DefaultContainer (UDefaultContainer) ← BP_InventoryComp (IIn UI Pipeline: WBP_TestUI (implements IPresentationScriptExecutor) → UDialogPresentationSubsystem -Item UI: WBP_InventoryView → BP_InventoryComp (via ViewCache/OnViewChanged) → BP_DefaultContainer (IItemContainer) +Item UI: +- WBP_InventoryView → BP_InventoryComp (via ViewCache/OnViewChanged) → BP_DefaultContainer (IItemContainer) +- WBP_ItemViewBox → BP_ItemViewDataView → WBP_InventoryView + +Test/Playground Flow: +- BP_ItemTrap → BP_NewChar (target) → BP_InventoryComp / BP_DefaultContainer (item injection) +- BP_TestItemCluster → BP_TestItem (child items) +- BP_Barrel → BP_Hud + BP_TestCtl → WBP_Window (barrel UI) → WBP_InventoryView (inventory display) + +Dialog UI Modules: +- WBP_Module1 → WBP_Circle (progress ring) +- WBP_Module2 → WBP_Resources (resource display) diff --git a/Content/Data/DA_InputCommands.md b/Content/Data/DA_InputCommands.md new file mode 100644 index 0000000..413717a --- /dev/null +++ b/Content/Data/DA_InputCommands.md @@ -0,0 +1,55 @@ +# DA_InputCommands + +## 基本信息 +- **类型**: InputCommandData +- **父类**: — +- **源文件**: /Game/Data/DA_InputCommands.DA_InputCommands +- **模块**: Content/Data + +## 功能概述 +输入命令数据资产，集中定义项目中的输入动作和映射上下文。引用了 8 个 InputAction（IA_CameraMoveAction、IA_CameraResetAction、IA_CameraRotateAction、IA_CameraZoomAction、IA_MoveAction、IA_SayHello、IA_Hint、IA_Inventory）和 1 个 InputMappingContext（IMC_Context）。 + +## 设计用意 +将输入命令的定义集中到一个数据资产中，作为输入系统的配置中心，方便管理和调整按键映射关系。 + +## 职责范围 +- 集中管理和暴露项目中的输入动作（InputAction） +- 关联输入映射上下文（InputMappingContext） + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| IA_CameraMoveAction | 引用 | /Game/Inputs/IA/IA_CameraMoveAction | +| IA_CameraResetAction | 引用 | /Game/Inputs/IA/IA_CameraResetAction | +| IA_CameraRotateAction | 引用 | /Game/Inputs/IA/IA_CameraRotateAction | +| IA_CameraZoomAction | 引用 | /Game/Inputs/IA/IA_CameraZoomAction | +| IA_MoveAction | 引用 | /Game/Inputs/IA/IA_MoveAction | +| IMC_Context | 引用 | /Game/Inputs/IMC/IMC_Context | +| IA_SayHello | 引用 | /Game/Inputs/IA/IA_SayHello | +| IA_Hint | 引用 | /Game/Inputs/IA/IA_Hint | +| IA_Inventory | 引用 | /Game/Inputs/IA/IA_Inventory | + +## 外部视角 + +DA_InputCommands 是 InputCommandData 数据资产，从外部调用者视角： + +**公开数据** +- 持有 8 个 InputAction 的引用：IA_MoveAction、IA_CameraMoveAction、IA_CameraZoomAction、IA_CameraRotateAction、IA_CameraResetAction、IA_SayHello、IA_Hint、IA_Inventory +- 持有 1 个 InputMappingContext 引用：IMC_Context + +**外部交互方式** +- 由 BP_TestCtl 在初始化时加载，作为输入命令定义的配置中心 +- 外部系统通过数据资产引用读取其中的 InputAction 和 IMC，用于增强输入绑定 +- 不提供函数调用接口，所有交互通过读取数据实现 + +## 使用方法 + +DA_InputCommands 在项目中的使用方式： + +- **BP_TestCtl**（`/Game/Blueprints/BP_TestCtl`）— 加载该数据资产，从中获取 InputAction 和 IMC_Context 配置输入系统 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| BP_TestCtl | `/Game/Blueprints/BP_TestCtl` | 加载输入命令配置，初始化增强输入绑定 | diff --git a/Content/Data/NewGraph.md b/Content/Data/NewGraph.md new file mode 100644 index 0000000..e32da3f --- /dev/null +++ b/Content/Data/NewGraph.md @@ -0,0 +1,46 @@ +# NewGraph + +## 基本信息 +- **类型**: DialogGraphDataAsset +- **父类**: — +- **源文件**: /Game/Data/NewGraph.NewGraph +- **模块**: Content/Data + +## 功能概述 +对话图数据资产，存储一个对话分支图的定义。作为 Dialog 系统的数据结构，用于定义对话节点的拓扑结构和连接关系。 + +## 设计用意 +Dialog 插件的核心数据资产之一，用于编辑和存储对话流程图，驱动对话系统的分支逻辑。 + +## 职责范围 +- 存储对话图的节点和连接数据 +- 供 Dialog 系统运行时加载和解析 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| （无） | — | — | + +## 外部视角 + +NewGraph 是 DialogGraphDataAsset 数据资产，从外部调用者视角： + +**公开数据** +- 存储对话图的节点和连接拓扑数据 +- 结构由 Dialog 插件的 DialogGraphDataAsset 类型定义 + +**外部交互方式** +- Dialog 系统的 UDialogPresentationSubsystem 在运行时加载并解析 +- 不提供函数调用接口，通过数据资产引用读取图结构 +- 当前项目内无其他资产直接引用（MCP 未发现引用者），可能在运行时通过路径加载 + +## 使用方法 + +NewGraph 在项目中的使用方式： + +- 由 Dialog 插件的数据层加载，作为对话分支图的数据源 +- 项目内暂无其他蓝图或 C++ 直接引用该资产 + +## 用例 + +（项目内暂无直接使用示例） diff --git a/Content/Data/TestDialog.md b/Content/Data/TestDialog.md new file mode 100644 index 0000000..0916767 --- /dev/null +++ b/Content/Data/TestDialog.md @@ -0,0 +1,47 @@ +# TestDialog + +## 基本信息 +- **类型**: DataTable +- **父类**: — +- **源文件**: /Game/Data/TestDialog.TestDialog +- **模块**: Content/Data + +## 功能概述 +测试对话数据表，用于存储对话框系统的测试数据。结构未知，作为 Dialog 系统的数据输入。 + +## 设计用意 +Dialog 系统的测试数据，用于验证对话数据的加载和解析流程。 + +## 职责范围 +- 存储测试用对话条目数据 +- 供 Dialog 系统读取和解析 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| （无） | — | — | + +## 外部视角 + +TestDialog 是 DataTable 数据资产，从外部调用者视角： + +**公开数据** +- 包含测试用对话条目数据行 +- 行结构由 Dialog 插件定义的 DataTable 类型决定 + +**外部交互方式** +- DialogTest 关卡中引用该数据表，由 Dialog 系统加载并解析 +- 外部通过 DataTable 引用读取数据行 +- 不提供函数调用接口 + +## 使用方法 + +TestDialog 在项目中的使用方式： + +- **DialogTest 关卡**（`/Game/地图关卡/DialogTest`）— 引用该 DataTable，作为对话数据的来源 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| DialogTest | `/Game/地图关卡/DialogTest` | 加载对话测试数据，驱动对话演示 | diff --git a/Content/Data/TestDialogMap.md b/Content/Data/TestDialogMap.md new file mode 100644 index 0000000..37ee14d --- /dev/null +++ b/Content/Data/TestDialogMap.md @@ -0,0 +1,47 @@ +# TestDialogMap + +## 基本信息 +- **类型**: DataTable +- **父类**: — +- **源文件**: /Game/Data/TestDialogMap.TestDialogMap +- **模块**: Content/Data + +## 功能概述 +测试对话映射表，用于存储对话 ID 与对话数据的映射关系。作为 Dialog 系统的查询表。 + +## 设计用意 +Dialog 系统的测试数据，用于验证对话映射查询功能。 + +## 职责范围 +- 存储对话 ID 到对话数据的映射关系 +- 供 Dialog 系统按 ID 查询对话数据 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| （无） | — | — | + +## 外部视角 + +TestDialogMap 是 DataTable 数据资产，从外部调用者视角： + +**公开数据** +- 包含对话 ID 到对话数据的映射关系 +- 行结构由 Dialog 插件定义的 DataTable 类型决定 + +**外部交互方式** +- DialogTest 关卡中引用该数据表，由 Dialog 系统按 ID 查询对话数据 +- 外部通过 DataTable 引用读取映射关系 +- 不提供函数调用接口 + +## 使用方法 + +TestDialogMap 在项目中的使用方式： + +- **DialogTest 关卡**（`/Game/地图关卡/DialogTest`）— 引用该 DataTable，作为对话映射查询的数据源 + +## 用例 + +| 引用方 | 路径 | 用途 | +|--------|------|------| +| DialogTest | `/Game/地图关卡/DialogTest` | 加载对话映射数据，支持按 ID 查询对话 | diff --git a/Content/Data/TestItemDefTable.md b/Content/Data/TestItemDefTable.md new file mode 100644 index 0000000..fec7abf --- /dev/null +++ b/Content/Data/TestItemDefTable.md @@ -0,0 +1,46 @@ +# TestItemDefTable + +## 基本信息 +- **类型**: DataTable +- **父类**: — +- **源文件**: /Game/Data/Item/TestItemDefTable.TestItemDefTable +- **模块**: Content/Data/Item + +## 功能概述 +测试物品定义表，用于存储物品定义的测试数据。作为物品系统的配置数据输入。 + +## 设计用意 +物品系统的测试数据表，用于验证物品定义（ItemDef）的加载和解析流程。 + +## 职责范围 +- 存储测试用物品定义数据行 +- 供物品系统读取和解析物品定义 + +## 项目内依赖 +| 依赖项 | 关系 | 源文件 | +|--------|------|--------| +| （无） | — | — | + +## 外部视角 + +TestItemDefTable 是 DataTable 数据资产，从外部调用者视角： + +**公开数据** +- 包含测试用物品定义（ItemDef）数据行 +- 行结构由 Item 插件定义的 DataTable 类型决定 + +**外部交互方式** +- Item 插件的 UItemRegistrySubsystem 在运行时加载，注册物品定义 +- BP_InventoryComp 等组件通过物品注册表间接引用其中的物品定义 +- 当前项目内无其他资产直接引用（MCP 未发现引用者），通过运行时路径加载 + +## 使用方法 + +TestItemDefTable 在项目中的使用方式： + +- 由物品系统的 UItemRegistrySubsystem 加载，作为物品定义的测试数据源 +- BP_InventoryComp 在其 BeginPlay 逻辑中通过物品注册表读取物品定义 + +## 用例 + +（项目内暂无直接使用示例 — 可能通过运行时路径动态加载） diff --git a/Content/Data/_relationships.md b/Content/Data/_relationships.md new file mode 100644 index 0000000..eb90289 --- /dev/null +++ b/Content/Data/_relationships.md @@ -0,0 +1,37 @@ +# Content/Data 依赖关系 + +## 文件间引用关系 + +Content/Data 模块包含 5 个数据资产，均为独立的数据定义/配置，**模块内无文件间引用**。 + +| 源文件 | 引用方式 | 目标文件 | 目标单位 | +|--------|---------|---------|---------| +| DA_InputCommands | 引用 | /Game/Inputs/IA/IA_CameraMoveAction | IA_CameraMoveAction | +| DA_InputCommands | 引用 | /Game/Inputs/IA/IA_CameraResetAction | IA_CameraResetAction | +| DA_InputCommands | 引用 | /Game/Inputs/IA/IA_CameraRotateAction | IA_CameraRotateAction | +| DA_InputCommands | 引用 | /Game/Inputs/IA/IA_CameraZoomAction | IA_CameraZoomAction | +| DA_InputCommands | 引用 | /Game/Inputs/IA/IA_MoveAction | IA_MoveAction | +| DA_InputCommands | 引用 | /Game/Inputs/IA/IA_SayHello | IA_SayHello | +| DA_InputCommands | 引用 | /Game/Inputs/IA/IA_Hint | IA_Hint | +| DA_InputCommands | 引用 | /Game/Inputs/IA/IA_Inventory | IA_Inventory | +| DA_InputCommands | 引用 | /Game/Inputs/IMC/IMC_Context | IMC_Context | + +**说明：** DA_InputCommands 的所有引用均指向 /Game/Inputs/ 下的输入资产，属于跨模块引用。其余 4 个数据资产（NewGraph、TestDialog、TestDialogMap、TestItemDefTable）不引用模块内或其他模块的资产，它们是纯粹的数据文件。 + +## 关键依赖链 + +**模块结构：** +``` +Content/Data/ +├── DA_InputCommands — 输入命令配置（引用 InputAction / IMC） +├── NewGraph — 对话图数据（Dialog 系统数据源） +├── TestDialog — 对话测试数据表 +├── TestDialogMap — 对话映射数据表 +└── TestItemDefTable — 物品定义测试数据表（Content/Data/Item 子模块） +``` + +**输入配置流：** DA_InputCommands → UEnhancedInputLocalPlayerSubsystem → BP_TestCtl 消费 + +**对话数据流：** NewGraph / TestDialog / TestDialogMap → UDialogPresentationSubsystem → WBP_TestUI 展示 + +**物品数据流：** TestItemDefTable → UItemRegistrySubsystem → BP_InventoryComp 加载物品定义 diff --git a/HOWTO_REGENERATE_DOCS.md b/HOWTO_REGENERATE_DOCS.md deleted file mode 100644 index 53ca9c2..0000000 --- a/HOWTO_REGENERATE_DOCS.md +++ /dev/null @@ -1,415 +0,0 @@ -# 文档生成操作手册 - -## 这篇文章是干什么的 - -当你需要更新这个项目的文档，或者想把同一套方法套到另一个 UE 项目时，看这个就够了。 - -本文记录： -1. **踩过的坑** — 初版被骂的 10 项问题，别再犯 -2. **正确的文档模板** — 每个单位应该长什么样 -3. **完整操作步骤** — 从零到 56 个文档是怎么生成的 -4. **工具和命令** — 用了什么、怎么用 - ---- - -## 一、血泪教训：初版的 10 项问题 - -第一次跑完「项目文档化计划」后，被用户逐条指出以下问题，全部在修订版中修正： - -| # | 问题 | 初版做法 | 正确做法 | -|---|------|---------|---------| -| 1 | 多个单位合并到一个文件 | `ItemDataStructures.md` 里塞了 3 个 struct | 每个结构体/类/接口/枚举独立一个 .md | -| 2 | "设计用意"和"职责范围"合并 | 一个 `## 设计用意与职责范围` 章节糊在一起 | 拆成两个独立章节 | -| 3 | "职责范围"用二分法 | 写"职责：xxx / 不负责：yyy" | 自然语言描述工作范围 | -| 4 | 多余的模块 | 文档里出现"变量"、"关键成员"表格 | 不写实现细节，对外接口从调用者视角描述 | -| 5 | 使用方法不引用真代码 | 写"可以这样用"但没有出处 | 每条引用真实文件路径和行号 | -| 6 | 用例编造示例代码 | 写伪代码 `// 继承 AMyActor...` | 只列出项目中实际使用该单位的文件 | -| 7 | `_relationships.md` 太花哨 | ASCII 艺术图、设计模式分析 | 简单的文件级依赖表格 + 文本箭头 | -| 8 | 执行顺序混乱 | 边写接口边写依赖 | 严格：孤立文档 → 关系文档 → 接口+用例 | -| 9 | README.md 没更新 | 还是旧的待办列表 | 更新为完整的文档索引 | -| 10 | "项目内依赖"列名不对 | 用了"说明"列 | 改为"源文件"列，放文件路径 | - -### 为什么这些问题很重要 - -- **合并文件**：后人要找 `FItemView` 的文档时，不能一眼看到文件名，还得打开文件在里面搜。单位名和文件名一一对应，是文档可发现性的底线。 -- **设计用意 vs 职责范围**：前者回答"为什么存在"，后者回答"管什么事"。混在一起会让维护者搞不清这个类的边界。 -- **真实代码引用**：没有行号的使用说明是废纸。半年后代码改了，维护者无法验证文档是否过期。 - ---- - -## 二、正确的文档模板 - -### 2.1 孤立单位文档模板 - -每个单位（class/struct/enum/BP）一个 .md 文件，**严格**以下结构： - -```markdown -# [单位名称] - -## 基本信息 -- **类型**: UCLASS / USTRUCT / UENUM / C++ class / Blueprint -- **父类**: XXX（没有就写 —） -- **源文件**: path/to/file.h（蓝图写 /Game/ 路径） -- **模块**: ModuleName - -## 功能概述 -[一段话概括这个单位做什么，什么场景用] - -## 设计用意 -[为什么这样设计，解决什么问题，在系统中的定位] - -## 职责范围 -[自然语言描述该单位承担的工作范围，它负责什么流程/数据/决策。 - 禁止使用"职责"/"不负责"二分格式] - -## 项目内依赖 -| 依赖项 | 关系 | 源文件 | -|--------|------|--------| -| XXX | 包含/引用/继承/调用 | path/to/file.h:行号 | - -## 对外接口 -[从外部调用者的角度描述： - - C++ 调用者：哪些 public 方法/虚函数可调用 - - 蓝图调用者：哪些 UFUNCTION/BlueprintNativeEvent 可调用 - - 委托：哪些委托可绑定 - - 结构体：哪些 UPROPERTY 字段对外可读写 - 禁止单纯罗列函数签名] - -## 使用方法 -[引用项目中的真实代码位置说明如何使用本单位的典型流程。 - 每条使用方式必须给出源文件和行号出处] - -## 用例 -[列举项目中实际使用本单位的文件和上下文。不编造示例。 - 格式：文件路径:行号 — 用途说明] -``` - -### 2.2 关系文档模板 (`_relationships.md`) - -每个模块目录下一个： - -```markdown -# [模块名] 依赖关系 - -## 文件间引用关系 - -| 源文件 | 引用方式 | 目标文件 | 目标单位 | -|--------|---------|---------|---------| -| XXX.h | #include | YYY.h | YYY | -| XXX.h | forward-declare | — | ZZZ | - -## 关键依赖链 -[用简单的文本箭头描述关键数据/控制流，如： -DefaultContainer.cpp → ItemFactory::CreateItemInstance → FItemInstance -] -``` - -### 2.3 README.md 模板 - -见 `Document/README.md`，核心是每个模块的完整单位列表表，含：单位名、文件名（链接）、类型、父类。 - ---- - -## 三、完整操作步骤 - -以下是在一个全新的 UE 项目上复现整个过程的操作步骤。 - -### 前置条件 - -1. **Claude Code CLI**（本文使用的 AI 编程助手） - - 安装方式见 [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code) - - 关键是它支持 Task 工具（可以启动后台子代理并行干活） - - 支持 MCP（用于查询 UE 编辑器中的蓝图信息） -2. **UnrealClaude MCP 插件** — 安装在项目的 `Plugins/UnrealClaude/` 下 - - 提供 `unreal_blueprint_query`、`unreal_asset_search` 等 MCP 工具 - - 用来查询蓝图资产信息（因为在 .uasset 二进制文件上没法直接 grep） -3. **ripgrep** (`rg`) — 用于在源代码中搜索单位引用 -4. **bash shell** — Windows 上用 Git Bash 或 WSL，macOS/Linux 直接用 - -### 步骤 1：确定文档化范围 - -先画出要文档化的所有单位清单： - -```bash -# 列出所有需要文档化的 C++ 头文件 -find Source/ -name "*.h" | grep -v Intermediate | grep -v Generated -find Plugins/ -name "*.h" -path "*/Public/*" | grep -v Intermediate | grep -v Generated - -# 列出所有需要文档化的蓝图（通过 MCP） -# 在 Claude Code 对话中使用： -# mcp__unrealclaude__unreal_blueprint_query operation=list path_filter=/Game/Blueprints/ -``` - -对每个头文件，手动列出它包含的所有单位（一个 .h 可能包含多个 class/struct/enum）。这就是你的文档化清单。 - -### 步骤 2：分析所有源文件 - -这是最耗时但最关键的一步。你需要从每个源文件中提取： -- 单位的类型、父类、所属模块 -- 功能概述（从注释和代码推断） -- 设计意图（为什么存在） -- `#include` 依赖关系 -- 前向声明 -- public 方法、UFUNCTION、delegate - -**用 Claude Code 的做法**（推荐）： - -启动多个 `Task` 子代理并行分析： - -``` -对 Claude Code 说： -"用 Explore 子代理分析 D:\workspace\u\lonese\Plugins\Item\ 目录下所有 .h 和 .cpp 文件， -对每个 class/struct/enum 提取：类型、父类、功能、设计意图、依赖、公开方法。" -``` - -关键提示词要点： -- 让代理先 `Glob` 找到所有 .h 文件，再逐文件 `Read` -- 要求结构化输出（每个单位一个条目） -- 明确列出需要的字段：类型/父类/文件路径/模块/功能/设计意图/include依赖/前向声明/公开方法/UFUNCTION/delegate/BlueprintNativeEvent - -**手动做法**（如果没有 AI 工具）： - -``` -对每个 .h 文件： -1. 记录文件中定义的所有 UCLASS/USTRUCT/UENUM/接口 -2. 记录每个单位的父类和包含的引擎头文件 -3. 搜索 #include "项目内头文件" 记录依赖 -4. 搜索 forward declaration -5. 记录 UPROPERTY 和 UFUNCTION 标记 -6. 从类/方法注释中提取功能描述 -``` - -结果应该整理成一张大表，每个单位一行，包含上述所有字段。 - -### 步骤 3：阶段 1 — 生成孤立单位文档 - -对每个单位创建一个 .md 文件，这个阶段**只填**： -- 基本信息 -- 功能概述 -- 设计用意 -- 职责范围 -- 项目内依赖 - -**暂不填**（留占位符 `（待阶段3填写）`）： -- 对外接口 -- 使用方法 -- 用例 - -**用 Claude Code 的做法**： - -```markdown -对 Claude Code 说： -"在 Document/Plugins/Item/ 下为以下每个单位创建独立的 .md 文件， -遵循 [粘贴模板]。每个单位一个文件，不要合并。 -现在只填基本信息、功能概述、设计用意、职责范围、项目内依赖。 -对外接口、使用方法、用例三个章节写'（待阶段3填写）'。" -``` - -然后把每个单位的结构化分析数据附在后面。 - -**注意**： -- 每个单位**必须独立成文件**，绝对不能合并 -- "设计用意"和"职责范围"是**两个独立章节**，不要偷懒合并 -- "职责范围"用自然语言，**禁止**出现"职责：/不负责："这种二分写法 -- 依赖表列名必须是 `依赖项 | 关系 | 源文件` - -**手动做法**： - -``` -对清单中的每个单位： -1. 创建 Document/[模块]/[单位名].md 文件 -2. 从步骤 2 的分析结果中抄入：基本信息、功能概述、设计用意、职责范围、依赖 -3. 最后三节写 "（待阶段3填写）" -``` - -### 步骤 4：阶段 2 — 生成关系文档 - -基于阶段 1 的依赖数据，为每个模块创建 `_relationships.md`。 - -**用 Claude Code 的做法**： - -```markdown -对 Claude Code 说： -"为 Document/Plugins/Item/ 创建 _relationships.md。 -表格列出每个文件间的 #include/forward-declare 关系。 -再列出关键数据/控制流依赖链，用简单文本箭头。" -``` - -**手动做法**： - -``` -1. 画一张表： - | 源文件 | 引用方式 | 目标文件 | 目标单位 | - -2. 从步骤 2 的 #include/forward-declare 数据中抄入 - -3. 画出关键数据流： - - 创建流程：谁调用谁的什么方法创建什么 - - 查询流程：谁通过谁获取什么数据 - - 更新流程：数据从哪来，经过谁，到哪去 -``` - -### 步骤 5：阶段 3 — 填充接口、使用方法和用例 - -这是最需要"搜代码"的阶段。 - -**对外接口**的做法： - -``` -对每个 C++ 单位： -1. 打开其头文件 -2. 找出所有 public/protected 方法 -3. 找出所有 UFUNCTION 宏（BlueprintCallable/BlueprintNativeEvent/BlueprintImplementableEvent） -4. 找出所有 UPROPERTY 宏（尤其是 BlueprintReadOnly/BlueprintReadWrite 的） -5. 找出所有 DECLARE_DELEGATE / DECLARE_DYNAMIC_MULTICAST_DELEGATE -6. 用"调用者视角"重写：不要罗列函数签名，而是描述"外部代码可以做哪些事" - 好例子："调用 GetItemViews() 获取所有物品的只读视图，用于 UI 列表展示" - 坏例子："GetItemViews() const -> TArray"（这是罗列签名） - -对每个蓝图单位： -1. 通过 MCP unreal_blueprint_query operation=inspect 查询变量和函数 -2. 描述蓝图事件图中可被外部调用的函数和事件 -3. 列出可编辑的实例变量 -``` - -**使用方法**的做法： - -``` -对每个单位： -1. grep 搜索它在项目中的所有使用位置 - rg "[单位名]" Source/ Plugins/ --type cpp --type h -2. 读相关代码段，理解它被如何使用 -3. 挑选 2-5 个最典型的用法 -4. 写成：文件路径:行号 — 在这段代码中是怎么用的 -``` - -**用例**的做法： - -``` -对每个单位： -1. 从 grep 结果中确定哪些文件会用到它 -2. 对每个使用文件写一条：文件路径:行号 — 用途说明 -3. 不要伪造。如果某个文件只是 include 了但没实际用，不要写进去 -``` - -**用 Claude Code 的做法**： - -```markdown -对 Claude Code 说： -"对 Document/Plugins/Item/ 下的所有 .md 文件， -用 Grep 搜索每个单位在 Source/ 和 Plugins/ 中的使用位置， -然后更新对外接口、使用方法、用例三个章节。 -要求每条引用有文件路径和行号，只写真实代码中存在的用法。" -``` - -### 步骤 6：阶段 4 — 更新 README.md - -``` -1. 列出所有 5 个模块 -2. 每个模块下列出所有单位、文件名（带链接）、类型、父类 -3. 描述文档模板的章节结构 -4. 写下统计数字：多少单位、多少文件、覆盖哪些模块 -``` - -### 步骤 7：验证 - -``` -□ 每个 .h 中定义的 class/struct/enum 都有对应的 .md 文件 -□ 没有多单位合并到一个文件的情况（检查文件名列表跟单位列表一一对应） -□ 每个 .md 的"设计用意"和"职责范围"是两个独立章节 -□ "职责范围"中没有出现"不负责"字样（这不是要求删除信息，而是用自然语言描述边界） -□ 每个 _relationships.md 的表格列名是"源文件|引用方式|目标文件|目标单位" -□ 每个使用方法/用例条目都带有文件路径和行号 -□ 没有编造的伪代码示例 -□ README.md 有完整的文档索引 -□ 所有占位符"(待阶段3填写)"已被替换 -``` - ---- - -## 四、工具速查 - -### 4.1 Grep 搜索命令 - -```bash -# 搜索某个类/结构体在项目中的使用 -rg "FItemView" Plugins/Item/ Source/ --type-add 'ue:*.h' --type-add 'ue:*.cpp' --type ue -n - -# 只列出文件名 -rg "IItemContainer" -l - -# 搜索 #include 关系 -rg '#include.*ItemFactory' Plugins/Item/ -``` - -### 4.2 MCP 蓝图查询命令 - -在 Claude Code 对话中可以直接用以下工具： - -``` -# 列出所有蓝图 -mcp__unrealclaude__unreal_blueprint_query operation=list path_filter=/Game/Blueprints/ limit=50 - -# 查看单个蓝图的变量和函数 -mcp__unrealclaude__unreal_blueprint_query operation=inspect - blueprint_path=/Game/Blueprints/BP_TestChar - include_variables=true - include_functions=true - -# 搜索资产 -mcp__unrealclaude__unreal_asset_search class_filter=Blueprint name_pattern=Test -``` - -### 4.3 Claude Code Task 代理 - -``` -# 启动一个分析代理（后台运行） -Task subagent_type=Explore run_in_background=true - prompt="分析 X 目录下所有头文件..." - -# 启动一个写文件的代理（后台运行） -Task subagent_type=general-purpose run_in_background=true - prompt="为以下单位创建/更新文档..." - -# 查看代理输出 -TaskOutput task_id=<代理ID> block=true timeout=120000 -``` - ---- - -## 五、作者注 - -### 我是怎么被骂的 - -第一轮跑完「项目文档化计划」后，用户逐项检查，指出了 10 个问题（详见第一章）。核心批评： - -1. **合并文件是最愚蠢的错误** — 文档的目的是让人查，文件名就是索引。把三个 struct 塞进一个 `ItemDataStructures.md`，等于给后人埋坑。 -2. **"设计用意"和"职责范围"不能合并** — 前者是历史/动机，后者是边界。维护者需要知道"为什么存在"，也需要知道"管多宽"。 -3. **自我编造示例代码** — 我写了一堆 `// 继承 AMyActor 创建自定义 Actor` 的伪代码。用户一眼看出这不是项目里的真实代码。 -4. **罗列函数签名** — 对外接口章节写成了 API reference，而不是从调用者角度说明"你能干什么"。 -5. **花式 ASCII 图** — `_relationships.md` 里搞了一堆 ASCII 艺术框图。用户要的是简洁的文件级表格。 - -### 为什么这个流程可以复现 - -- **模板化**：每个文档的结构完全一致，没有自由发挥空间 -- **可验证**：每条引用必须有文件路径和行号，grep 一下就能确认 -- **分阶段**：4 个阶段每条有明确的输入和输出，不会出现循环依赖 -- **工具支持**：Claude Code 的 Task 代理可以并行处理大量文件，MCP 可以查询二进制蓝图 - -### 如果你没有 Claude Code - -整个流程的核心逻辑不依赖 AI 工具。你可以纯手工完成： - -1. 在 Excel/Notion 里建一张表，列出所有单位及其分析数据（步骤 2） -2. 按模板逐个创建 .md 文件（步骤 3-5） -3. 用 grep/VSCode 搜索来验证引用关系（步骤 7） - -只是一个人做 56 个文档大概需要 3-5 个工作日。 - -### 后续维护 - -代码改动后，更新对应文档： -- 新增类：按模板创建新 .md，更新 `_relationships.md` 和 `README.md` -- 删除类：删除对应 .md，更新 `_relationships.md` 和 `README.md` -- 修改接口：更新"对外接口"章节和对应的"使用方法"引用 -- 修改依赖：更新"项目内依赖"表和 `_relationships.md` diff --git a/README.md b/README.md index 9ea6692..cfab3d2 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # lonese 项目文档 -> **维护者必读**：[HOWTO_REGENERATE_DOCS.md](HOWTO_REGENERATE_DOCS.md) — 文档是怎么生成的、踩过什么坑、如何复现。修改本文档之前请先看这篇。 - ## 文档索引 ### 一、Source/lonese/（4 单位） @@ -73,28 +71,57 @@ 依赖关系：[Plugins/CharacterControl/_relationships.md](Plugins/CharacterControl/_relationships.md) -### 五、Content/Blueprints/（15 单位） +### 五、Content/Blueprints/（32 单位） | 单位 | 文件 | 类型 | 父类 | |------|------|------|------| +| ABP_TestChar | [ABP_TestChar.md](Content/Blueprints/ABP_TestChar.md) | AnimBlueprint | AnimInstance | +| BP_Barrel | [BP_Barrel.md](Content/Blueprints/BP_Barrel.md) | Blueprint | Actor | +| BP_Bomb | [BP_Bomb.md](Content/Blueprints/BP_Bomb.md) | Blueprint | Actor | +| BP_CameraPawn | [BP_CameraPawn.md](Content/Blueprints/BP_CameraPawn.md) | Blueprint | ACameraPawn | +| BP_ControllerComp | [BP_ControllerComp.md](Content/Blueprints/BP_ControllerComp.md) | Blueprint | UEndpointComponent | +| BP_DefaultContainer | [BP_DefaultContainer.md](Content/Blueprints/BP_DefaultContainer.md) | Blueprint | UDefaultContainer | +| BP_DropItemInvComp | [BP_DropItemInvComp.md](Content/Blueprints/BP_DropItemInvComp.md) | Blueprint | BP_InventoryComp | +| BP_Hud | [BP_Hud.md](Content/Blueprints/BP_Hud.md) | Blueprint | HUD | +| BP_InventoryComp | [BP_InventoryComp.md](Content/Blueprints/BP_InventoryComp.md) | Blueprint | ActorComponent | +| BP_InventoryDrop | [BP_InventoryDrop.md](Content/Blueprints/BP_InventoryDrop.md) | Blueprint | Actor | +| BP_ItemTrap | [BP_ItemTrap.md](Content/Blueprints/BP_ItemTrap.md) | Blueprint | Actor | +| BP_ItemViewDataView | [BP_ItemViewDataView.md](Content/Blueprints/BP_ItemViewDataView.md) | Blueprint | Object | +| BP_MoveInput | [BP_MoveInput.md](Content/Blueprints/BP_MoveInput.md) | Blueprint | UEndpointComponent | +| BP_NewChar | [BP_NewChar.md](Content/Blueprints/BP_NewChar.md) | Blueprint | Character | +| BP_SayHello | [BP_SayHello.md](Content/Blueprints/BP_SayHello.md) | Blueprint | UEndpointComponent | | BP_TestChar | [BP_TestChar.md](Content/Blueprints/BP_TestChar.md) | Blueprint | AMyCharacter | | BP_TestCtl | [BP_TestCtl.md](Content/Blueprints/BP_TestCtl.md) | Blueprint | AMyPlayerController | -| BP_CameraPawn | [BP_CameraPawn.md](Content/Blueprints/BP_CameraPawn.md) | Blueprint | ACameraPawn | +| BP_TestItem | [BP_TestItem.md](Content/Blueprints/BP_TestItem.md) | Blueprint | Actor | +| BP_TestItemCluster | [BP_TestItemCluster.md](Content/Blueprints/BP_TestItemCluster.md) | Blueprint | Actor | | BP_TestMode | [BP_TestMode.md](Content/Blueprints/BP_TestMode.md) | Blueprint | GameModeBase | -| BP_Hud | [BP_Hud.md](Content/Blueprints/BP_Hud.md) | Blueprint | HUD | +| BP_Trap | [BP_Trap.md](Content/Blueprints/BP_Trap.md) | Blueprint | Actor | | BP_UniversalEndpointComp | [BP_UniversalEndpointComp.md](Content/Blueprints/BP_UniversalEndpointComp.md) | Blueprint | UEndpointComponent | -| BP_MoveInput | [BP_MoveInput.md](Content/Blueprints/BP_MoveInput.md) | Blueprint | UEndpointComponent | -| BP_ControllerComp | [BP_ControllerComp.md](Content/Blueprints/BP_ControllerComp.md) | Blueprint | UEndpointComponent | -| BP_SayHello | [BP_SayHello.md](Content/Blueprints/BP_SayHello.md) | Blueprint | UEndpointComponent | -| BP_DefaultContainer | [BP_DefaultContainer.md](Content/Blueprints/BP_DefaultContainer.md) | Blueprint | UDefaultContainer | -| BP_InventoryComp | [BP_InventoryComp.md](Content/Blueprints/BP_InventoryComp.md) | Blueprint | ActorComponent | -| BP_DropItemInvComp | [BP_DropItemInvComp.md](Content/Blueprints/BP_DropItemInvComp.md) | Blueprint | BP_InventoryComp | -| BP_Bomb | [BP_Bomb.md](Content/Blueprints/BP_Bomb.md) | Blueprint | Actor | -| WBP_TestUI | [WBP_TestUI.md](Content/Blueprints/WBP_TestUI.md) | Blueprint | UserWidget | -| WBP_InventoryView | [WBP_InventoryView.md](Content/Blueprints/WBP_InventoryView.md) | Blueprint | UserWidget | +| WBP_ChoiceButton | [WBP_ChoiceButton.md](Content/Blueprints/WBP_ChoiceButton.md) | WidgetBlueprint | UserWidget | +| WBP_Circle | [WBP_Circle.md](Content/Blueprints/WBP_Circle.md) | WidgetBlueprint | UserWidget | +| WBP_Hint | [WBP_Hint.md](Content/Blueprints/WBP_Hint.md) | WidgetBlueprint | UserWidget | +| WBP_InventoryView | [WBP_InventoryView.md](Content/Blueprints/WBP_InventoryView.md) | WidgetBlueprint | UserWidget | +| WBP_ItemViewBox | [WBP_ItemViewBox.md](Content/Blueprints/WBP_ItemViewBox.md) | WidgetBlueprint | UserWidget | +| WBP_Module1 | [WBP_Module1.md](Content/Blueprints/WBP_Module1.md) | WidgetBlueprint | UserWidget | +| WBP_Module2 | [WBP_Module2.md](Content/Blueprints/WBP_Module2.md) | WidgetBlueprint | UserWidget | +| WBP_Resources | [WBP_Resources.md](Content/Blueprints/WBP_Resources.md) | WidgetBlueprint | UserWidget | +| WBP_TestUI | [WBP_TestUI.md](Content/Blueprints/WBP_TestUI.md) | WidgetBlueprint | UserWidget | +| WBP_Window | [WBP_Window.md](Content/Blueprints/WBP_Window.md) | WidgetBlueprint | UserWidget | 依赖关系：[Content/Blueprints/_relationships.md](Content/Blueprints/_relationships.md) +### 六、Content/Data/（5 单位） + +| 单位 | 文件 | 类型 | 父类 | +|------|------|------|------| +| DA_InputCommands | [DA_InputCommands.md](Content/Data/DA_InputCommands.md) | InputCommandData | — | +| NewGraph | [NewGraph.md](Content/Data/NewGraph.md) | DialogGraphDataAsset | — | +| TestDialog | [TestDialog.md](Content/Data/TestDialog.md) | DataTable | — | +| TestDialogMap | [TestDialogMap.md](Content/Data/TestDialogMap.md) | DataTable | — | +| TestItemDefTable | [TestItemDefTable.md](Content/Data/TestItemDefTable.md) | DataTable | — | + +依赖关系：[Content/Data/_relationships.md](Content/Data/_relationships.md) + --- ## 文档模板说明 @@ -106,7 +133,7 @@ 3. **设计用意** — 为什么这样设计，解决什么问题，在系统中的定位 4. **职责范围** — 自然语言描述该单位承担的工作范围 5. **项目内依赖** — 文件级依赖表格 -6. **对外接口** — 从外部调用者视角描述的接口说明 +6. **外部视角** — 从外部调用者视角描述的接口说明 7. **使用方法** — 引用项目真实代码位置说明典型用法 8. **用例** — 项目中实际使用本单位的文件和上下文 @@ -116,6 +143,6 @@ ## 统计 -- **总单位数**: 56（4 + 14 + 10 + 13 + 15） -- **总文档文件**: 62（含 5 个 `_relationships.md` + 1 个 `README.md`） -- **覆盖模块**: 5（Source/lonese + 3 插件 + Content/Blueprints） +- **总单位数**: 78（4 + 14 + 10 + 13 + 32 + 5） +- **总文档文件**: 85（含 6 个 `_relationships.md` + 1 个 `README.md`） +- **覆盖模块**: 6（Source/lonese + 3 插件 + Content/Blueprints + Content/Data）