starmen1265
c3c10a9fcb
- game-reviewer: 删除本地审查记录，仅Issue评论 - quality-gate-review: 删除审查记录/步骤号/阶段标准 - game-dev: 删除阶段感知节，4个工作流详情拆到技能 - game-designer: 删除原型/批量生产阶段，执行案规范拆到技能 - game-pm: 去掉节号和步骤号 - 全局去掉步骤标号（①-⑧/步骤1-5/1.4.X/第一步-第四步） - 新建技能: code-implementation/deviation-report/design-execution - 原型目录扁平化: docs/design/prototype/* → docs/design/ - requirements-analysis及子文件去步骤号和阶段引用 - stage-iteration/sketch/roadmap去任务编号 - 更新所有docs/design/路径引用
377 lines
12 KiB
Markdown
377 lines
12 KiB
Markdown
# 需求分析示例
|
||
|
||
本文档从项目现有技术设计文档中提取注释示例，展示每步分析的实际输出效果。
|
||
|
||
---
|
||
|
||
## 示例来源
|
||
|
||
| 示例 | 来源文档 |
|
||
|------|---------|
|
||
| 交互系统 | `docs/technical/交互系统-技术方案.md` |
|
||
| 角色控制 | `docs/technical/玩家控制器-技术方案.md` |
|
||
| 收集系统 | `docs/technical/收集系统-技术方案.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 变金色 + 弹出完成提示
|
||
```
|
||
|
||
**要点**：
|
||
- 先做前置检查（快速失败）
|
||
- 核心逻辑按顺序执行
|
||
- 异步操作（延迟、动画）明确标注
|
||
- 完成判定/边界情况放在最后
|