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,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 变金色 + 弹出完成提示
|
||||
```
|
||||
|
||||
**要点**：
|
||||
- 先做前置检查（快速失败）
|
||||
- 核心逻辑按顺序执行
|
||||
- 异步操作（延迟、动画）明确标注
|
||||
- 完成判定/边界情况放在最后
|
||||
Reference in New Issue
Block a user