starmen1265/ChildHood
1
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects 2 Releases Wiki Activity

docs(design): v0.1执行案P-002修正——交互/收集/角色控制三系统对齐

Browse Source
This commit is contained in:
DESKTOP-2K5TJI4\admin
2026-06-05 19:06:43 +08:00
parent cdf7f68788
commit 0dfc90cfdf
4 changed files with 601 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/prototype/collection-system-execution.md
+241
View File
@@ -0,0 +1,241 @@
# 收集系统执行案（v0.1 原型）
## 迭代记录
| 迭代版本 | 修改日期 | 状态 | 说明 |
|----------|----------|------|------|
| v0.1.0 | 2026-06-05 | 📝 设计中 | 初版执行案，覆盖 v0.1 基础拾取的完整行为规则 |
| v0.1.1 | 2026-06-05 | 📝 设计中 | 架构重构：收集系统从拾取流程中剥离，仅负责收集进度追踪和收集通知；拾取通知归物品系统；引入「杂物」品类概念 |
> 状态标记：📝 设计中 | 🔄 开发中 | ✅ 已同步
---
## 系统概述
收集系统是游戏的**情感锚点**。它追踪玩家的收集进度，在达成收集里程碑时给予反馈。
v0.1 范围：一个收集品类「杂物」，共 10 个物品。系统接收物品系统的获得通知，判定是否为新收集，更新进度，弹出收集通知。
### 核心设计决定（已确认）
1. **收集系统不感知拾取过程** — 收集系统不关心物品怎么来的（拾取、翻找、购买、奖励……），只从收到物品系统的「获得物品」通知开始工作。
2. **收集通知与拾取通知分离** — 拾取通知（「找到了 XXX」）由物品系统负责，每次获得物品都弹。收集通知（「发现了新的杂物，进度 X/Y」）由收集系统负责，仅在判定为新收集时弹出。
3. **v0.1 单一品类的简单追踪** — 只有一种收集品类「杂物」，无分类、无图鉴、无世界反馈。
### 系统边界
| 收集系统负责 | 收集系统不负责 |
|-------------|---------------|
| 维护收集品类进度（当前数/总数） | 物品如何获得（拾取/翻找/购买） |
| 判定是否为新收集 | 拾取通知 UI（「找到了 XXX」） |
| 弹出收集通知（「发现了新的杂物，进度 X/Y」） | 物品在场景中的位置和表现 |
| 全部收集完成时的特殊表现 | 物品进入背包的流程 |
---
## 依赖关系
### 物品系统（上游）
收集系统依赖物品系统发出的「获得物品」通知。
**通知内容**：
- 物品名称（如「彩色弹珠（蓝色）」）
- 物品所属品类（如「杂物」）
- 物品内部编号
**v0.1 中触发此通知的行为**：
1. 交互系统的「拾取」交互完成时（动画播放到物品消失时间点）
2. 交互系统的「废纸箱翻找」获得结果物品时（翻找动画完成，结果包含物品）
> 后续版本可能有更多触发来源：购买、小游戏奖励、NPC 交换、剧情奖励等。收集系统不需要知道这些来源，只认通知。
---
## 状态定义
| 状态字段 | 类型 | 说明 |
|----------|------|------|
| progress | 整数 | 当前已收集的杂物品数（0-10） |
| collectedIDs | 集合 | 已收集物品的内部编号集合，用于判定新收集 |
| isComplete | 布尔值 | progress 是否达到 10，初始为 false |
### 状态转换
```
初始状态（progress=0, collectedIDs={}, isComplete=false）
│
├──(收到获得物品通知 + 判定为新收集)──→ progress+1, collectedIDs 增加 ID
│ 若 progress=10 → isComplete=true
│
├──(收到获得物品通知 + 判定为非新收集)──→ 状态不变，不弹收集通知
│
└──(游戏重启)──→ 回到初始状态（v0.1 无持久化）
```
---
## 行为规则
### 一、收到获得物品通知后的流程
物品系统发出「获得物品」通知后，收集系统按以下顺序执行：
| 步骤 | 行为 | 说明 |
|------|------|------|
| 1 | 查品类 | 检查通知中的物品品类是否为收集系统追踪的品类。v0.1 只追踪「杂物」，其他品类忽略 |
| 2 | 查重复 | 检查物品内部编号是否已在 collectedIDs 中。若已存在，判定为非新收集，流程结束，不弹收集通知 |
| 3 | 记录 | 将物品内部编号加入 collectedIDs，progress +1 |
| 4 | 弹收集通知 | 显示收集通知 UI（见下文） |
| 5 | 完成判定 | 若 progress 达到 10，将 isComplete 置为 true，触发完成表现 |
### 二、收集通知 UI
#### 显示规则
- **触发条件**：步骤 4（判定为新收集时）
- **触发时机**：物品系统的拾取通知（「找到了 XXX」）弹出后 0.3 秒（建议值，可调，范围 0.1-0.5 秒），避免与拾取通知视觉重叠
- **位置**：屏幕右上角，在拾取通知下方。若当前无拾取通知显示，则在拾取通知的默认位置显示
- **内容**：`发现了新的杂物，进度 <当前>/<总数>`（例：`发现了新的杂物，进度 3/10`）
- **颜色**：文字为浅金色（与拾取通知的白色区分），建议色值 #F0D060（可调）
- **大小**：与拾取通知文字大小一致
#### 显示动画
| 阶段 | 行为 | 时长 |
|------|------|------|
| 淡入 | 通知从透明渐变到不透明 | 0.2 秒（建议值，可调，范围 0.1-0.3 秒） |
| 停留 | 保持完全显示 | 2.0 秒（建议值，可调，范围 1.5-3.0 秒） |
| 淡出 | 通知从不透明渐变到透明，完全透明后移除 | 0.3 秒（建议值，可调，范围 0.2-0.5 秒） |
#### 与拾取通知的叠放
- 收集通知始终在拾取通知下方
- 若短时间内连续触发多条收集通知（v0.1 不会发生，但架构上支持），新通知从上一条下方弹出
- 最大同屏收集通知数：2 条
### 三、收集进度 UI
#### 显示规则
- **位置**：屏幕左上角，距左边距 3%屏幕宽度（建议值，可调，范围 2%-5%），距上边距 3%屏幕高度（建议值，可调，范围 2%-5%）
- **格式**：`<品类图标> <品类名> <当前数>/<总数>`（例：`📦 杂物 3/10`）
- **图标**：白盒阶段用简单符号或纯色方块，尺寸约 20×20 像素（建议值，可调）
- **文字**：白色文字，正常字体大小
- **常驻显示**：游戏开始后始终可见
#### 数值更新动画
- progress 数字变化时有一个轻微的放大-缩小弹性效果（缩放到 1.2 倍再回到 1.0 倍，时长 0.2 秒，建议值，可调，范围 0.1-0.4 秒）
### 四、全部收集完成表现
- 当 progress 达到 10（isComplete 变为 true）时：
- 收集进度 UI 的数字变更为金色，并播放一次放大弹性效果（1.4 倍缩放，时长 0.5 秒，建议值，可调，范围 0.3-0.8 秒）
- 在最后一条收集通知消失后 0.5 秒（建议值，可调，范围 0.3-1.0 秒），屏幕中央弹出完成提示文字：「杂物全部收集完成！」，白色大字，显示 2.0 秒（建议值，可调，范围 1.5-3.0 秒）后淡出
- 无其他特殊效果（过场动画、NPC 反应等留给后续版本）
---
## v0.1 杂物品类清单
以下 10 个物品归属于「杂物」品类。物品在场景中的位置、交互表现由交互系统定义，收集系统仅关心物品名称和品类归属。
| # | 物品名称 | 稀有度 | 获取方式（通知来源） |
|---|----------|--------|-------------------|
| 1 | 彩色弹珠（蓝色） | 普通 | 场景拾取 |
| 2 | 彩色弹珠（红色花纹） | 普通 | 场景拾取 |
| 3 | 小石子 | 普通 | 场景拾取 |
| 4 | 水浒卡（鲁智深） | 稀有 | 场景拾取 |
| 5 | 糖纸（大白兔） | 普通 | 场景拾取 |
| 6 | 香味橡皮擦 | 普通 | 场景拾取 |
| 7 | 水浒卡（武松） | 稀有 | 废纸箱翻找 |
| 8 | 弹珠（透明冰花） | 普通 | 场景拾取 |
| 9 | 小弹力球 | 普通 | 场景拾取 |
| 10 | 玻璃弹珠（猫眼） | 稀有 | 场景拾取 |
> 稀有度影响物品系统拾取通知的图标颜色（普通=白色，稀有=金色），不影响收集系统的行为。收集系统对所有物品一视同仁。
---
## 边界情况处理
### 重复获得同一物品
- 若物品系统对同一物品发出多次获得通知（理论上 v0.1 不应发生，因拾取物为 oneShot）→ 收集系统在步骤 2 查重复时判定为非新收集，不增加 progress，不弹收集通知
- 不会出现进度超过 10 的情况
### 全部收集完成
- 见「全部收集完成表现」章节
- 完成后继续收到新通知（不会发生）：查重复判定拦截，无副作用
### 重启状态处理
- v0.1 不实现存档，每次启动游戏收集状态完全重置
- 重置内容：progress 归零、collectedIDs 清空、isComplete 置为 false
- 收集进度 UI 恢复显示 `杂物 0/10`
### 收集通知与拾取通知时序
- 收集通知在拾取通知弹出后延迟 0.3 秒弹出
- 若拾取通知已消失（停留时间已过），收集通知在原拾取通知位置显示
- 两条通知不会完全重叠，有时间差和位置差
---
## 跨系统交互
### 与物品系统的关系（上游）
- **单向接收通知**：收集系统被动接收物品系统的「获得物品」通知，不主动请求
- **通知内容**：物品名称、物品品类、物品内部编号
- **无反向通信**：收集系统不向物品系统发送任何信息
### 与交互系统的关系（间接）
- 收集系统与交互系统**无直接通信**
- 交互系统的拾取交互 → 触发物品系统发出通知 → 收集系统收到通知
- 交互系统的废纸箱翻找获得物品 → 触发物品系统发出通知 → 收集系统收到通知
- 收集系统不知道物品来自交互系统
### 与 UI 系统的关系
- **收集通知 UI**：由收集系统控制显示内容、弹出位置、动画时序
- **收集进度 UI**：由收集系统控制显示位置、数值更新、完成变色效果
- **拾取通知 UI**：由物品系统控制，收集系统不干涉
---
## v0.1 不实现清单
| 功能 | 排除原因 |
|------|----------|
| 多品类收集（弹珠、卡片、糖纸等） | v0.1 统一归为「杂物」 |
| 收集图鉴 UI | 后续版本 |
| 收集品分类和稀有度系统 | 后续版本 |
| 世界反馈（NPC 讨论收集、称号） | 后续版本 |
| 收集完成触发的支线剧情 | 后续版本 |
| 收集进度持久化 | v0.1 无存档 |
---
## 可调参数汇总
| 参数 | 建议值 | 可调范围 | 说明 |
|------|--------|----------|------|
| 收集通知延迟 | 0.3 秒 | 0.1-0.5 秒 | 拾取通知弹出后到收集通知弹出的间隔 |
| 收集通知淡入时长 | 0.2 秒 | 0.1-0.3 秒 | |
| 收集通知停留时长 | 2.0 秒 | 1.5-3.0 秒 | |
| 收集通知淡出时长 | 0.3 秒 | 0.2-0.5 秒 | |
| 收集通知文字颜色 | #F0D060 | — | 浅金色，与拾取通知白色区分 |
| 最大同屏收集通知数 | 2 条 | 1-3 条 | |
| 进度 UI 距左边距 | 3% 屏幕宽度 | 2%-5% | |
| 进度 UI 距上边距 | 3% 屏幕高度 | 2%-5% | |
| 进度数字弹性缩放 | 1.2 倍 | 1.1-1.5 倍 | 单次新收集时 |
| 进度数字弹性时长 | 0.2 秒 | 0.1-0.4 秒 | 单次新收集时 |
| 完成金色缩放倍率 | 1.4 倍 | 1.2-1.8 倍 | 全部收集完成时 |
| 完成金色缩放时长 | 0.5 秒 | 0.3-0.8 秒 | 全部收集完成时 |
| 完成提示延迟 | 0.5 秒 | 0.3-1.0 秒 | 收集通知消失后到完成提示弹出的间隔 |
| 完成提示显示时长 | 2.0 秒 | 1.5-3.0 秒 | 「杂物全部收集完成！」文字 |
docs/design/prototype/interaction-system-execution.md
+88 -67
View File
@@ -1,16 +1,14 @@
# 交互系统执行案（v0.1 原型）
> 最后更新：2026-06-05
> 状态：待程序评审
---
## 迭代记录
| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| v0.1.0 | 2026-06-05 | 初版执行案，覆盖四类交互的完整行为规则 | 策划 Agent |
| v0.1.1 | 2026-06-05 | 重构状态模型为层级状态（Free/Interacting/SubSystem/Cutscene），Detecting 降为 Free 检测标记，AnimLock 降为 Interacting 子阶段，新增 postAction 分叉机制 | 策划 Agent |
| v0.1.1 | 2026-06-05 | 重构状态模型为层级状态，Detecting 降为 Free 检测标记，AnimLock 降为 Interacting 子阶段，新增 postAction 分叉机制 | 策划 Agent |
| v0.1.2 | 2026-06-05 | 废纸箱改为单次翻找；UI 统一为半透明底框+一句话（去掉打字机效果）；叙事视角改为小孩当下视角（去掉成人回顾）；对话类只显示对话内容；拾取物通用外观；跨系统交互改为物品系统 | 策划 Agent |
> 状态标记：📝 设计中 | 🔄 开发中 | ✅ 已同步
---
@@ -23,6 +21,8 @@
1. **交互中断行为：输入锁定** — 交互进行中，移动输入被忽略，玩家必须按 E 或 ESC 主动关闭交互后才能恢复自由移动。
2. **多交互物重叠：自动最近 + 按键切换** — 默认显示最近的交互物提示，按 Tab 或鼠标滚轮切换到范围内下一个可交互物。
3. **动画期间输入：全程锁定** — 任何交互动画播放期间忽略所有按键输入，动画必须自然播完才接受新输入。
4. **叙事视角：小孩当下** — 玩家就是小孩，所有文本只有小孩当下的想法或客观描述，没有成人回顾式的"现在想起来"。
5. **文本 UI 统一** — 观察类、对话类、翻找无结果的文本显示，统一使用屏幕中间半透明小底框 + 一句话，无打字机效果。
---
@@ -140,7 +140,7 @@ v0.1 所有交互的 postAction 均为 return。
- 玩家在 Free 状态下（检测标记为 true 时）按 E 键 → 触发当前选中交互物的交互
- 触发后系统进入 Interacting 状态
- Interacting 状态下：
- 移动输入（WASD、方向键、摇杆）被忽略，角色不移动
- 移动输入（WASD、方向键）被忽略，角色不移动
- Tab 键、鼠标滚轮被忽略，不切换交互物
- E 键和 ESC 键的行为取决于具体交互类型（见下文）
@@ -148,13 +148,24 @@ v0.1 所有交互的 postAction 均为 return。
- 交互结束后系统回到 Free 状态（v0.1 所有交互的 postAction 均为 return）
- 若角色仍在某交互物的触发范围内，回到 Free 状态的同时检测标记激活，立即显示提示 UI
- 若角色已不在任何交互物触发范围内（交互中角色不移动，仅因 oneShot 交互物被消耗导致范围内无交互物），回到 Free 状态且检测标记为 false
- 若角色已不在任何交互物触发范围内（仅因 oneShot 交互物被消耗导致），回到 Free 状态且检测标记为 false
#### 通用文本显示 UI
观察类、对话类、翻找无结果的文本显示，统一使用以下 UI 格式：
- **位置**：屏幕正中偏下（距屏幕中心向下偏移约 10%屏幕高度，建议值，可调，范围 5%-20%）
- **底框**：半透明黑色背景（透明度 60%，可调，范围 40%-80%），圆角矩形，宽度按文字内容自适应（左右各留边距 20 像素，建议值，可调），高度按文字行数自适应
- **文字**：白色，正常字体大小，居中对齐
- **显示方式**：整句一次性显示，无打字机效果
- **淡入**：0.2 秒（建议值，可调，范围 0.1-0.3 秒）
- **淡出**：0.2 秒（建议值，可调，范围 0.1-0.3 秒）
---
### 交互类型一：观察（Examine）
**用途**：查看物品或场景，触发主角的内心独白。
**用途**：查看物品或场景，触发小孩当下的想法。
#### 触发条件
- 通用触发条件满足
@@ -167,19 +178,15 @@ v0.1 所有交互的 postAction 均为 return。
| 1. 转向 | 0 秒 | 角色自动转向交互物（面朝交互物方向），转向时长 0.2 秒（建议值，可调，范围 0.1-0.4 秒） |
| 2. 推镜 | 0 秒（与转向同时开始） | 相机从当前第三人称位置平滑推向交互物前方约 0.8-1.0m（建议值，可调，范围 0.5-2.0m），高度略低于交互物中心（微仰视），推镜时长 0.5 秒（建议值，可调，范围 0.3-1.0 秒），ease-out 缓动 |
| 3. 等待 | 推镜结束后 0.2 秒 | 无动作，间隔等待 |
| 4. 文本显示 | 等待结束后 | 屏幕底部浮现内心独白文本框，半透明黑色背景（透明度 60%，可调，范围 40%-80%），白色文字，打字机效果逐字显示（每字间隔 0.05 秒，可调，范围 0.03-0.08 秒；一个汉字为一个单位） |
| 5. 用户控制 | 文本全部显示完毕后 | 玩家可按 E 或 ESC 关闭文本框 |
| 4. 文本显示 | 等待结束后 | 屏幕中间半透明底框显示一句话（小孩当下的想法），使用通用文本显示 UI，进入 Active 子阶段 |
| 5. 用户控制 | 文本显示完毕后 | 玩家可按 E 或 ESC 关闭 |
#### 关闭行为
- 玩家按 E 或 ESC → 文本框淡出（0.2 秒，可调，范围 0.1-0.5 秒）→ 相机从推镜位置回到默认第三人称位置（0.3 秒，可调，范围 0.2-0.5 秒，ease-in 缓动）→ 进入 Exit 子阶段 → 回到 Free 状态
#### 文本显示期间的按键行为
- 文本仍在打字机效果中（未全部显示）时：E 键和 ESC 键被忽略（Interacting 的 AnimLock 子阶段）
- 文本全部显示后：E 键和 ESC 键可触发关闭（Interacting 的 Active 子阶段）
- 玩家按 E 或 ESC → 底框淡出（0.2 秒）→ 相机从推镜位置回到默认第三人称位置（0.3 秒，可调，范围 0.2-0.5 秒，ease-in 缓动）→ 进入 Exit 子阶段 → 回到 Free 状态
#### 可重复交互
- oneShot 为 false 的观察类交互物可反复交互
- 每次触发的叙事文本从该交互物的文本列表中随机选取（不重复上一次的内容；若文本列表只有一条则每次显示同一条）
- 每次触发的文本从该交互物的文本列表中随机选取（不重复上一次的内容；若文本列表只有一条则每次显示同一条）
---
@@ -192,6 +199,11 @@ v0.1 所有交互的 postAction 均为 return。
- 交互物类型为 pickup
- 该交互物未被拾取（oneShot 且已触发过则不再响应）
#### 拾取物外观
- v0.1 白盒阶段所有拾取物使用**同一通用模型**（建议：简单球形或方块，尺寸约 0.1m 直径/边长）
- 通过颜色区分稀有度：普通=白色，稀有=金色
- 不需要为每个拾取物制作独立模型
#### 触发后行为（按时间顺序）
| 阶段 | 时间点 | 行为 |
@@ -199,9 +211,8 @@ v0.1 所有交互的 postAction 均为 return。
| 1. 转向 | 0 秒 | 角色自动转向交互物方向，转向时长 0.2 秒（建议值，可调，范围 0.1-0.4 秒） |
| 2. 动画 | 转向完成后 | 角色播放弯腰拾取动画（总时长约 1.0 秒，建议值，可调，范围 0.8-1.5 秒），进入 Interacting 的 AnimLock 子阶段 |
| 3. 物品消失 | 动画播放至"手触碰物品"时间点（约为动画总时长的 60% 位置，可调，范围 50%-70%） | 交互物从场景中消失 |
| 4. 提示弹出 | 物品消失后 0.1 秒 | 屏幕右上角弹出物品获得提示（物品图标 + 物品名称），提示显示 1.5 秒（可调，范围 1.0-3.0 秒）后自动淡出 |
| 5. 计数更新 | 物品消失同时 | 该类型的收集计数 +1 |
| 6. 自动结束 | 动画自然播完 | 系统回到 Free 状态 |
| 4. 通知物品系统 | 物品消失同时 | 交互系统通知物品系统「<物品名称>（品类：杂物，编号：XXX）已被拾取」。后续的拾取通知（"找到了 XXX"）和收集通知由物品系统和收集系统分别处理 |
| 5. 自动结束 | 动画自然播完 | 系统回到 Free 状态 |
#### 关闭行为
- 拾取交互不支持手动关闭，必须等待动画自然播完
@@ -212,7 +223,7 @@ v0.1 所有交互的 postAction 均为 return。
#### 一次性消耗
- 拾取类交互物均为 oneShot，拾取后永久消失
- 消失后该交互物的触发范围不再生效，角色走过原位置不会触发提示
- 消失后该交互物的触发范围不再生效
---
@@ -257,22 +268,29 @@ v0.1 包含两种操作子类型，行为规则分别定义。
| 1. 转向 | 0 秒 | 角色自动转向纸箱方向，转向时长 0.2 秒（建议值，可调） |
| 2. 推镜 | 0 秒（与转向同时） | 相机推向纸箱前方约 0.6m（建议值，可调，范围 0.4-1.0m），推镜时长 0.5 秒（可调，范围 0.3-1.0 秒），ease-out 缓动 |
| 3. 动画 | 转向完成后 | 角色播放弯腰翻找动画（总时长约 1.5 秒，可调，范围 1.0-2.0 秒），进入 Interacting 的 AnimLock 子阶段 |
| 4. 结果显示 | 动画自然播完后 | 屏幕底部弹出翻找结果文本（与观察类文本框样式相同），内容从该纸箱的结果列表中按顺序显示（首次翻找显示第一条，第二次显示第二条，依此类推；列表显示完毕后显示"什么都没有了"） |
| 5. 用户控制 | 文本全部显示后 | 玩家按 E 或 ESC 关闭文本框 |
| 4. 结果判定 | 动画自然播完后 | 根据纸箱是否有物品，走不同分支（见下文） |
##### 关闭行为
- 文本显示完毕后按 E 或 ESC → 文本淡出（0.2 秒）→ 相机回到默认第三人称位置（0.3 秒）→ 回到 Free 状态
##### 有物品分支
- 纸箱内有物品时（v0.1 的废纸箱必定包含「水浒卡（武松）」）：
- 交互系统通知物品系统「<物品名称>（品类：杂物，编号：XXX）已获得」
- 物品系统弹出拾取通知「找到了 水浒卡（武松）」，收集系统弹出收集通知
- 无文本底框显示
- 玩家按 E 或 ESC → 相机回位（0.3 秒）→ 回到 Free 状态
##### 可重复交互
- 纸箱可反复翻找，直到结果列表显示完毕
- 结果列表显示完毕后，再次翻找始终显示"什么都没有了"
- 如果翻找结果中包含拾取品，在该条结果显示的同时执行拾取逻辑（计数 +1、物品获得提示弹出）
##### 无物品分支
- 纸箱内无物品时（v0.1 废纸箱必定有物品，此分支为架构预留）：
- 屏幕中间显示通用文本底框：`什么都没找到。`
- 玩家按 E 或 ESC → 底框淡出 → 相机回位 → 回到 Free 状态
##### 一次性交互
- 废纸箱为 oneShot 交互物：翻找一次后不可再翻找
- 翻找后纸箱不消失（视觉仍在场景中），但不再显示交互提示
---
### 交互类型四：对话（Talk）— v0.1 简化版
**用途**：与场景中的 NPC 交谈。v0.1 为简化实现，NPC 视为"会说话的观察对象"。
**用途**：与场景中的 NPC 交谈。v0.1 为简化实现，只显示 NPC 的对话或状态表现。
#### 触发条件
- 通用触发条件满足
@@ -280,13 +298,19 @@ v0.1 包含两种操作子类型，行为规则分别定义。
#### 触发后行为
与观察类型（Examine）完全一致，唯一区别：叙事文本为场景描述而非内心独白。
| 阶段 | 时间 | 行为 |
|------|------|------|
| 1. 转向 | 0 秒 | 角色自动转向 NPC 方向，转向时长 0.2 秒（建议值，可调） |
| 2. 推镜 | 0 秒（与转向同时） | 相机推向 NPC 前方约 0.8-1.0m（建议值，可调），推镜时长 0.5 秒（可调） |
| 3. 文本显示 | 推镜结束后 0.2 秒 | 屏幕中间半透明底框显示 NPC 的对话内容（仅对话文本，无旁白描述），使用通用文本显示 UI |
| 4. 用户控制 | 文本显示后 | 玩家按 E 或 ESC 关闭 |
- 相机推向 NPC → 底部浮现场景描述文本 → 按 E/ESC 关闭 → 相机回位
#### 关闭行为
- 按 E 或 ESC → 底框淡出 → 相机回位 → 回到 Free 状态
#### 可重复交互
- NPC 可反复交谈
- 每次触发的场景描述文本从该 NPC 的文本列表中随机选取（不重复上一次；列表只有一条则每次相同）
- 每次触发的对话文本从该 NPC 的文本列表中随机选取（不重复上一次；列表只有一条则每次相同）
---
@@ -332,15 +356,18 @@ v0.1 包含两种操作子类型，行为规则分别定义。
- 交互结束后，角色控制系统恢复正常输入响应
- 角色面朝方向的自动转向由交互系统控制，不由角色控制系统控制
### 与收集系统的关系
- 拾取类交互触发后，交互系统通知收集系统"物品 ID +1"
- 收集系统负责维护收集计数和物品获得提示 UI
- 纸箱翻找结果中包含拾取品时，同样通知收集系统
### 与物品系统的关系
- 拾取类交互触发后，交互系统在拾取动画执行到「物品消失」时间点时，通知物品系统「<物品名称>（品类：杂物，编号：XXX）已被拾取」
- 废纸箱翻找获得物品时，同样通知物品系统
- 物品系统负责：物品进入背包、弹出拾取通知（"找到了 XXX"）
- 收集系统从物品系统接收通知，弹出收集通知（"发现了新的杂物，进度 X/Y"）
- 交互系统不直接与收集系统通信
### 与 UI 系统的关系
- 交互提示 UI 由交互系统控制显示/隐藏/切换
- 叙事文本 UI 由交互系统控制显示/内容/关闭
- 物品获得提示 UI 由收集系统控制（不在交互系统执行案范围内）
- 交互提示 UI（`[E] 查看旧冰箱`）由交互系统控制显示/隐藏/切换
- 文本底框（观察想法、对话内容、翻找无结果）由交互系统控制显示/关闭
- 拾取通知（"找到了 XXX"）由物品系统控制，不在交互系统执行案范围内
- 收集通知（"发现了新的杂物"）由收集系统控制，不在交互系统执行案范围内
---
@@ -352,13 +379,13 @@ v0.1 包含两种操作子类型，行为规则分别定义。
| # | 物体名 | 交互类型 | 区域 | 验证目标 |
|---|--------|----------|------|----------|
| 1 | 旧冰箱 | 观察 | 家 | 室内大件观察，推镜 + 内心独白 |
| 1 | 旧冰箱 | 观察 | 家 | 室内大件观察，推镜 + 小孩想法 |
| 2 | 家的门 | 操作（门） | 家 | 门开关状态切换 |
| 3 | 散落的弹珠 | 拾取 | 空地 | 拾取完整流程 |
| 3 | 拾取物（通用） | 拾取 | 空地 | 拾取完整流程，通知物品系统 |
| 4 | 公用电话亭 | 观察 | 街道 | 室外独立物体观察 |
| 5 | 小卖部老板 | 对话（简化） | 小卖部 | NPC 交互 |
**探索路线**：家（冰箱 → 门）→ 街道（电话亭）→ 小卖部（老板）→ 空地（弹珠）
**探索路线**：家（冰箱 → 门）→ 街道（电话亭）→ 小卖部（老板）→ 空地（拾取物）
### 第二轮：体验填充（5 个）
@@ -368,7 +395,7 @@ v0.1 包含两种操作子类型，行为规则分别定义。
|---|--------|----------|------|------------|
| 6 | 老式电视 | 观察 | 家 | 同区域第二件观察物 |
| 7 | 零食货架 | 观察 | 小卖部 | 矮物体推镜角度 |
| 8 | 水浒卡碎片 | 拾取 | 空地 | 第二个拾取品 |
| 8 | 拾取物（通用） | 拾取 | 空地 | 第二个拾取品 |
| 9 | 墙上的涂鸦 | 观察 | 街道 | 墙面类物体 |
| 10 | 废纸箱 | 操作（翻找） | 巷子 | 第二种操作类型 |
@@ -384,55 +411,49 @@ v0.1 包含两种操作子类型，行为规则分别定义。
| 角色转向时长 | 0.2 秒 | 0.1-0.4 秒 | |
| 推镜距离（观察类） | 0.8-1.0m | 0.5-2.0m | 根据交互物体型调整 |
| 推镜距离（翻找类） | 0.6m | 0.4-1.0m | |
| 推镜距离（对话类） | 0.8-1.0m | 0.5-2.0m | |
| 推镜时长 | 0.5 秒 | 0.3-1.0 秒 | |
| 推镜后等待 | 0.2 秒 | 0.1-0.5 秒 | 推镜结束到文本开始显示的间隔 |
| 相机回位时长 | 0.3 秒 | 0.2-0.5 秒 | |
| 文本背景透明度 | 60% | 40%-80% | |
| 打字机每字间隔 | 0.05 秒 | 0.03-0.08 秒 | 一个汉字为一个单位 |
| 文本淡出时长 | 0.2 秒 | 0.1-0.5 秒 | |
| 文本底框背景透明度 | 60% | 40%-80% | |
| 文本底框淡入时长 | 0.2 秒 | 0.1-0.3 秒 | |
| 文本底框淡出时长 | 0.2 秒 | 0.1-0.3 秒 | |
| 拾取动画总时长 | 1.0 秒 | 0.8-1.5 秒 | |
| 物品消失时间点（动画进度） | 60% | 50%-70% | 动画播放到此比例时物品消失 |
| 物品获得提示显示时长 | 1.5 秒 | 1.0-3.0 秒 | |
| 门操作动画时长 | 0.8 秒 | 0.5-1.2 秒 | |
| 门状态切换时间点（动画进度） | 40% | 30%-50% | |
| 翻找动画时长 | 1.5 秒 | 1.0-2.0 秒 | |
---
## 叙事文本示例
## 文本示例
> 所有文本均为小孩当下的想法或客观描述，没有成人回顾视角。
### 观察类
**旧冰箱**：
> 夏天的时候最期待打开冰箱的那一刻。
> 冰棒、西瓜、偶尔还有一瓶健力宝。
> 现在想起来，那个冰箱的嗡嗡声好像还在耳边。
> 冰箱嗡嗡响。里面有冰棒，还有一瓶健力宝！
**公用电话亭**：
> 街角的公用电话亭，玻璃上贴满了小广告。
> 以前打个电话要排半天队，现在好像没人用了。
> 玻璃上全是小广告。投币口好像卡住了。
**老式电视**：
> 家里的大脑袋电视，拍两下就能出画面。
> 有时候信号不好，得去转天线。
> 拍两下就有画面了。今天信号不太好。
**零食货架**：
> 货架上摆满了五毛钱的零食。
> 辣条、干脆面、还有那种一毛钱两颗的糖。
> 五毛钱的辣条！还有干脆面和泡泡糖。
**墙上的涂鸦**：
> 不知道是谁画的，但画得还挺像奥特曼的。
> 我以前也想在墙上画，被我妈追着打了半条街。
> 谁画的奥特曼？画得还挺像的。
### 对话类（简化）
**小卖部老板**：
> 老板正在柜台后面打瞌睡，电视里放着还珠格格。
> zzz
### 翻找结果类
### 翻找结果
**废纸箱**（按顺序显示）：
1. > 翻了半天，找到了一张皱巴巴的纸条：上面写着"小明是笨蛋"。
2. > 纸箱底下一堆旧报纸，翻到一张去年的电视报。
3. > 摸到一个硬硬的东西……是一颗弹珠！（触发拾取：弹珠 +1）
4. > 什么都没有了。
**废纸箱**（v0.1 必定获得物品，走物品系统通知，不显示文本底框）。
无物品时预留文本：
> 什么都没找到。
docs/design/prototype/player-controller-execution.md
+240
View File
@@ -0,0 +1,240 @@
# 角色控制执行案（v0.1 原型）
## 迭代记录
| 迭代版本 | 修改日期 | 状态 | 说明 |
|----------|----------|------|------|
| v0.1.0 | 2026-06-05 | 📝 设计中 | 初版执行案，覆盖 v0.1 角色移动、摄像机、跑步的完整行为规则 |
| v0.1.1 | 2026-06-05 | 📝 设计中 | 移除步行状态，仅保留跑步；修正摄像机与角色转身行为描述 |
> 状态标记：📝 设计中 | 🔄 开发中 | ✅ 已同步
---
## 系统概述
角色控制系统让玩家操控主角在千禧年城郊场景中自由移动。v0.1 原型实现：第三人称摄像机跟随、WASD 移动（跑步速度）、鼠标控制视角。
### 核心设计决定（已确认）
1. **移动方向相对摄像机** — WASD/方向键的移动方向以当前摄像机朝向为基准。W 永远是摄像机看的方向，角色转身朝移动方向跑。因为角色转向速度远快于摄像机旋转速度，跑动中摄像机永远追不到角色正面——玩家始终看到角色背影。
2. **仅跑步，无步行** — v0.1 只有一种移动速度（跑步速度），不需要 Shift 键切换。按移动键就是跑，松开就是停。
3. **不实现蹲下和跳跃** — v0.1 场景设计保证所有区域跑步可达。
---
## 状态定义
角色控制系统维护两个状态：
| 状态 | 说明 |
|------|------|
| Idle | 静止站立，不接收移动输入或所有方向键已松开 |
| Running | 跑步中，速度 4.5 m/s（建议值，可调，范围 3.5-6.0 m/s） |
### 状态转换
```
Idle ──(按下移动键)──→ Running
Running ──(松开所有移动键)──→ Idle
```
> 交互进行中（交互系统处于 Interacting 状态）时，角色控制系统忽略所有移动输入，状态冻结为 Idle。
---
## 行为规则
### 一、摄像机系统
#### 默认位置
- **距离**：摄像机距角色约 3.5m（建议值，可调，范围 2.5-5.0m），沿摄像机当前偏航角的反方向偏移（即摄像机看的方向的反方向）
- **高度**：摄像机位于角色头部上方约 0.8m（建议值，可调，范围 0.5-1.2m），相对角色位置
- **俯角**：摄像机略微向下看向角色，约 15° 俯角（建议值，可调，范围 10°-25°）
- **效果**：能看到角色全身及周围 2-3m 的环境
#### 跟随规则
- **跟随目标**：角色脚底中心点
- **跟随方式**：软跟随，摄像机位置以一定延迟追踪角色位置，始终保持当前偏航角和俯角
- **跟随速度**：摄像机从当前位置平滑移动到目标位置，速度为角色移动速度的 3-5 倍（建议值，可调，范围 2-8 倍）
- **效果**：角色移动时摄像机不会 1:1 同步，有轻微的"拖拽感"，让画面更柔和自然
#### 视角旋转（鼠标）
- **水平旋转**：鼠标左右移动 → 摄像机围绕角色水平旋转（偏航角），旋转速度约 150°/秒（建议值，可调，范围 90°-300°/秒）
- **垂直旋转**：鼠标上下移动 → 摄像机围绕角色垂直旋转（俯仰角）
- **上限**：最高可到水平线以上约 45°（建议值，可调，范围 30°-60°），不能再往上看到天空正上方
- **下限**：最低可到水平线以下约 30°（建议值，可调，范围 20°-45°），不能再往下看到地面以下
- **旋转范围**：水平方向无限制（可 360° 连续旋转），垂直方向限制在上下限之间
#### 摄像机与角色移动的关系
摄像机角度决定移动方向，角色转向移动方向，二者形成以下行为：
- **站定时**：摄像机可自由旋转到任何角度（包括角色正面），角色面朝方向不变
- **跑动中**：角色转向速度（720°/秒）远快于摄像机旋转速度（150°/秒），因此角色始终比摄像机"先转到位"。玩家在跑动中旋转摄像机，角色的移动方向会跟着变（跑出弧线），但摄像机永远追不到角色正面——玩家始终看到角色背影
- **站定后转到正面再按 W**：角色转身背对摄像机，朝摄像机看的方向跑。摄像机跟随角色前进，玩家看到的是角色背影
#### 摄像机碰撞处理
- **碰撞规则**：当摄像机目标位置与场景几何体（墙壁、柱子等）重叠时，摄像机自动向前拉近，紧贴碰撞面内侧
- **最小距离**：摄像机距角色最近不低于 0.5m（建议值，可调，范围 0.3-1.0m），防止摄像机穿入角色身体内部
- **恢复**：碰撞消除后（角色离开墙壁等），摄像机以软跟随速度平滑回到默认距离位置
- **v0.1 简化**：仅处理摄像机与静态场景几何体的碰撞，不处理与动态物体的碰撞
---
### 二、移动系统
#### 移动方向
- **输入源**：WASD 键或方向键
- **方向基准**：当前摄像机的水平朝向（偏航角）
- W / ↑ = 摄像机看的方向（前方）
- S / ↓ = 摄像机看的反方向（后方）
- A / ← = 摄像机看的方向的左侧
- D / → = 摄像机看的方向的右侧
- **对角移动**：同时按两个方向键（如 W+A）时，移动方向为两个方向的合成方向（45° 斜向），速度不叠加（斜向移动速度与正向相同）
- **连续旋转中移动**：跑动中旋转摄像机，移动方向实时跟随摄像机朝向变化，角色平滑转向新的移动方向，跑出弧线轨迹
#### 角色转向
- 角色静止（Idle）时，面朝方向不变，不随摄像机旋转而转身
- 角色移动（Running）时，角色面朝方向平滑转向移动方向：
- 转向速度约 720°/秒（建议值，可调，范围 360°-1080°/秒），远快于摄像机旋转速度（150°/秒）
- 转向采用最短路径旋转（不超过 180° 的方向选择较短弧线旋转）
- 转向期间角色持续移动（不"停顿再转向"，而是"边跑边转"）
- **结果**：跑动中玩家始终看到角色背影，摄像机追不到角色正面
#### 跑步
- **触发**：按下任意移动键（WASD/方向键）
- **速度**：4.5 m/s（建议值，可调，范围 3.5-6.0 m/s）
- **起步**：从静止到跑步的加速时间约 0.2 秒（建议值，可调，范围 0.1-0.4 秒），不是瞬间达到全速
- **动画**：v0.1 使用简单的占位跑步动画（若有）；若无动画资源，角色在地面滑动也可接受
#### 停止与减速
- **松开所有移动键**：角色从跑步速度减速到静止，减速时间约 0.3 秒（建议值，可调，范围 0.2-0.5 秒）
- **效果**：角色不会突然"钉"在地上，而是有自然的减速感
#### 坡道与台阶
- **可通行坡度**：角色可沿坡度 ≤ 45°（建议值，可调，范围 30°-60°）的斜面向上/下移动
- **超出坡度**：角色无法攀爬超过最大坡度的斜面，在坡面底部停止移动（不滑落）
- **台阶**：v0.1 场景中台阶高度不超过 0.15m（建议值，可调，范围 0.1-0.3m）时角色可直接跑上去，无需跳跃
- **v0.1 简化**：场景设计应避免需要跳跃或复杂攀爬的地形，所有可达区域通过跑步即可到达
---
### 三、输入映射
#### 键鼠操作
| 操作 | 按键 | 说明 |
|------|------|------|
| 移动（跑步） | WASD / 方向键 | 方向相对摄像机朝向，按住就跑 |
| 视角旋转 | 鼠标移动 | 水平无限制，垂直有上下限 |
| 交互 | E | 委托交互系统处理 |
| 取消/返回 | ESC | 委托交互系统处理 |
| 切换交互物 | Tab / 鼠标滚轮 | 委托交互系统处理 |
#### 输入优先级
- 交互系统处于 Interacting 状态时 → 移动键（WASD/方向键）的输入被忽略
- 交互系统处于 Free 状态时 → 所有输入正常响应
- 视角旋转（鼠标）不受交互状态影响，交互进行中仍可旋转视角（但摄像机可能被交互系统的推镜行为覆盖，见交互系统执行案）
---
## 边界情况处理
### 角色碰撞场景边界
- 场景边缘用物理碰撞体阻挡（围墙、建筑外墙、水塘碰撞面等）
- 角色跑到碰撞体时停止移动，不穿墙、不掉出场景
- 碰撞时角色保持 Idle 或贴墙滑行（沿碰撞面方向的分量仍可移动）
### 摄像机穿墙
- 摄像机碰撞处理见「摄像机碰撞处理」章节
- 若角色背靠墙壁（摄像机默认位置在墙内）→ 摄像机拉近到角色前方 0.5m 处
- 若角色在狭窄空间中（前后都有墙）→ 摄像机拉到最近的开放空间一侧
### 同时按多个方向键
- W+S 同时按：W 和 S 互为反向，抵消后角色不移动（或取最后按下的键方向，不叠加）
- W+A 同时按：按对角线方向移动，速度与正向相同
- W+A+S 同时按：W 与 S 抵消，仅 A 方向生效，角色向左移动
- 三个以上方向键同时按：遵循"对向抵消"规则
### 角色在交互中
- 交互系统进入 Interacting 状态 → 角色控制系统忽略所有移动输入
- 交互系统回到 Free 状态 → 角色控制系统恢复正常输入响应
- 交互期间摄像机由交互系统控制（推镜/回位），角色控制系统不更新摄像机位置
- 交互结束后摄像机回到角色控制系统的默认跟随位置（以角色当前位置为基准）
### 鼠标灵敏度极端值
- 鼠标灵敏度由引擎输入设置控制，不通过角色控制系统配置
- v0.1 使用默认灵敏度，不提供灵敏度调节选项
- 后续版本可在设置菜单中加入灵敏度滑块
---
## 跨系统交互
### 与交互系统的关系
- **输入互斥**：交互系统处于 Interacting 状态时，角色控制系统忽略移动输入
- **角色转向委托**：交互触发时（如观察、拾取），角色自动转向交互物的行为由交互系统控制，不由角色控制系统控制
- **摄像机控制权**：交互进行中摄像机由交互系统控制（推镜/回位）；交互结束后摄像机回到角色控制系统的默认跟随
- **状态信号**：角色控制系统向交互系统提供「角色当前状态」（Idle/Running）和「角色位置」，交互系统用这些信息判断交互触发条件
### 与场景系统的关系
- **碰撞体**：场景中的碰撞体决定角色的可通行区域，角色控制系统不定义碰撞，仅响应碰撞结果
- **地形设计约束**：v0.1 场景设计确保所有可达区域无需跳跃或蹲下即可到达
- **出生点**：角色初始位置在"家"门口，由场景系统定义出生点位置
---
## v0.1 不实现清单
以下功能明确排除在 v0.1 之外：
| 功能 | 排除原因 |
|------|----------|
| 步行 | v0.1 仅跑步，简化状态 |
| 蹲下 / 蹲伏移动 | v0.2+ 实现，v0.1 场景无蹲下专属内容 |
| 跳跃 | 不需要，场景设计保证跑步可达 |
| 攀爬 | 不需要 |
| 手柄适配 | v0.1 优先键鼠 |
| 体力 / 疲劳系统 | v0.1 跑步无限制 |
| 角色换装 / 自定义 | 后续版本 |
| 复杂动画系统 | v0.1 使用简单占位动画或无动画 |
| 存档 / 读档 | v0.1 不持久化 |
---
## 可调参数汇总
| 参数 | 建议值 | 可调范围 | 说明 |
|------|--------|----------|------|
| 摄像机默认距离 | 3.5m | 2.5-5.0m | 沿摄像机偏航角反方向 |
| 摄像机高度 | 0.8m | 0.5-1.2m | 角色头部上方 |
| 摄像机俯角 | 15° | 10°-25° | |
| 摄像机跟随速度倍率 | 3-5 倍 | 2-8 倍 | 相对角色移动速度 |
| 视角水平旋转速度 | 150°/秒 | 90°-300°/秒 | |
| 视角垂直上限 | +45° | +30° 至 +60° | 水平线以上 |
| 视角垂直下限 | -30° | -20° 至 -45° | 水平线以下 |
| 摄像机最小距离 | 0.5m | 0.3-1.0m | 碰撞拉近时 |
| 跑步速度 | 4.5 m/s | 3.5-6.0 m/s | v0.1 唯一移动速度 |
| 起步加速时间 | 0.2 秒 | 0.1-0.4 秒 | 静止到全速 |
| 停止减速时间 | 0.3 秒 | 0.2-0.5 秒 | 全速到静止 |
| 角色转向速度 | 720°/秒 | 360°-1080°/秒 | 移动时转向移动方向 |
| 可通行最大坡度 | 45° | 30°-60° | |
| 台阶最大高度 | 0.15m | 0.1-0.3m | 无需跳跃直接跑上 |
docs/plans/reports/design-report.md
+32 -9
View File
@@ -1,37 +1,60 @@
# 策划汇报
> 最后更新：—
> 当前无活跃任务
> 最后更新：2026-06-05
---
## 基本信息
- **日期**：—
- **日期**：2026-06-05
- **阶段**：原型阶段
- **版本号**：—
- **当前任务 ID**：—
- **版本号**：v0.1
- **当前任务 ID**：P-002
---
## 本期完成内容
—
### P-002 v0.1 执行案（③质量门修正）
三个执行案均已完成，可提交 PM 重新审查：
| 子任务 | 文件 | 版本 | 状态 |
|--------|------|------|------|
| P-002a 交互系统执行案 | `interaction-system-execution.md` | — | ✅ 已有（之前产出） |
| P-002b 收集系统执行案 | `collection-system-execution.md` | v0.1.1 | ✅ 架构重构完成 |
| P-002c 角色控制执行案 | `player-controller-execution.md` | v0.1.1 | ✅ 重写完成 |
### 主要设计决策
1. **交互系统**：层级状态模型（Free/Interacting/SubSystem/Cutscene），废纸箱改为单次翻找
2. **收集系统**：从拾取流程中剥离，仅负责进度追踪和收集通知；拾取通知归物品系统
3. **角色控制**：去掉步行，仅跑步；WASD 相对摄像机方向；平滑转身
---
## 待同步项
- [ ] 交互系统执行案：废纸箱翻找章节改为单次翻找（呼应收集系统 #7 武松卡）
- [ ] v01-scope.md：「WASD 步行移动」「Shift 跑步」更新为「WASD 跑步移动」
- [ ] 物品系统：新依赖，需 PM 审查时决定是否单独出执行案
---
## 遇到的问题 / 偏差
—
1. 收集系统初版与交互系统职责混淆，经用户反馈后重构为三层架构（交互→物品→收集）
2. 角色控制初版包含步行/跑步双状态，经用户反馈后简化为仅跑步
---
## 下一步计划
—
- 等待 PM 对 P-002 执行案进行 ③质量门审查
- 审查通过后进入 ④程序设计
---
## 需要协调的事项
—
- 物品系统（背包+拾取通知）是新引入的系统依赖，v0.1 需要实现但暂无独立执行案，需 PM 判定处理方式