docs(review): P-008交互系统程序设计质量门审查通过+美术调研+工作流完善
- P-008 交互系统技术设计审查通过，审查记录 docs/plans/reviews/P-008-review.md - D-001 关卡执行案审查通过，审查记录 docs/plans/reviews/D-001-review.md - 新增 AI 美术调研参考图（我的暑假/放学后少年/真实场景/美术风格） - 新增关卡执行案、白模搭建指南和搭建报告 - 完善工作流技能：质量门审查、Agent记忆、需求分析 - 更新交互系统和角色控制系统技术设计文档 - 清理过时参考文档
This commit is contained in:
@@ -0,0 +1,297 @@
|
||||
# Mermaid 图表语法速查与项目约定
|
||||
|
||||
本文档为需求分析 skill 中各类图表的 Mermaid 语法参考和项目特定约定。
|
||||
|
||||
---
|
||||
|
||||
## 1. Mermaid 语法速查
|
||||
|
||||
### 1.1 功能领域图（步骤②）
|
||||
|
||||
使用 `flowchart` 展示功能模块及其交互关系。模块级抽象，不涉及类级别细节。
|
||||
|
||||
**语法模板**：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph 输入层
|
||||
PlayerInput[玩家输入模块]
|
||||
end
|
||||
|
||||
subgraph 核心层
|
||||
Movement[移动控制模块]
|
||||
Interaction[交互管理模块]
|
||||
end
|
||||
|
||||
subgraph 数据层
|
||||
ItemData[物品数据模块]
|
||||
CollectionData[收集数据模块]
|
||||
end
|
||||
|
||||
PlayerInput --> Movement
|
||||
PlayerInput --> Interaction
|
||||
Interaction -->|查询可交互物| ItemData
|
||||
Interaction -->|通知收集| CollectionData
|
||||
```
|
||||
|
||||
**要点**：
|
||||
- 使用 `subgraph` 划分模块边界（如输入层、核心层、数据层）
|
||||
- 节点使用中文标签标注模块职责
|
||||
- 边上可加 `|文字|` 说明交互类型
|
||||
- 不同层可用 `style` 着色区分
|
||||
|
||||
**样式区分**（可选）：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[模块A] --> B[模块B]
|
||||
A -.->|事件通知| C[模块C]
|
||||
|
||||
style A fill:#e1f5fe
|
||||
style B fill:#f3e5f5
|
||||
style C fill:#e8f5e9
|
||||
```
|
||||
|
||||
- `-->` 实线：主数据流 / 同步调用
|
||||
- `-.->` 虚线：事件通知 / 异步通信
|
||||
|
||||
---
|
||||
|
||||
### 1.2 类设计图（步骤③）
|
||||
|
||||
使用 `classDiagram` 展示类的关键数据、接口和关系。
|
||||
|
||||
**语法模板**：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class UInteractionManager {
|
||||
-EInteractionState State
|
||||
-EInteractPhase Phase
|
||||
-TArray~UInteractableComponent*~ NearbyInteractables
|
||||
+BeginInteract(UInteractableComponent* Target) void
|
||||
+EndInteract() void
|
||||
+TickComponent(float DeltaTime) void
|
||||
#OnDetectionEnter(UPrimitiveComponent* Overlapped) void
|
||||
}
|
||||
|
||||
class IChildHoodInteractable {
|
||||
<<interface>>
|
||||
+GetInteractableData() FInteractableData
|
||||
+OnInteract(AChildHoodCharacter* Player) void
|
||||
}
|
||||
|
||||
class UInteractableComponent {
|
||||
-FInteractableData Data
|
||||
-USphereComponent* DetectionSphere
|
||||
+GetInteractableData() FInteractableData
|
||||
+OnInteract(AChildHoodCharacter* Player) void
|
||||
}
|
||||
|
||||
class AChildHoodCharacter {
|
||||
-UInteractionManager* InteractionManager
|
||||
-bool bIsInteracting
|
||||
+SetInteracting(bool bValue) void
|
||||
}
|
||||
|
||||
UInteractionManager --> UInteractableComponent : 检测并驱动
|
||||
UInteractableComponent ..|> IChildHoodInteractable : 实现
|
||||
AChildHoodCharacter *-- UInteractionManager : 组合（持有）
|
||||
UInteractableComponent o-- USphereComponent : 聚合（引用）
|
||||
```
|
||||
|
||||
**关系类型速查**：
|
||||
|
||||
| 关系 | 语法 | 含义 | UE5 中的典型场景 |
|
||||
|------|------|------|------------------|
|
||||
| 继承 | `<\|--` | 子类继承父类 | `ACharacter` 的子类 |
|
||||
| 实现 | `..\|>` | 实现接口 | `UInterface` 的实现类 |
|
||||
| 组合 | `*--` | 生命周期绑定，整体拥有部分 | Character 持有 Component |
|
||||
| 聚合 | `o--` | 引用关系，部分可独立存在 | Component 引用另一个 Actor |
|
||||
| 依赖 | `..>` | 使用关系，临时引用 | 方法参数、局部变量 |
|
||||
| 关联 | `-->` | 持久引用 | 成员指针引用 |
|
||||
|
||||
**可见性标记**：
|
||||
|
||||
| 标记 | 含义 | UE5 惯例 |
|
||||
|------|------|---------|
|
||||
| `+` | public | `UFUNCTION(BlueprintCallable)` |
|
||||
| `-` | private | 内部状态 |
|
||||
| `#` | protected | 子类可访问 |
|
||||
|
||||
**UE5 类命名约定**：
|
||||
|
||||
| 前缀 | 类型 | 示例 |
|
||||
|------|------|------|
|
||||
| `A` | Actor | `AChildHoodCharacter` |
|
||||
| `U` | UObject / Component | `UInteractionManager` |
|
||||
| `I` | Interface | `IChildHoodInteractable` |
|
||||
| `F` | Struct / Enum | `FInteractableData` |
|
||||
| `E` | Enum | `EInteractType` |
|
||||
|
||||
---
|
||||
|
||||
### 1.3 时序图（步骤④）
|
||||
|
||||
使用 `sequenceDiagram` 追踪复杂特性的跨系统调用流程。
|
||||
|
||||
**语法模板**：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant Player as 玩家
|
||||
participant PC as PlayerController
|
||||
participant IM as InteractionManager
|
||||
participant IC as InteractableComponent
|
||||
participant CM as CollectionManager
|
||||
|
||||
Player->>PC: 按 E 键 (IA_Interact)
|
||||
activate PC
|
||||
PC->>IM: BeginInteract(SelectedInteractable)
|
||||
deactivate PC
|
||||
|
||||
activate IM
|
||||
IM->>IM: 状态 Free -> Interacting
|
||||
IM->>IM: 子阶段 Enter (转向+推镜)
|
||||
|
||||
IM->>IC: OnInteract(Player)
|
||||
activate IC
|
||||
IC->>IC: 检查交互类型 (Pickup)
|
||||
IC->>CM: AddItem(ItemId, Category)
|
||||
activate CM
|
||||
CM-->>IC: 收集成功
|
||||
deactivate CM
|
||||
IC-->>IM: 交互完成
|
||||
deactivate IC
|
||||
|
||||
IM->>IM: 子阶段 Exit (回位+淡出)
|
||||
IM->>IM: 状态 Interacting -> Free
|
||||
deactivate IM
|
||||
```
|
||||
|
||||
**要点**：
|
||||
- `participant` 使用 UE5 类名缩写 + 中文别名
|
||||
- `activate` / `deactivate` 展示调用栈深度
|
||||
- `->>` 同步调用，`-->>` 返回，`--)` 异步通知
|
||||
- `autonumber` 自动编号消息
|
||||
- `Note over` 可添加阶段说明
|
||||
|
||||
**消息类型**：
|
||||
|
||||
| 语法 | 含义 | 适用场景 |
|
||||
|------|------|---------|
|
||||
| `->>` | 实线箭头，同步调用 | 函数调用 |
|
||||
| `-->>` | 虚线箭头，返回 | 函数返回值 |
|
||||
| `--)` | 开放箭头，异步 | 委托广播、事件分发 |
|
||||
| `-x` | 叉号，失败 | 异常、条件不满足 |
|
||||
|
||||
---
|
||||
|
||||
### 1.4 流程图 / 鲁棒图（步骤⑥）
|
||||
|
||||
使用 `flowchart` 描述复杂接口的决策分支和执行流程。
|
||||
|
||||
**语法模板**：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([BeginInteract 被调用]) --> CheckState{当前状态?}
|
||||
CheckState -->|Free| CheckSelected{是否有选中的可交互物?}
|
||||
CheckState -->|Interacting| Reject1([返回：已在交互中])
|
||||
|
||||
CheckSelected -->|是| SetState[State = Interacting<br/>Phase = Enter]
|
||||
CheckSelected -->|否| Reject2([返回：无可交互物])
|
||||
|
||||
SetState --> TurnAndPush[执行角色转向<br/>执行摄像机推镜]
|
||||
TurnAndPush --> CheckAnim{需要等待动画?}
|
||||
CheckAnim -->|是| AnimLock[Phase = AnimLock<br/>等待动画事件]
|
||||
CheckAnim -->|否| Active[Phase = Active]
|
||||
|
||||
AnimLock --> Active
|
||||
Active --> ExecuteLogic[根据交互类型执行具体逻辑]
|
||||
ExecuteLogic --> EndFlow([进入 Exit 阶段])
|
||||
```
|
||||
|
||||
**要点**：
|
||||
- `([...])` 圆角矩形：开始/结束节点
|
||||
- `{...}` 菱形：判断/分支节点
|
||||
- `[...]` 矩形：处理/动作节点
|
||||
- 边上的 `|文字|` 标注分支条件
|
||||
- 每个分支都要有明确的去向（不允许"悬空"分支）
|
||||
|
||||
---
|
||||
|
||||
## 2. 项目约定
|
||||
|
||||
### 2.1 命名约定
|
||||
|
||||
- **类名节点**：使用 UE5 完整类名（`AChildHoodCharacter`、`UInteractionManager`），不缩写
|
||||
- **模块名节点**：使用中文（`交互管理模块`、`物品数据模块`）
|
||||
- **时序图参与者**：UE5 类名缩写 + 中文别名（`IM as InteractionManager`）
|
||||
- **函数/方法**：保留 C++ 命名（`BeginInteract()`），不翻译
|
||||
- **变量/属性**：使用 UE5 属性名（`bIsInteracting`、`MaxWalkSpeed`）
|
||||
|
||||
### 2.2 UE5 特有模式的表示
|
||||
|
||||
| UE5 概念 | Mermaid 表示 | 示例 |
|
||||
|----------|-------------|------|
|
||||
| Component 挂载 | 组合关系 `*--` | Character `*--` InteractionManager |
|
||||
| Interface 实现 | 实现关系 `..\|>` | InteractableComponent `..\|>` IChildHoodInteractable |
|
||||
| Delegate 广播 | 异步消息 `--)` | `OnItemCollected--)` CollectionManager |
|
||||
| Enhanced Input | 时序图入口 | `Player->>PC: 按 E 键 (IA_Interact)` |
|
||||
| DataAsset | 聚合关系 `o--` | Manager `o--` ConfigDataAsset |
|
||||
| Subsystem | 单例节点 | `UGameInstanceSubsystem` 作为独立节点 |
|
||||
|
||||
### 2.3 图表复杂度控制
|
||||
|
||||
- **功能领域图**：控制在 5-10 个模块节点。超过 10 个考虑拆分子图。
|
||||
- **类设计图**：聚焦核心类（3-8 个）。辅助类（如 `FVector`、`FRotator` 等 UE 内置类型）不单独列出。
|
||||
- **时序图**：单张控制在 15-25 条消息。超过 25 条按子流程拆分多张图。
|
||||
- **流程图**：控制在 10-20 个节点。超过 20 个按子流程拆分。
|
||||
|
||||
---
|
||||
|
||||
## 3. 复杂度判定启发式
|
||||
|
||||
### 3.1 何时需要时序图（步骤④）
|
||||
|
||||
时序图为条件性步骤，仅在特性满足以下任一条件时需要绘制：
|
||||
|
||||
| 条件 | 判定 | 示例 |
|
||||
|------|------|------|
|
||||
| 涉及 3+ 个系统协调 | 需要 | 拾取流程：InteractionManager → ItemManager → CollectionManager |
|
||||
| 有条件分支或循环流程 | 需要 | 交互流程：根据交互类型走不同子流程 |
|
||||
| 跨层级通信（UI ↔ 逻辑 ↔ 数据） | 需要 | 提示 UI 显示 → 检测逻辑 → 数据查询 |
|
||||
| 仅涉及单系统内部配置 | 不需要 | SpringArm 参数调整（纯配置） |
|
||||
| 仅 2 个系统简单调用 | 可选 | Character 设置 flag → Movement 检查 flag |
|
||||
|
||||
### 3.2 何时需要复杂接口描述（步骤⑥）
|
||||
|
||||
复杂接口描述为条件性步骤，仅在接口满足以下任一条件时需要：
|
||||
|
||||
| 条件 | 判定 | 示例 |
|
||||
|------|------|------|
|
||||
| 5+ 个决策分支 | 需要 | `BeginInteract()`：状态检查 → 选中检查 → 类型分发 → 阶段管理 |
|
||||
| 协调多个子系统状态 | 需要 | 状态机转换：涉及移动状态、摄像机状态、UI 状态的切换 |
|
||||
| 有异步等待或回调链 | 需要 | 等待动画事件 → 触发后续逻辑 → 等待推镜完成 |
|
||||
| 纯数据查询或简单赋值 | 不需要 | `GetInteractableData()`：直接返回成员变量 |
|
||||
| 2-4 个分支的简单逻辑 | 可选 | `SetInteracting()`：设置 flag + 通知 UI |
|
||||
|
||||
### 3.3 项目实际案例参考
|
||||
|
||||
**需要时序图的特性**（从现有 `interaction-system-tech.md` 提取）：
|
||||
- 完整交互流程（Enter → AnimLock → Active → Exit）
|
||||
- 拾取流程（交互系统 → 物品系统 → 收集系统）
|
||||
|
||||
**不需要时序图的特性**（从现有 `player-controller-tech.md` 提取）：
|
||||
- SpringArm 参数配置（纯构造函数设置）
|
||||
- CMC 移动参数调整（纯配置）
|
||||
|
||||
**需要复杂接口描述的接口**：
|
||||
- `UInteractionManager::BeginInteract()` — 状态检查 + 子阶段管理 + 摄像机推镜 + 动画等待
|
||||
- `UInteractionManager::TickComponent()` — 检测更新 + 状态机驱动 + 推镜插值 + UI 更新
|
||||
|
||||
**不需要复杂接口描述的接口**：
|
||||
- `AChildHoodCharacter::DoMove()` — 直接调用 AddMovementInput
|
||||
- `AChildHoodCharacter::IsInteracting()` — 直接返回 bool
|
||||
@@ -0,0 +1,376 @@
|
||||
# 需求分析各步骤示例
|
||||
|
||||
本文档从项目现有技术设计文档中提取注释示例，展示每步分析的实际输出效果。
|
||||
|
||||
---
|
||||
|
||||
## 示例来源
|
||||
|
||||
| 示例 | 来源文档 |
|
||||
|------|---------|
|
||||
| 交互系统 | `docs/technical/interaction-system-tech.md` |
|
||||
| 角色控制 | `docs/technical/player-controller-tech.md` |
|
||||
| 收集系统 | `docs/technical/collection-system-tech.md` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 需求功能点罗列示例
|
||||
|
||||
以**交互系统**为例，展示如何从执行文档的行为规则中提取功能点并分类：
|
||||
|
||||
### UE 内置功能
|
||||
|
||||
| 功能点 | 使用的 UE 内置能力 | 对应行为规则 | 备注 |
|
||||
|--------|-------------------|-------------|------|
|
||||
| 交互触发输入（E/ESC/Tab） | Enhanced Input (IA_Interact / IA_Cancel / IA_SwitchInteract) | I3 交互输入 | 通过 IMC 映射，无需自定义输入框架 |
|
||||
| 摄像机推镜 | SetViewTargetWithBlend + SpringArm | C1-C5 摄像机系统 | 推镜时切换 ViewTarget，回位时切回 |
|
||||
| 移动输入屏蔽 | CMC 移动组件 + bIsInteracting 标志 | P1 交互中忽略移动 | 在 DoMove() 中检查标志即可 |
|
||||
| 视角旋转限幅 | PlayerCameraManager::ViewPitchMin/Max | C3 视角旋转 | 直接设置属性 |
|
||||
| 摄像机碰撞 | SpringArm::bDoCollisionTest | C4 摄像机碰撞 | 原生支持 |
|
||||
|
||||
### 自定义实现
|
||||
|
||||
| 功能点 | 实现方式概述 | 对应行为规则 | 预估复杂度 |
|
||||
|--------|-------------|-------------|-----------|
|
||||
| 交互类型分发（观察/拾取/操作/对话） | 枚举 EInteractType + switch 分发 | 交互类型系统 | 中 |
|
||||
| 可交互物检测与选择 | 自定义 SphereComponent 碰撞检测 + 距离排序 | 检测与选择规则 | 中 |
|
||||
| 交互状态机（Free/Interacting + 子阶段） | 自定义 UActorComponent 管理状态 | 交互流程规则 | 高 |
|
||||
| 交互提示 UI | 自定义 UMG Widget | 提示显示规则 | 低 |
|
||||
| 叙事文本展示 | 自定义 UMG Widget + 文本列表随机选取 | 文本展示规则 | 低 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 功能领域图示例
|
||||
|
||||
以**交互系统**为例，展示模块级的功能领域图：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph 玩家侧
|
||||
Input[输入处理模块]
|
||||
CharState[角色状态模块]
|
||||
end
|
||||
|
||||
subgraph 交互核心
|
||||
Detection[检测与选择模块]
|
||||
StateMachine[交互状态机模块]
|
||||
CameraCtrl[摄像机控制模块]
|
||||
end
|
||||
|
||||
subgraph 可交互物侧
|
||||
InteractableData[交互物数据模块]
|
||||
Trigger[触发区域模块]
|
||||
end
|
||||
|
||||
subgraph 表现层
|
||||
PromptUI[提示 UI 模块]
|
||||
TextUI[叙事文本 UI 模块]
|
||||
end
|
||||
|
||||
subgraph 下游系统
|
||||
ItemSys[物品系统]
|
||||
CollectionSys[收集系统]
|
||||
end
|
||||
|
||||
Input -->|E/ESC/Tab| StateMachine
|
||||
Detection -->|可交互物列表| StateMachine
|
||||
StateMachine -->|锁定/解锁| CharState
|
||||
StateMachine -->|推镜/回位| CameraCtrl
|
||||
StateMachine -->|显示/隐藏| PromptUI
|
||||
StateMachine -->|显示文本| TextUI
|
||||
StateMachine -.->|拾取通知| ItemSys
|
||||
ItemSys -.->|收集通知| CollectionSys
|
||||
Trigger -->|进入/离开| Detection
|
||||
InteractableData -->|交互数据| Detection
|
||||
```
|
||||
|
||||
### 模块职责说明
|
||||
|
||||
| 模块 | 职责 | 关键输入 | 关键输出 |
|
||||
|------|------|---------|---------|
|
||||
| 输入处理模块 | 接收玩家按键，转发给状态机 | Enhanced Input IA 回调 | BeginInteract / Cancel / Switch |
|
||||
| 检测与选择模块 | 维护附近可交互物列表，选择最近的 | SphereComponent 碰撞事件 | NearbyInteractables 列表 |
|
||||
| 交互状态机模块 | 管理交互全流程状态转换 | 玩家输入 + 检测结果 + 动画事件 | 状态转换 + 驱动其他模块 |
|
||||
| 摄像机控制模块 | 交互中推镜和回位 | 状态机阶段信号 | ViewTarget 切换 |
|
||||
| 交互物数据模块 | 存储单个可交互物的配置数据 | 配置文件 | FInteractableData |
|
||||
| 触发区域模块 | 检测玩家进入/离开交互范围 | SphereComponent 碰撞 | 注册/注销检测列表 |
|
||||
| 提示 UI 模块 | 显示 `[E] 查看旧冰箱` 格式的提示 | 选中状态变化 | 视觉提示 |
|
||||
| 叙事文本 UI 模块 | 显示半透明背景 + 文字的叙事内容 | 交互完成信号 | 文本展示 + 淡出 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 类设计图示例
|
||||
|
||||
以**交互系统**为例，将功能领域图细化为类设计：
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class AChildHoodCharacter {
|
||||
-UInteractionManager* InteractionManager
|
||||
-UItemManager* ItemManager
|
||||
-UCollectionManager* CollectionManager
|
||||
-bool bIsInteracting
|
||||
+SetInteracting(bool bValue) void
|
||||
+IsInteracting() bool
|
||||
+DoMove(float Right, float Forward) void
|
||||
}
|
||||
|
||||
class AChildHoodPlayerController {
|
||||
+SetupPlayerInputComponent() void
|
||||
}
|
||||
|
||||
class UInteractionManager {
|
||||
-EInteractionState State
|
||||
-EInteractPhase Phase
|
||||
-TArray~UInteractableComponent*~ NearbyInteractables
|
||||
-int32 SelectedIndex
|
||||
-UInteractableComponent* CurrentInteractable
|
||||
+BeginInteract() void
|
||||
+CancelInteract() void
|
||||
+SwitchTarget(int32 Direction) void
|
||||
#OnDetectionEnter(UPrimitiveComponent*) void
|
||||
#OnDetectionExit(UPrimitiveComponent*) void
|
||||
}
|
||||
|
||||
class IChildHoodInteractable {
|
||||
<<interface>>
|
||||
+GetInteractableData() FInteractableData
|
||||
+OnInteract(AChildHoodCharacter*) void
|
||||
}
|
||||
|
||||
class UInteractableComponent {
|
||||
-FInteractableData Data
|
||||
-USphereComponent* DetectionSphere
|
||||
+GetInteractableData() FInteractableData
|
||||
+OnInteract(AChildHoodCharacter*) void
|
||||
}
|
||||
|
||||
class FInteractableData {
|
||||
+FName ItemId
|
||||
+FString DisplayName
|
||||
+EInteractType Type
|
||||
+float TriggerRadius
|
||||
+bool bOneShot
|
||||
+FString InteractVerb
|
||||
+TArray~FString~ NarrativeTexts
|
||||
+bool bUseCameraPush
|
||||
+EPostAction PostAction
|
||||
}
|
||||
|
||||
AChildHoodCharacter *-- UInteractionManager : 组合（持有）
|
||||
AChildHoodCharacter --> AChildHoodPlayerController : 关联
|
||||
UInteractionManager --> UInteractableComponent : 检测并驱动
|
||||
UInteractableComponent ..|> IChildHoodInteractable : 实现
|
||||
UInteractableComponent *-- FInteractableData : 组合（内含）
|
||||
UInteractableComponent o-- USphereComponent : 聚合（引用）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 时序图示例
|
||||
|
||||
以**交互系统拾取流程**为例，展示复杂特性的时序图：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant Player as 玩家
|
||||
participant PC as PlayerController
|
||||
participant IM as InteractionManager
|
||||
participant IC as InteractableComponent
|
||||
participant Char as Character
|
||||
participant ItemMgr as ItemManager
|
||||
participant CollMgr as CollectionManager
|
||||
|
||||
Player->>PC: 按 E 键 (IA_Interact)
|
||||
activate PC
|
||||
PC->>IM: BeginInteract()
|
||||
deactivate PC
|
||||
|
||||
activate IM
|
||||
IM->>IM: 检查 State == Free
|
||||
IM->>IM: State = Interacting, Phase = Enter
|
||||
|
||||
IM->>Char: SetInteracting(true)
|
||||
IM->>IM: 执行角色转向 + 摄像机推镜
|
||||
|
||||
Note over IM: Phase: Enter → AnimLock/Active
|
||||
|
||||
IM->>IC: OnInteract(Character)
|
||||
activate IC
|
||||
IC->>IC: 检查 Type == Pickup
|
||||
|
||||
IC->>ItemMgr: OnItemPickedUp(ItemId, Category)
|
||||
activate ItemMgr
|
||||
ItemMgr-->>IC: 处理完成
|
||||
deactivate ItemMgr
|
||||
|
||||
ItemMgr--)CollMgr: OnItemCollectedEvent(ItemId, Category)
|
||||
activate CollMgr
|
||||
CollMgr->>CollMgr: 判重 → 记录 → 弹通知
|
||||
deactivate CollMgr
|
||||
|
||||
IC-->>IM: 交互完成
|
||||
deactivate IC
|
||||
|
||||
IM->>IM: Phase = Exit (回位 + 淡出)
|
||||
IM->>Char: SetInteracting(false)
|
||||
IM->>IM: State = Free
|
||||
deactivate IM
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 核心数据结构示例
|
||||
|
||||
以**交互系统**的 `FInteractableData` 为例，展示良好的数据结构文档：
|
||||
|
||||
```cpp
|
||||
// 交互类型
|
||||
UENUM(BlueprintType)
|
||||
enum class EInteractType : uint8
|
||||
{
|
||||
Examine, // 观察
|
||||
Pickup, // 拾取
|
||||
Operate, // 操作
|
||||
Talk // 对话
|
||||
};
|
||||
|
||||
// 交互系统顶层状态
|
||||
UENUM(BlueprintType)
|
||||
enum class EInteractionState : uint8
|
||||
{
|
||||
Free, // 自由状态
|
||||
Interacting, // 交互中
|
||||
};
|
||||
|
||||
// Interacting 子阶段
|
||||
UENUM(BlueprintType)
|
||||
enum class EInteractPhase : uint8
|
||||
{
|
||||
None,
|
||||
Enter, // 进入：转向 + 推镜
|
||||
AnimLock, // 动画锁定：等待动画播完
|
||||
Active, // 活跃：等待玩家输入
|
||||
Exit // 退出：回位 + 淡出
|
||||
};
|
||||
|
||||
// 可交互物配置数据
|
||||
USTRUCT(BlueprintType)
|
||||
struct FInteractableData
|
||||
{
|
||||
GENERATED_BODY()
|
||||
|
||||
// 基本信息
|
||||
UPROPERTY(EditAnywhere, BlueprintReadWrite)
|
||||
FName ItemId; // 物品唯一ID（如 "fridge_home"）
|
||||
|
||||
UPROPERTY(EditAnywhere, BlueprintReadWrite)
|
||||
FString DisplayName; // 显示名称（如 "旧冰箱"）
|
||||
|
||||
UPROPERTY(EditAnywhere, BlueprintReadWrite)
|
||||
EInteractType Type = EInteractType::Examine;
|
||||
|
||||
// 触发
|
||||
UPROPERTY(EditAnywhere, BlueprintReadWrite)
|
||||
float TriggerRadius = 150.0f; // 触发半径（cm）
|
||||
|
||||
UPROPERTY(EditAnywhere, BlueprintReadWrite)
|
||||
bool bOneShot = false; // 一次性消耗
|
||||
|
||||
// 提示文本
|
||||
UPROPERTY(EditAnywhere, BlueprintReadWrite)
|
||||
FString InteractVerb; // 动作词（如 "查看"、"拾取"）
|
||||
|
||||
// 叙事文本
|
||||
UPROPERTY(EditAnywhere, BlueprintReadWrite)
|
||||
TArray<FString> NarrativeTexts; // 文本列表，随机选取
|
||||
|
||||
// 摄像机推镜
|
||||
UPROPERTY(EditAnywhere, BlueprintReadWrite)
|
||||
bool bUseCameraPush = false;
|
||||
|
||||
UPROPERTY(EditAnywhere, BlueprintReadWrite)
|
||||
float CameraPushDistance = 100.0f;
|
||||
|
||||
UPROPERTY(EditAnywhere, BlueprintReadWrite)
|
||||
float CameraPushDuration = 0.5f;
|
||||
|
||||
// 结束动作
|
||||
UPROPERTY(EditAnywhere, BlueprintReadWrite)
|
||||
EPostAction PostAction = EPostAction::Return;
|
||||
};
|
||||
```
|
||||
|
||||
**要点**：
|
||||
- 使用 `UPROPERTY` 标记所有需要暴露给蓝图的属性
|
||||
- 每个属性都有中文注释说明用途
|
||||
- 提供合理的默认值
|
||||
- UE5 类型前缀规范：`E` 枚举、`F` 结构体
|
||||
|
||||
---
|
||||
|
||||
## 6. 复杂接口描述示例
|
||||
|
||||
以**交互系统 `BeginInteract()`** 为例，展示如何用流程图描述复杂接口：
|
||||
|
||||
### 流程图示例
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([BeginInteract 被调用]) --> CheckState{State == Free?}
|
||||
CheckState -->|否| Reject1([返回：已在交互中])
|
||||
|
||||
CheckState -->|是| CheckSelected{SelectedInteractable 有效?}
|
||||
CheckSelected -->|否| Reject2([返回：无选中目标])
|
||||
|
||||
CheckSelected -->|是| SetState[State = Interacting<br/>Phase = Enter]
|
||||
SetState --> LockInput[Character.SetInteracting true<br/>屏蔽移动输入]
|
||||
LockInput --> Turn[角色转向目标<br/>插值旋转]
|
||||
|
||||
Turn --> PushCam{需要推镜?}
|
||||
PushCam -->|是| DoPush[摄像机推镜<br/>SetViewTargetWithBlend]
|
||||
PushCam -->|否| CheckAnim
|
||||
DoPush --> CheckAnim{需要等待动画?}
|
||||
|
||||
CheckAnim -->|是| AnimLock[Phase = AnimLock<br/>等待 AnimNotify]
|
||||
CheckAnim -->|否| Active[Phase = Active]
|
||||
|
||||
AnimLock -->|AnimNotify 触发| Active
|
||||
Active --> ExecuteType[根据 InteractType 分发]
|
||||
|
||||
ExecuteType -->|Examine| ShowText[显示叙事文本<br/>Phase = Exit]
|
||||
ExecuteType -->|Pickup| DoPickup[通知 ItemManager<br/>Phase = Exit]
|
||||
ExecuteType -->|Operate| DoOperate[执行操作逻辑<br/>Phase = Exit]
|
||||
ExecuteType -->|Talk| DoTalk[进入对话<br/>Phase = Exit]
|
||||
```
|
||||
|
||||
### 伪代码示例
|
||||
|
||||
以**收集系统 `OnItemReceived()`** 为例，展示伪代码风格：
|
||||
|
||||
```
|
||||
function OnItemReceived(ItemId, Category, Number):
|
||||
前置检查:
|
||||
1. Category != TargetCategory → 忽略（不是追踪品类）
|
||||
2. CollectedIDs.Contains(ItemId) → 忽略（已收集过）
|
||||
|
||||
核心逻辑:
|
||||
3. CollectedIDs.Add(ItemId) → 记录收集
|
||||
4. Progress++ → 更新计数
|
||||
5. 延迟 NotificationDelay 后:
|
||||
- 创建 WBP_CollectionNotification
|
||||
- 显示 "发现了新的杂物，进度 X/Y"
|
||||
6. 更新 WBP_CollectionProgress → 弹性动画
|
||||
|
||||
完成判定:
|
||||
7. if Progress >= TotalCount AND NOT bIsComplete:
|
||||
- bIsComplete = true
|
||||
- 延迟后: 进度 UI 变金色 + 弹出完成提示
|
||||
```
|
||||
|
||||
**要点**：
|
||||
- 先做前置检查（快速失败）
|
||||
- 核心逻辑按顺序执行
|
||||
- 异步操作（延迟、动画）明确标注
|
||||
- 完成判定/边界情况放在最后
|
||||
@@ -0,0 +1,337 @@
|
||||
# 技术设计文档输出模板
|
||||
|
||||
本模板定义需求分析 8 步流程产出的技术设计文档的标准结构。所有技术设计文档必须遵循此模板。
|
||||
|
||||
---
|
||||
|
||||
## 模板
|
||||
|
||||
```markdown
|
||||
# <系统名称> 技术设计文档（<版本号> <阶段>）
|
||||
|
||||
> 任务ID: <任务编号>
|
||||
> 对应执行案: `<执行案文件路径>`
|
||||
> 关联系统: <上游/下游/平行系统列表>
|
||||
> 阶段: 原型 / 批量生产 / 测试
|
||||
> 日期: <YYYY-MM-DD>
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
<系统的一句话定位>。<系统在当前版本中要做什么、不做什么>。
|
||||
|
||||
**实现复杂度**：低 / 中 / 中-高 / 高
|
||||
**预估工期**：<X-Y 天>
|
||||
**新增/修改代码量**：约 <XXX-YYY> 行 C++ + <N> 个 UMG 蓝图
|
||||
|
||||
---
|
||||
|
||||
## 1. 需求功能点罗列
|
||||
|
||||
将执行文档中所有行为规则逐一列出，按实现方式分类。
|
||||
|
||||
### UE 内置功能
|
||||
|
||||
以下功能点直接使用 UE5 引擎内置能力，无需或仅需极少量自定义代码：
|
||||
|
||||
| 功能点 | 使用的 UE 内置能力 | 对应行为规则 | 备注 |
|
||||
|--------|-------------------|-------------|------|
|
||||
| <功能描述> | <如：SpringArm Camera Lag、Enhanced Input、CMC 参数、SetViewTargetWithBlend 等> | <执行案条目编号> | <配置说明> |
|
||||
|
||||
### 自定义实现
|
||||
|
||||
以下功能点需要编写自定义 C++ / 蓝图代码：
|
||||
|
||||
| 功能点 | 实现方式概述 | 对应行为规则 | 预估复杂度 |
|
||||
|--------|-------------|-------------|-----------|
|
||||
| <功能描述> | <如：新建 UActorComponent 管理状态机、自定义 UI Widget 等> | <执行案条目编号> | 低/中/高 |
|
||||
|
||||
> **分类原则**：如果 UE 内置能力能覆盖 80% 以上的需求且行为一致，归为"UE 内置"。需要自定义状态管理、跨系统协调或特殊逻辑的归为"自定义实现"。
|
||||
|
||||
---
|
||||
|
||||
## 2. 功能领域图
|
||||
|
||||
展示当前系统由哪些功能模块组成，以及模块之间的关系。注意：此处只关注功能领域和领域之间的关系，不细分到类级别。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph <层名1>
|
||||
<模块A>[<模块A名称>]
|
||||
<模块B>[<模块B名称>]
|
||||
end
|
||||
|
||||
subgraph <层名2>
|
||||
<模块C>[<模块C名称>]
|
||||
end
|
||||
|
||||
<模块A> -->|<交互说明>| <模块C>
|
||||
<模块B> -.->|<事件通知>| <模块C>
|
||||
```
|
||||
|
||||
### 模块职责说明
|
||||
|
||||
| 模块 | 职责 | 关键输入 | 关键输出 |
|
||||
|------|------|---------|---------|
|
||||
| <模块名> | <一句话描述> | <从哪接收什么> | <向谁发送什么> |
|
||||
|
||||
---
|
||||
|
||||
## 3. 类设计图
|
||||
|
||||
将功能领域图细化为具体的类设计。展示每个类的关键数据成员、关键接口，以及类之间的关系类型。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class <类名> {
|
||||
<可见性><数据成员/接口>
|
||||
}
|
||||
|
||||
<类A> *-- <类B> : <关系说明>
|
||||
<类C> ..|> <接口D> : <关系说明>
|
||||
```
|
||||
|
||||
### 关系类型说明
|
||||
|
||||
| 关系类型 | 含义 | 本项目中的体现 |
|
||||
|---------|------|--------------|
|
||||
| 继承 `<\|--` | 子类继承父类 | Actor/Component 继承 |
|
||||
| 实现 `..\|>` | 实现接口 | UInterface 实现 |
|
||||
| 组合 `*--` | 生命周期绑定 | Character 持有 Component |
|
||||
| 聚合 `o--` | 引用但非拥有 | 引用其他 Actor/Component |
|
||||
| 依赖 `..>` | 临时使用 | 方法参数、局部变量 |
|
||||
|
||||
### 新增类
|
||||
|
||||
| 类名 | 类型 | 职责 | 位置 |
|
||||
|------|------|------|------|
|
||||
| <UE5类名> | <UActorComponent / UInterface / AActor 等> | <一句话职责> | <Source/ 子目录> |
|
||||
|
||||
### 修改类
|
||||
|
||||
| 类名 | 修改内容 |
|
||||
|------|---------|
|
||||
| <已有类名> | <新增成员/接口/修改逻辑> |
|
||||
|
||||
### 新增蓝图
|
||||
|
||||
| 蓝图名 | 类型 | 用途 |
|
||||
|--------|------|------|
|
||||
| <BP_前缀名称> | <UMG Widget / Actor Blueprint 等> | <用途说明> |
|
||||
|
||||
---
|
||||
|
||||
## 4. 时序图（仅复杂特性）
|
||||
|
||||
> ⚠️ 条件性章节：仅当特性涉及 3+ 个系统协调，或有条件分支/循环流程时才需要绘制。
|
||||
> 简单特性（如纯参数配置、单系统内部逻辑）跳过此章节。
|
||||
|
||||
### <特性名称> 时序图
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant <别名1> as <中文名1>
|
||||
participant <别名2> as <中文名2>
|
||||
|
||||
<别名1>->><别名2>: <消息描述>
|
||||
activate <别名2>
|
||||
<别名2>-->><别名1>: <返回描述>
|
||||
deactivate <别名2>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 核心数据结构
|
||||
|
||||
### 枚举
|
||||
|
||||
```cpp
|
||||
UENUM(BlueprintType)
|
||||
enum class E<EnumName> : uint8
|
||||
{
|
||||
<Value1>, // <中文说明>
|
||||
<Value2>, // <中文说明>
|
||||
};
|
||||
```
|
||||
|
||||
### 配置数据结构
|
||||
|
||||
```cpp
|
||||
USTRUCT(BlueprintType)
|
||||
struct F<StructName>
|
||||
{
|
||||
GENERATED_BODY()
|
||||
|
||||
// <分组说明>
|
||||
UPROPERTY(EditAnywhere, BlueprintReadWrite)
|
||||
<Type> <PropertyName> = <DefaultValue>; // <中文说明>
|
||||
};
|
||||
```
|
||||
|
||||
### 类关键数据定义
|
||||
|
||||
```cpp
|
||||
UCLASS()
|
||||
class U<ClassName> : public U<ParentClass>
|
||||
{
|
||||
GENERATED_BODY()
|
||||
|
||||
// === 配置参数（构造函数设置默认值） ===
|
||||
UPROPERTY(EditAnywhere, Category="<Category>")
|
||||
<Type> <Property> = <Default>; // <说明>
|
||||
|
||||
// === 运行时状态 ===
|
||||
<Type> <Property>; // <说明>
|
||||
|
||||
// === 关键接口 ===
|
||||
UFUNCTION(BlueprintCallable)
|
||||
void <MethodName>(<Params>); // <说明>
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 行为规则 → 实现方案映射
|
||||
|
||||
对执行文档中每条行为规则，逐一说明实现方案。复杂接口使用鲁棒图/流程图/伪代码描述。
|
||||
|
||||
### 一、<规则分组标题>
|
||||
|
||||
#### <规则编号>. <规则简述>
|
||||
|
||||
**实现**：<一句话概述实现方式>
|
||||
|
||||
```cpp
|
||||
// 关键代码片段
|
||||
```
|
||||
|
||||
**可调参数**：<参数名>, <范围/默认值>
|
||||
|
||||
---
|
||||
|
||||
#### <复杂接口名称>（复杂接口描述）
|
||||
|
||||
> ⚠️ 条性章节：仅当接口有 5+ 个决策分支或协调多个子系统状态时才需要。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([入口]) --> Check{判断?}
|
||||
Check -->|条件A| ActionA[执行A]
|
||||
Check -->|条件B| ActionB[执行B]
|
||||
ActionA --> End([结束])
|
||||
ActionB --> End
|
||||
```
|
||||
|
||||
或使用伪代码：
|
||||
|
||||
```
|
||||
function <InterfaceName>(<params>):
|
||||
1. <步骤1：前置检查>
|
||||
2. <步骤2：状态更新>
|
||||
3. <步骤3：根据类型分发>
|
||||
- 类型A → <处理A>
|
||||
- 类型B → <处理B>
|
||||
4. <步骤4：后续通知>
|
||||
5. <步骤5：状态清理>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 美术资源需求
|
||||
|
||||
| 资源类型 | 名称 | 数量 | 规格 | 触发时机/用途 |
|
||||
|----------|------|------|------|---------------|
|
||||
| <3D模型/动画/UI/2D图标/音效> | <名称> | <数量> | <尺寸/格式/时长> | <何时使用> |
|
||||
|
||||
> v0.1 原型阶段允许占位资源，但类型和数量必须明确。
|
||||
|
||||
---
|
||||
|
||||
## 8. 技术风险与注意事项
|
||||
|
||||
| 风险 | 等级 | 说明 | 缓解措施 |
|
||||
|------|------|------|---------|
|
||||
| <风险描述> | 🔴高/🟡中/🟢低 | <详细说明> | <如何应对> |
|
||||
|
||||
### 注意事项
|
||||
|
||||
1. **<注意事项标题>**：<详细说明>
|
||||
|
||||
---
|
||||
|
||||
## 9. 数据流
|
||||
|
||||
### 配置参数流
|
||||
|
||||
```
|
||||
<数据来源> → <加载方式> → <使用位置>
|
||||
```
|
||||
|
||||
### 运行时状态流
|
||||
|
||||
```
|
||||
<输入源> → <处理系统> → <输出/通知>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 可调参数汇总
|
||||
|
||||
| 参数 | C++ 属性 | 默认值 | 位置 |
|
||||
|------|---------|--------|------|
|
||||
| <中文参数名> | `<PropertyName>` | <值> | <构造函数/BeginPlay/DataAsset> |
|
||||
|
||||
---
|
||||
|
||||
## 11. 文件结构
|
||||
|
||||
```
|
||||
Source/ChildHood/
|
||||
├── <模块目录>/
|
||||
│ ├── <文件名>.h/.cpp # <说明>
|
||||
│ └── <文件名>.h/.cpp # <说明>
|
||||
└── <其他目录>/
|
||||
└── <文件名>.h/.cpp # <修改说明>
|
||||
|
||||
Content/
|
||||
├── Blueprints/
|
||||
│ └── <蓝图名> # <说明>
|
||||
├── UI/
|
||||
│ └── <Widget名> # <说明>
|
||||
└── Data/
|
||||
└── <DataAsset名> # <说明>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 工期预估与实现拆分
|
||||
|
||||
### 工作量估算
|
||||
|
||||
| 维度 | 估算 |
|
||||
|------|------|
|
||||
| 总工期 | <X-Y 天> |
|
||||
| 新增 C++ 代码 | <XXX-YYY 行> |
|
||||
| 新增蓝图 | <N 个> |
|
||||
| 实现复杂度 | <低/中/高> |
|
||||
|
||||
### 实现拆分建议
|
||||
|
||||
供步骤⑥（程序实现）参考的推荐拆分方式，每个子任务可独立验证：
|
||||
|
||||
| 子任务 | 内容 | 预估时间 | 依赖 | 验证方式 |
|
||||
|--------|------|---------|------|---------|
|
||||
| <子任务名> | <具体内容> | <时间> | <依赖其他子任务> | <如何验证完成> |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 使用说明
|
||||
|
||||
1. **替换所有 `<...>` 占位符**为实际内容
|
||||
2. **条件性章节**（第 4 节时序图、第 6 节复杂接口描述）：根据复杂度判定决定是否包含
|
||||
3. **Mermaid 图表**：在 markdown 渲染器中会自动生成可视化图表
|
||||
4. **保持一一映射**：每条执行文档行为规则都必须在第 6 节有对应实现方案
|
||||
5. **阶段适配**：原型阶段允许简化描述，批量生产阶段需要完整覆盖所有章节
|
||||
Reference in New Issue
Block a user