2037 lines
62 KiB
Markdown
2037 lines
62 KiB
Markdown
# 《听仙》MVP 任务清单
|
||
|
||
> 创建日期：2026-05-22
|
||
> 对应策划案：v1.5
|
||
> 技术方案：纯前端（HTML5，无服务器）
|
||
> MVP 范围：v0.1 → v0.2 → v0.3 三阶段渐进交付
|
||
|
||
---
|
||
|
||
## 概览
|
||
|
||
### 阶段划分
|
||
|
||
| 阶段 | 目标 | 核心验证 |
|
||
|------|------|---------|
|
||
| **Phase 0** 基础准备 | 环境、设计补全、音色选定 | 工具链全通，设计无歧义 |
|
||
| **Phase 1 / v0.1** 纯音频原型 | 黑屏+手势+音频播报+房间移动 | 手势是否直觉，语音是否可懂 |
|
||
| **Phase 2 / v0.2** 战斗原型 | 2种怪+3技能+完整回合制 | 纯音频回合制是否可玩 |
|
||
| **Phase 3 / v0.3** 内容原型 | NPC+任务+背包+菜单 | 能否完成"接任务→打怪→交任务"闭环 |
|
||
|
||
### 技术选型（纯前端）
|
||
|
||
```
|
||
构建工具：Vite（本地开发服务+手机局域网测试）
|
||
语言：JavaScript（ES2022 模块化，不强制 TypeScript）
|
||
音频：Web Audio API + HTMLAudioElement
|
||
手势：Touch Events API
|
||
状态：有限状态机（自实现，无框架）
|
||
存储：localStorage（进度存档）
|
||
数据：JSON 文件（房间/NPC/物品/技能/怪物定义）
|
||
```
|
||
|
||
### 项目目录结构
|
||
|
||
```
|
||
xianxia/
|
||
├── docs/ # 策划与任务文档
|
||
├── src/
|
||
│ ├── index.html # 启动页 + 游戏容器
|
||
│ ├── main.js # 入口，组装所有模块
|
||
│ ├── audio/
|
||
│ │ ├── AudioEngine.js # 四层混音器
|
||
│ │ ├── VoiceQueue.js # 语音播报队列
|
||
│ │ └── UISynth.js # Web Audio UI音效合成
|
||
│ ├── gesture/
|
||
│ │ └── GestureRecognizer.js
|
||
│ ├── state/
|
||
│ │ └── StateMachine.js # 状态机框架
|
||
│ ├── game/
|
||
│ │ ├── World.js # 房间/地图
|
||
│ │ ├── Player.js # 角色属性
|
||
│ │ ├── Combat.js # 战斗引擎
|
||
│ │ ├── Quest.js # 任务系统
|
||
│ │ └── Inventory.js # 背包/物品
|
||
│ └── data/
|
||
│ ├── rooms.json
|
||
│ ├── npcs.json
|
||
│ ├── monsters.json
|
||
│ ├── items.json
|
||
│ ├── skills.json
|
||
│ └── quests.json
|
||
├── assets/
|
||
│ ├── voice/ # TTS 语音片段（mp3）
|
||
│ ├── sfx/ # 音效（wav/mp3）
|
||
│ ├── ambient/ # 环境氛围音（ogg）
|
||
│ └── bgm/ # 背景音乐（ogg）
|
||
└── scripts/
|
||
├── gen_tts.py # 批量 TTS 生成脚本
|
||
├── gen_sfx.py # 批量音效生成脚本
|
||
└── tts_manifest.csv # TTS 文本清单
|
||
```
|
||
|
||
### 任务编号规则
|
||
|
||
`P{阶段}-{序号}` — 例如 P1-03 表示 Phase 1 第 3 个任务。
|
||
每个任务包含：目标 / 前置依赖 / 实现方式 / 交付物 / 测试用例。
|
||
|
||
---
|
||
|
||
## Phase 0：基础准备
|
||
|
||
### P0-01：前端开发环境搭建
|
||
|
||
**目标**
|
||
建立可运行的项目骨架，开发者能在 PC 浏览器和局域网手机上实时预览。
|
||
|
||
**前置依赖**
|
||
无
|
||
|
||
**实现方式**
|
||
1. 在 `/home/xsl/xianxia/` 下初始化 Vite 项目：
|
||
```bash
|
||
npm create vite@latest . -- --template vanilla
|
||
npm install
|
||
```
|
||
2. 修改 `vite.config.js` 开启局域网访问：
|
||
```js
|
||
export default { server: { host: '0.0.0.0', port: 5173 } }
|
||
```
|
||
3. 按上方目录结构创建空文件占位。
|
||
4. `index.html` 设置 `<meta name="viewport" content="width=device-width">` 和黑色背景。
|
||
|
||
**交付物**
|
||
- `package.json` + `vite.config.js`
|
||
- `src/index.html`（空白黑屏页，含"开始听仙"按钮占位）
|
||
- `npm run dev` 成功启动，手机浏览器可访问
|
||
|
||
**测试用例**
|
||
|
||
| # | 操作 | 预期结果 |
|
||
|---|------|---------|
|
||
| 1 | `npm run dev` | 控制台无报错，显示本地和网络地址 |
|
||
| 2 | PC 浏览器访问 `localhost:5173` | 页面加载，黑色背景，有"开始听仙"按钮 |
|
||
| 3 | 手机浏览器访问局域网 IP | 同上，无布局错误 |
|
||
|
||
---
|
||
|
||
### P0-02：移动端测试环境搭建
|
||
|
||
**目标**
|
||
确保每个阶段的成果都能在真实手机上测试（iOS Safari + Android Chrome）。
|
||
|
||
**前置依赖**
|
||
P0-01
|
||
|
||
**实现方式**
|
||
1. 确认开发机与手机在同一局域网。
|
||
2. 在手机浏览器上将游戏页面添加到主屏幕（模拟 PWA 全屏）。
|
||
3. 准备 Chrome DevTools 远程调试（Android via USB）或 Safari Web Inspector（iOS via USB）。
|
||
4. 写 `scripts/open_qr.sh`：用 `qrencode` 生成局域网 URL 的二维码，方便快速打开。
|
||
```bash
|
||
#!/bin/bash
|
||
IP=$(hostname -I | awk '{print $1}')
|
||
echo "http://$IP:5173" | qrencode -t ANSIUTF8
|
||
```
|
||
|
||
**交付物**
|
||
- `scripts/open_qr.sh`
|
||
- 确认 iOS Safari 和 Android Chrome 均能访问开发服务器
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期结果 |
|
||
|---|------|---------|
|
||
| 1 | Android Chrome 访问 | 页面正常加载 |
|
||
| 2 | iOS Safari 访问 | 页面正常加载 |
|
||
| 3 | 添加到主屏幕后打开 | 全屏显示，无浏览器工具栏 |
|
||
|
||
---
|
||
|
||
### P0-03：音频生成管线验证与脚本化
|
||
|
||
**目标**
|
||
验证 VoxCPM2 → ffmpeg 的完整 TTS 流程可批量执行，产出可用的 mp3 文件；同时验证 ACE-Step 和 Stable Audio 能产出符合规格的音效/BGM。
|
||
|
||
**前置依赖**
|
||
无（工具已部署）
|
||
|
||
**实现方式**
|
||
|
||
**3.1 编写批量 TTS 脚本 `scripts/gen_tts.py`：**
|
||
```python
|
||
# 读取 tts_manifest.csv (id, text, voice_ref, output_path)
|
||
# 调用 VoxCPM2 REST API: POST http://localhost:8000/tts
|
||
# 用 ffmpeg 后处理：归一化音量(-16 LUFS)，转 mp3 64kbps，22050Hz
|
||
# 输出到 assets/voice/{id}.mp3
|
||
# 记录失败条目，支持断点续跑
|
||
```
|
||
|
||
`tts_manifest.csv` 格式：
|
||
```csv
|
||
id,text,voice_ref,priority
|
||
sys_welcome,"欢迎来到苍玄大陆。",narrator.wav,P2
|
||
sys_menu_open,"菜单。",narrator.wav,P2
|
||
```
|
||
|
||
**3.2 验证 ACE-Step（BGM/长音效）：**
|
||
- 手动启动 `conda activate acestep`
|
||
- 生成一段 30s 测试氛围音，确认输出可用
|
||
- 记录启动命令到 `scripts/README_tools.md`
|
||
|
||
**3.3 验证 Stable Audio（短音效）：**
|
||
- 启动 Gradio WebUI，生成一段 1s 剑击音效测试
|
||
- 确认 44.1kHz WAV 输出正常
|
||
|
||
**3.4 ffmpeg 后处理验证：**
|
||
```bash
|
||
# BGM/氛围 → OGG 128kbps
|
||
ffmpeg -i input.wav -c:a libvorbis -q:a 4 output.ogg
|
||
# 语音 → MP3 64kbps 22050Hz
|
||
ffmpeg -i input.wav -af "loudnorm=I=-16:TP=-1.5" -ar 22050 -b:a 64k output.mp3
|
||
# 短音效 → WAV 保持原格式（不压缩）
|
||
ffmpeg -i input.wav -ar 44100 -ac 1 output.wav
|
||
```
|
||
|
||
**交付物**
|
||
- `scripts/gen_tts.py`（可运行，含断点续跑）
|
||
- `scripts/tts_manifest.csv`（空模板）
|
||
- `scripts/README_tools.md`（各工具启动命令速查）
|
||
- 测试输出：3 条 TTS mp3、1 段氛围 ogg、1 个音效 wav，均通过质量验证
|
||
|
||
**测试用例**
|
||
|
||
| # | 操作 | 预期结果 |
|
||
|---|------|---------|
|
||
| 1 | 运行 `gen_tts.py` 生成 3 条测试文本 | 输出 3 个 mp3，无报错 |
|
||
| 2 | 手机播放生成的 mp3 | 音量正常，无爆音/底噪 |
|
||
| 3 | 手动中断 `gen_tts.py` 再重跑 | 已完成条目跳过，断点续跑正常 |
|
||
| 4 | 输入空文本或超长文本（>200字） | 脚本报错并记录，不崩溃 |
|
||
|
||
---
|
||
|
||
### P0-04：策划补全——战斗数值体系
|
||
|
||
**目标**
|
||
填补策划案中三处设计空缺，确保 Phase 2 战斗系统有明确的实现依据，不需要在编码时临时拍数字。
|
||
|
||
**前置依赖**
|
||
无
|
||
|
||
**需补全的三处问题**（来自 review）：
|
||
|
||
**4.1 攻击力推导**
|
||
在 `游戏策划案.md` 第四章补充：
|
||
|
||
```
|
||
物理攻击力 = 根骨 × 2 + 装备物理攻击加值
|
||
法术攻击力 = 灵力 × 2 + 装备法术攻击加值
|
||
物理防御力 = 根骨 × 1.5 + 装备防御加值
|
||
法术防御力 = 神识 × 1.5 + 装备法术防御加值
|
||
气血上限 = 根骨 × 10 + 境界基础值
|
||
灵力上限 = 灵力 × 8 + 境界基础值
|
||
```
|
||
|
||
**4.2 灵根与功法绑定规则**
|
||
在 `游戏策划案.md` 第四章 4.4 节补充：
|
||
|
||
```
|
||
规则：灵根不限制可学功法种类，但影响效果。
|
||
- 同灵根功法（如火灵根使用火球术）：伤害 × 1.2，灵力消耗 × 0.8
|
||
- 异灵根功法（如火灵根使用冰锥术）：伤害 × 0.9，灵力消耗 × 1.2
|
||
- 防御/辅助功法不受灵根影响
|
||
设计意图：允许跨灵根尝试，鼓励同灵根专精，不强制锁死功法选择。
|
||
```
|
||
|
||
**4.3 命中率公式计算顺序明确**
|
||
在 `游戏策划案.md` 第七章 7.3 节将：
|
||
> `最终命中 = 命中率 - 闪避率（下限50%，上限99%）`
|
||
|
||
改为更明确的表述：
|
||
> `最终命中率 = clamp(命中率 - 闪避率, 50%, 99%)`
|
||
> 其中命中率本身无上限限制（可超过100%用于抵消高闪避敌人）
|
||
|
||
**交付物**
|
||
- `游戏策划案.md` 中对应三处内容更新
|
||
|
||
**测试用例（设计评审）**
|
||
|
||
| # | 场景 | 验证 |
|
||
|---|------|------|
|
||
| 1 | 练气一层初始角色（根骨10，灵力8）| 物理攻击力=20，气血上限=100+境界基础值 |
|
||
| 2 | 火灵根用火球术 vs 冰锥术 | 伤害相差 1.2/0.9 倍，逻辑自洽 |
|
||
| 3 | 攻方等级比守方高20级 | 命中率=90%+40%=130%，减去闪避后仍被 cap 在 99% |
|
||
|
||
---
|
||
|
||
### P0-05：旁白音色选定与验证
|
||
|
||
**目标**
|
||
确定系统旁白（房间描述、系统提示）的 TTS 参考音频，后续所有 TTS 生成使用统一音色。
|
||
|
||
**前置依赖**
|
||
P0-03
|
||
|
||
**实现方式**
|
||
1. 用 VoxCPM2 准备 3 组候选参考音频（建议：沉稳男声/清冽女声/中性叙事声）。
|
||
2. 对每组音色，用相同的测试文本生成 3 句语音：
|
||
```
|
||
"你站在清风镇的中心广场。四周传来市集的喧嚣声。"
|
||
"战斗胜利。你获得经验值 120 点，灵石 30 枚。"
|
||
"菜单。角色信息。"
|
||
```
|
||
3. 在手机耳机下播放，评估清晰度、疲劳感（长时间听是否舒适）、仙侠感。
|
||
4. 记录选定音色的参考音频路径到 `scripts/tts_manifest.csv` 头部注释。
|
||
|
||
**交付物**
|
||
- `assets/voice/ref/narrator.wav`（选定的旁白参考音频）
|
||
- 3 组测试对比音频（存入 `assets/voice/ref/candidates/`，不进入游戏）
|
||
- `docs/音色选定记录.md`：记录选择理由
|
||
|
||
**测试用例**
|
||
|
||
| # | 评估维度 | 通过标准 |
|
||
|---|---------|---------|
|
||
| 1 | 清晰度 | 手机外放能听清每个字 |
|
||
| 2 | 疲劳感 | 连续播放 5 分钟不刺耳 |
|
||
| 3 | 风格 | 符合仙侠叙事感，不像 GPS 导航 |
|
||
| 4 | 一致性 | 同参考音频重复生成两次，结果基本相同 |
|
||
|
||
---
|
||
|
||
## Phase 1：v0.1 纯音频交互原型
|
||
|
||
**阶段目标**：玩家能打开游戏，在 3-5 个房间之间移动，通过语音了解所处位置，通过菜单查看基本状态。无战斗，无NPC，无物品。
|
||
|
||
**验证问题**：手势操作是否直觉？音频队列是否清晰？玩家能否理解所处环境？
|
||
|
||
---
|
||
|
||
### P1-01：启动页与音频解锁
|
||
|
||
**目标**
|
||
实现极简启动页，用户点击"开始听仙"后解锁浏览器音频权限，进入全黑游戏模式。
|
||
|
||
**前置依赖**
|
||
P0-01
|
||
|
||
**实现方式**
|
||
|
||
`src/index.html` 结构：
|
||
```html
|
||
<!-- 启动层（初始可见） -->
|
||
<div id="launch-screen">
|
||
<button id="start-btn" aria-label="开始听仙">开始听仙</button>
|
||
</div>
|
||
|
||
<!-- 游戏层（初始隐藏，黑色背景） -->
|
||
<div id="game-screen" hidden aria-live="polite" aria-atomic="false"></div>
|
||
```
|
||
|
||
`src/main.js` 音频解锁逻辑：
|
||
```js
|
||
document.getElementById('start-btn').addEventListener('click', async () => {
|
||
const ctx = new AudioContext();
|
||
await ctx.resume(); // 解锁
|
||
// 播放 0.1s 静音确保解锁
|
||
const buf = ctx.createBuffer(1, ctx.sampleRate * 0.1, ctx.sampleRate);
|
||
const src = ctx.createBufferSource();
|
||
src.buffer = buf;
|
||
src.connect(ctx.destination);
|
||
src.start();
|
||
|
||
document.getElementById('launch-screen').hidden = true;
|
||
document.getElementById('game-screen').hidden = false;
|
||
initGame(ctx);
|
||
});
|
||
```
|
||
|
||
**交付物**
|
||
- `src/index.html`（启动页完整标记）
|
||
- 音频解锁逻辑（嵌入 `main.js`）
|
||
- 启动页 CSS：黑色背景，居中按钮，无其他视觉元素
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期结果 |
|
||
|---|------|---------|
|
||
| 1 | PC Chrome 点击按钮 | 控制台无 AudioContext 报错，进入黑屏 |
|
||
| 2 | iOS Safari 点击按钮 | 音频正常解锁，不出现无声黑屏 |
|
||
| 3 | 不点按钮直接调用音频 | 音频不播放，保留在启动页 |
|
||
| 4 | 解锁失败（模拟）| 保留在启动页，不进入无声黑屏 |
|
||
|
||
---
|
||
|
||
### P1-02：手势识别模块
|
||
|
||
**目标**
|
||
识别 6 种手势（上/下/左/右滑动、单击、双击），以事件方式发出，供状态机消费。
|
||
|
||
**前置依赖**
|
||
P1-01
|
||
|
||
**实现方式**
|
||
|
||
`src/gesture/GestureRecognizer.js`：
|
||
```js
|
||
export class GestureRecognizer {
|
||
constructor(element) { /* 监听 touchstart/touchend/touchmove */ }
|
||
|
||
// 识别逻辑
|
||
// - 滑动：位移 > 30px，且 X 或 Y 方向占比 > 65%（防斜滑误触）
|
||
// - 单击：touchend 时位移 < 10px，300ms 内无第二次 touch
|
||
// - 双击：300ms 内两次单击
|
||
// - 不识别长按、三击等其他手势
|
||
|
||
on(gesture, callback) { /* 'swipe-up'|'swipe-down'|'swipe-left'|'swipe-right'|'tap'|'double-tap' */ }
|
||
}
|
||
```
|
||
|
||
关键参数（可配置常量）：
|
||
```js
|
||
const SWIPE_MIN_DISTANCE = 30; // px，最小滑动距离
|
||
const SWIPE_AXIS_RATIO = 0.65; // 主轴方向占比阈值
|
||
const DOUBLE_TAP_DELAY = 300; // ms，双击最大间隔
|
||
const TAP_MAX_DISTANCE = 10; // px，点击最大位移
|
||
```
|
||
|
||
**交付物**
|
||
- `src/gesture/GestureRecognizer.js`（完整实现）
|
||
- 浏览器控制台调试日志（开发模式下打印识别到的手势）
|
||
|
||
**测试用例**
|
||
|
||
| # | 操作 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 手指从下向上快速滑动 | 触发 `swipe-up` |
|
||
| 2 | 手指斜向滑动（45°） | 触发主方向的 swipe，不触发两个 |
|
||
| 3 | 轻点一次 | 300ms 后触发 `tap` |
|
||
| 4 | 快速点击两次（< 300ms）| 触发 `double-tap`，不触发两个 `tap` |
|
||
| 5 | 慢点两次（> 300ms 间隔）| 触发两个 `tap` |
|
||
| 6 | 滑动 < 30px | 不触发 swipe |
|
||
| 7 | iOS Safari 实机测试 | 系统手势（下拉刷新）不干扰游戏手势 |
|
||
|
||
---
|
||
|
||
### P1-03：UI 音效合成模块
|
||
|
||
**目标**
|
||
用 Web Audio API 实时合成 13 种 UI 音效，零文件依赖，操作后 < 10ms 内播放。
|
||
|
||
**前置依赖**
|
||
P1-01（需要已解锁的 AudioContext）
|
||
|
||
**实现方式**
|
||
|
||
`src/audio/UISynth.js`：
|
||
```js
|
||
export class UISynth {
|
||
constructor(audioContext) { this.ctx = audioContext; }
|
||
|
||
play(type) {
|
||
// type: 'swipe-up'|'swipe-down'|'swipe-left'|'swipe-right'
|
||
// 'tap'|'double-tap'|'invalid'
|
||
// 'menu-open'|'menu-close'|'list-scroll'
|
||
// 'confirm'|'error'|'item-pickup'
|
||
const spec = SOUND_SPECS[type];
|
||
if (!spec) return;
|
||
// 用 OscillatorNode + GainNode 合成短音
|
||
// 每种音效定义：频率(Hz)、包络(attack/decay/sustain/release)、波形
|
||
}
|
||
}
|
||
|
||
const SOUND_SPECS = {
|
||
'swipe-up': { freq: 880, type: 'sine', adsr: [0.01, 0.1, 0, 0.05] },
|
||
'swipe-down': { freq: 220, type: 'sine', adsr: [0.01, 0.15, 0, 0.05] },
|
||
'swipe-left': { freq: 440, type: 'triangle', adsr: [0.005, 0.08, 0, 0.03] },
|
||
'swipe-right': { freq: 550, type: 'triangle', adsr: [0.005, 0.08, 0, 0.03] },
|
||
'tap': { freq: 660, type: 'sine', adsr: [0.005, 0.1, 0, 0.04] },
|
||
'double-tap': { freq: [660, 880], type: 'sine', adsr: [0.005, 0.08, 0, 0.03] },
|
||
'invalid': { freq: 150, type: 'sawtooth', adsr: [0.01, 0.2, 0.1, 0.1] },
|
||
// ... 其余6种
|
||
};
|
||
```
|
||
|
||
**交付物**
|
||
- `src/audio/UISynth.js`（13 种音效全部实现）
|
||
- 调试页面：按钮逐一触发每种音效（开发用，不进游戏）
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 调用 `play('swipe-up')` | 立即听到升调短音，无延迟感 |
|
||
| 2 | 快速连续调用 10 次 | 每次都响，不互相覆盖/消音 |
|
||
| 3 | `play('invalid')` | 音色明显与其他不同，表达"无效" |
|
||
| 4 | 耳机下聆听 | 13 种音效能主观区分，不混淆 |
|
||
|
||
---
|
||
|
||
### P1-04：音频引擎——四层混音器
|
||
|
||
**目标**
|
||
实现 BGM / 氛围 / 音效 / 语音 四层独立混音，支持各层音量控制和 BGM 交叉淡入淡出。
|
||
|
||
**前置依赖**
|
||
P1-01
|
||
|
||
**实现方式**
|
||
|
||
`src/audio/AudioEngine.js`：
|
||
```js
|
||
export class AudioEngine {
|
||
constructor(audioContext) {
|
||
this.ctx = audioContext;
|
||
// 四个 GainNode → MasterGain → destination
|
||
this.layers = {
|
||
bgm: { gain: ctx.createGain(), volume: 0.4, loop: true },
|
||
ambient: { gain: ctx.createGain(), volume: 0.4, loop: true },
|
||
sfx: { gain: ctx.createGain(), volume: 0.8, loop: false },
|
||
voice: { gain: ctx.createGain(), volume: 1.0, loop: false },
|
||
};
|
||
}
|
||
|
||
// BGM 切换：交叉淡入淡出（2秒）
|
||
async setBGM(url) { /* 淡出旧BGM，加载新BGM，淡入 */ }
|
||
|
||
// 语音播报时 BGM 压低到 20%，播完恢复
|
||
onVoiceStart() { this._fadeTo('bgm', 0.2, 0.3); }
|
||
onVoiceEnd() { this._fadeTo('bgm', 0.4, 0.5); }
|
||
|
||
// 氛围音切换（1秒交叉）
|
||
setAmbient(url) { /* 同 BGM 逻辑，时间更短 */ }
|
||
|
||
// 音效：最多同时 3 个
|
||
playSFX(url) { /* 超过3个时丢弃最旧的 */ }
|
||
|
||
_fadeTo(layer, targetVolume, duration) { /* GainNode.gain.linearRampToValueAtTime */ }
|
||
}
|
||
```
|
||
|
||
**交付物**
|
||
- `src/audio/AudioEngine.js`（四层混音完整实现）
|
||
- 验证：两首 BGM 切换时有平滑交叉渐变，无爆音
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 播放 BGM，再调用 `setBGM(url2)` | 旧 BGM 渐出，新 BGM 渐入，无爆音 |
|
||
| 2 | 触发 `onVoiceStart()` | BGM 音量在 0.3s 内降到 20% |
|
||
| 3 | 触发 `onVoiceEnd()` | BGM 音量恢复到 40% |
|
||
| 4 | 同时触发 4 个音效 | 最多 3 个同时播放，第 4 个被丢弃 |
|
||
| 5 | 切换氛围音 | 旧氛围渐出，新氛围渐入，无突变 |
|
||
|
||
---
|
||
|
||
### P1-05：音频引擎——语音播报队列
|
||
|
||
**目标**
|
||
实现带优先级的语音队列：P0 立即打断，P1 插队，P2/P3 排队；支持音频片段拼接播放；队列上限 5 条。
|
||
|
||
**前置依赖**
|
||
P1-04
|
||
|
||
**实现方式**
|
||
|
||
`src/audio/VoiceQueue.js`：
|
||
```js
|
||
export class VoiceQueue {
|
||
constructor(audioEngine) {
|
||
this.queue = []; // [{priority, segments, fallbackText}]
|
||
this.playing = null;
|
||
this.maxSize = 5;
|
||
}
|
||
|
||
enqueue(item) {
|
||
// item = { priority: 0-3, segments: [url,...], fallbackText: '' }
|
||
if (item.priority === 0) {
|
||
this._interrupt();
|
||
this.queue.unshift(item);
|
||
} else if (item.priority === 1) {
|
||
const insertAt = this.queue.findIndex(i => i.priority > 1);
|
||
this.queue.splice(insertAt === -1 ? 0 : insertAt, 0, item);
|
||
} else {
|
||
this.queue.push(item);
|
||
}
|
||
// 队列溢出：丢弃队尾最低优先级
|
||
while (this.queue.length > this.maxSize) {
|
||
const dropIdx = this._findLowestPriorityFromTail();
|
||
this.queue.splice(dropIdx, 1);
|
||
}
|
||
if (!this.playing) this._playNext();
|
||
}
|
||
|
||
// 拼接播放：顺序播放 segments 数组中的多个音频片段
|
||
async _playSegments(segments) { /* 逐个 HTMLAudioElement 播放 */ }
|
||
|
||
_interrupt() { /* 停止当前播放，清空 P2/P3 队列 */ }
|
||
}
|
||
```
|
||
|
||
**交付物**
|
||
- `src/audio/VoiceQueue.js`（完整实现，含片段拼接）
|
||
- 单元测试文件 `src/audio/VoiceQueue.test.js`（验证优先级逻辑）
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 队列空时 enqueue P2 | 立即播放 |
|
||
| 2 | P2 播放中 enqueue P1 | P2 播完后播 P1 |
|
||
| 3 | P2 播放中 enqueue P0 | P2 立即中断，P0 立即开始 |
|
||
| 4 | 入队 6 条 P3 | 第 6 条被丢弃，队列保持 5 条 |
|
||
| 5 | 入队含 3 段 segments 的消息 | 三段依次播放，中间无明显停顿（≤100ms） |
|
||
| 6 | P3 播放中，玩家单击 | P3 被中断，状态播报（P2）正常入队 |
|
||
|
||
---
|
||
|
||
### P1-06：游戏状态机框架
|
||
|
||
**目标**
|
||
实现可扩展的有限状态机，管理探索态/战斗态/菜单态等主状态，支持状态进入/退出钩子。
|
||
|
||
**前置依赖**
|
||
P1-02（手势事件），P1-03（UI音效），P1-05（语音队列）
|
||
|
||
**实现方式**
|
||
|
||
`src/state/StateMachine.js`：
|
||
```js
|
||
export class StateMachine {
|
||
constructor(states, initialState) {
|
||
// states = { 'explore': ExploreState, 'combat': CombatState, ... }
|
||
this.current = null;
|
||
this.states = states;
|
||
this.transition(initialState);
|
||
}
|
||
|
||
transition(stateName, data = {}) {
|
||
if (this.current) this.current.onExit();
|
||
this.current = new this.states[stateName](this, data);
|
||
this.current.onEnter();
|
||
}
|
||
|
||
handleGesture(gesture) {
|
||
this.current.handleGesture(gesture);
|
||
}
|
||
}
|
||
|
||
// 每个状态实现:
|
||
export class BaseState {
|
||
onEnter() {}
|
||
onExit() {}
|
||
handleGesture(gesture) {}
|
||
}
|
||
```
|
||
|
||
Phase 1 只实现两个状态：
|
||
- `ExploreState`：处理移动、焦点切换、单击查看状态、下滑进菜单
|
||
- `MenuState`：处理菜单导航，左滑退出
|
||
|
||
**交付物**
|
||
- `src/state/StateMachine.js`
|
||
- `src/state/ExploreState.js`（移动、焦点、单击、进菜单）
|
||
- `src/state/MenuState.js`（基础菜单框架，菜单项为空占位）
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 初始状态 | 进入探索态，触发 `onEnter` |
|
||
| 2 | 探索态下滑 | 切换到菜单态，播放菜单打开音效 |
|
||
| 3 | 菜单态左滑 | 切换回探索态，播放菜单关闭音效 |
|
||
| 4 | 状态切换时旧状态 `onExit` 被调用 | 控制台可见日志 |
|
||
|
||
---
|
||
|
||
### P1-07：房间数据结构与清风镇地图
|
||
|
||
**目标**
|
||
定义 5 个清风镇房间的数据，可在运行时被导航系统读取。
|
||
|
||
**前置依赖**
|
||
P0-04（设计已补全）
|
||
|
||
**实现方式**
|
||
|
||
`src/data/rooms.json`（5 个房间）：
|
||
```json
|
||
{
|
||
"qingfeng_square": {
|
||
"id": "qingfeng_square",
|
||
"name": "清风镇·镇中广场",
|
||
"description": "你站在清风镇的中心广场。四周传来商贩的吆喝声和行人的脚步声。",
|
||
"area": "清风镇",
|
||
"exits": { "north": "qingfeng_north", "east": "qingfeng_inn", "west": "qingfeng_smith" },
|
||
"ambient": "market_noise.ogg",
|
||
"bgm": "town_bgm.ogg",
|
||
"safe_zone": true,
|
||
"pvp_allowed": false,
|
||
"level_range": [1, 5],
|
||
"npcs": [],
|
||
"items": []
|
||
},
|
||
"qingfeng_north": { ... /* 镇北郊外 */ },
|
||
"qingfeng_inn": { ... /* 客栈 */ },
|
||
"qingfeng_smith": { ... /* 铁匠铺 */ },
|
||
"qingfeng_inn2f": { ... /* 客栈二楼，安全区修炼 */ }
|
||
}
|
||
```
|
||
|
||
**交付物**
|
||
- `src/data/rooms.json`（5 个房间完整定义）
|
||
- `src/game/World.js`：`getRoom(id)`、`getRoomExits(id)` 等方法
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | `World.getRoom('qingfeng_square')` | 返回完整房间对象 |
|
||
| 2 | 检查所有出口的目标房间 ID | 均存在于 rooms.json，无悬空引用 |
|
||
| 3 | 安全区标记一致性 | 客栈二楼 `safe_zone: true`，镇北郊外 `false` |
|
||
|
||
---
|
||
|
||
### P1-08：探索态——移动与焦点切换
|
||
|
||
**目标**
|
||
实现完整的探索态交互：左/右滑切换焦点，上滑移动，单击查看状态，进房间播报完整语音流。
|
||
|
||
**前置依赖**
|
||
P1-05（语音队列），P1-06（状态机），P1-07（房间数据）
|
||
|
||
**实现方式**
|
||
|
||
完善 `src/state/ExploreState.js`：
|
||
|
||
```js
|
||
// 进入房间时的播报顺序（严格按策划案 5.3）：
|
||
// 1. 移动音效（脚步声，Web Audio 合成，0.5s）
|
||
// 2. 氛围音渐变（1s）
|
||
// 3. 房间名称 [P2]
|
||
// 4. 简短描述 [P2]
|
||
// 5. 出口提示 [P2]
|
||
// 6. 特殊提示（NPC/物品/玩家）[P3]
|
||
|
||
// 焦点系统：
|
||
// - 焦点列表 = 当前房间的 [出口列表] + [NPC列表] + [物品列表]
|
||
// - 进入房间默认焦点为第一个出口
|
||
// - 左/右滑循环切换，播报焦点名称
|
||
// - 上滑：当前焦点为出口 → 移动；否则播报"当前无法前进"
|
||
|
||
// 危险移动二次确认：
|
||
// - 出口目标房间 level_range[0] > 玩家等级+3 时，第一次上滑只播警告
|
||
// - 3秒内再次上滑才真正移动；其他操作取消确认
|
||
```
|
||
|
||
**交付物**
|
||
- `src/state/ExploreState.js`（完整探索态逻辑）
|
||
- 玩家位置持久化到 `localStorage`（刷新后恢复位置）
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 进入广场 | 依次听到：脚步音、氛围音渐入、"清风镇·镇中广场"、描述、出口提示 |
|
||
| 2 | 右滑两次 | 焦点从第一个出口切换到第二个出口，分别播报出口名称 |
|
||
| 3 | 焦点在出口时上滑 | 移动到目标房间，触发新房间播报流程 |
|
||
| 4 | 焦点在 NPC 时上滑 | 播报"当前无法前进"，不移动 |
|
||
| 5 | 单击 | 播报"你在 X。当前焦点：Y。" |
|
||
| 6 | 向危险区域上滑 | 播报警告，不移动 |
|
||
| 7 | 危险区域上滑后 3 秒内再次上滑 | 移动成功 |
|
||
| 8 | 刷新页面 | 恢复到上次位置，重新播报房间描述 |
|
||
|
||
---
|
||
|
||
### P1-09：菜单态基础框架
|
||
|
||
**目标**
|
||
实现可导航的菜单态，v0.1 阶段只需"角色信息"一个有实际内容的菜单项，其余为占位。
|
||
|
||
**前置依赖**
|
||
P1-06（状态机）
|
||
|
||
**实现方式**
|
||
|
||
完善 `src/state/MenuState.js`：
|
||
```
|
||
菜单项（v0.1 阶段）：
|
||
1. 角色信息 → 播报"练气初期，气血100，灵力80"（硬编码占位数值）
|
||
2. 修炼/突破 → "功能尚未开放"
|
||
3-8. 其余项 → "功能尚未开放"
|
||
|
||
手势：
|
||
- 上/下滑：切换焦点菜单项，播报项目名称
|
||
- 单击：播报当前菜单项简介
|
||
- 双击：执行当前菜单项
|
||
- 左滑：关闭菜单，返回探索态
|
||
- 60 秒无操作：自动关闭，播报"菜单已关闭"
|
||
```
|
||
|
||
**交付物**
|
||
- `src/state/MenuState.js`（8 个菜单项，含超时逻辑）
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 进入菜单 | 播放菜单打开音效 + "菜单。角色信息。" |
|
||
| 2 | 下滑 | 焦点移到下一项，播报项目名 |
|
||
| 3 | 上滑到第一项再上滑 | 不超出边界，播报无效提示或循环 |
|
||
| 4 | 双击"角色信息" | 播报角色信息 |
|
||
| 5 | 左滑 | 关闭菜单，返回探索态，播放关闭音效 |
|
||
| 6 | 静置 60 秒 | 自动关闭，播报"菜单已关闭" |
|
||
|
||
---
|
||
|
||
### P1-10：v0.1 音频资源批量生成
|
||
|
||
**目标**
|
||
生成 v0.1 原型所需的全部预制音频资源（约 23 个文件，不含 Web Audio 合成的 UI 音效）。
|
||
|
||
**前置依赖**
|
||
P0-03（管线验证），P0-05（旁白音色）
|
||
|
||
**实现方式**
|
||
|
||
**10.1 填写 TTS 文本清单 `scripts/tts_manifest_v01.csv`：**
|
||
|
||
系统提示语音（10 段，旁白音色）：
|
||
```
|
||
sys_welcome, "欢迎来到苍玄大陆。"
|
||
sys_menu_open, "菜单。"
|
||
sys_menu_item_1, "角色信息。"
|
||
sys_menu_close, "菜单已关闭。"
|
||
sys_invalid_move, "当前无法前进。"
|
||
sys_danger_warn, "前方危险，再次上滑确认前进。"
|
||
sys_safe_enter, "你进入了安全区。"
|
||
sys_safe_leave, "你离开了安全区。"
|
||
sys_focus_exit, "出口。"
|
||
sys_no_operation, "无法执行。"
|
||
```
|
||
|
||
房间描述语音（5 段，旁白音色）：
|
||
```
|
||
room_square_name, "清风镇·镇中广场。"
|
||
room_square_desc, "四周传来商贩的吆喝声和行人的脚步声。"
|
||
room_square_exits, "可向北前往镇北郊外，向东进入客栈，向西去铁匠铺。"
|
||
room_north_name, "清风镇·镇北郊外。"
|
||
room_north_desc, "微风吹过，草虫鸣叫。远处似有妖兽出没的迹象。"
|
||
... （其余3个房间类似，共15段）
|
||
```
|
||
|
||
通用词汇片段（5 段）：
|
||
```
|
||
word_you, "你"
|
||
word_at, "在"
|
||
word_focus, "当前焦点："
|
||
word_health, "气血"
|
||
word_mp, "灵力"
|
||
```
|
||
|
||
**10.2 生成环境氛围音（ACE-Step）：**
|
||
- `ambient_market.ogg`：市集喧嚣，30s 循环，prompt: "busy marketplace, chinese town ambience, crowd noise, vendors calling, footsteps"
|
||
- `ambient_wilderness.ogg`：山野，30s 循环，prompt: "outdoor wilderness, insects chirping, wind, peaceful nature"
|
||
|
||
**10.3 生成城镇 BGM（ACE-Step）：**
|
||
- `town_bgm.ogg`：90s 循环，中国风轻快，笛子为主，prompt: "chinese fantasy town BGM, flute, light and cheerful, loop"
|
||
|
||
**10.4 运行脚本并后处理：**
|
||
```bash
|
||
python scripts/gen_tts.py --manifest scripts/tts_manifest_v01.csv --output assets/voice/
|
||
# 后处理：氛围音和BGM转OGG 128kbps
|
||
for f in assets/ambient/*.wav; do ffmpeg -i "$f" -c:a libvorbis -q:a 4 "${f%.wav}.ogg"; done
|
||
```
|
||
|
||
**交付物**
|
||
- `assets/voice/*.mp3`：约 30 条语音（10 系统 + 15 房间描述 + 5 通用词）
|
||
- `assets/ambient/ambient_market.ogg`、`ambient_wilderness.ogg`
|
||
- `assets/bgm/town_bgm.ogg`
|
||
- 生成日志（记录成功/失败条数）
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 手机播放全部 30 条语音 | 无杂音/爆音，音量一致，吐字清晰 |
|
||
| 2 | 循环播放氛围音 5 分钟 | 无明显循环接缝感 |
|
||
| 3 | 手机外放 BGM | 音量适中，不刺耳 |
|
||
| 4 | 检查 mp3 文件大小 | 单条语音 < 100KB，BGM < 1.5MB |
|
||
|
||
---
|
||
|
||
### P1-11：v0.1 音频质检与验收
|
||
|
||
**目标**
|
||
对所有 v0.1 音频资源进行系统性主观评估，不合格的标记重生成。
|
||
|
||
**前置依赖**
|
||
P1-10
|
||
|
||
**实现方式**
|
||
|
||
建立评分表 `docs/音频质检_v01.md`：
|
||
|
||
| 文件 | 清晰度(1-5) | 音量一致(1-5) | 风格适合(1-5) | 结论 | 备注 |
|
||
|------|------------|-------------|-------------|------|------|
|
||
| sys_welcome.mp3 | | | | 通过/重生成 | |
|
||
| ... | | | | | |
|
||
|
||
评分标准：
|
||
- **清晰度 < 3**：重生成
|
||
- **音量差异 > 3dB**（主观感知）：ffmpeg 重归一化
|
||
- **风格 < 3**：考虑更换参考音频或调整生成参数
|
||
- BGM/氛围音额外检查：循环接缝是否自然
|
||
|
||
**交付物**
|
||
- `docs/音频质检_v01.md`（全部文件的评分记录）
|
||
- 重生成后的替换文件（如有）
|
||
|
||
**验收标准**
|
||
- 所有文件清晰度 ≥ 3，风格 ≥ 3
|
||
- BGM 循环接缝无明显断裂感
|
||
|
||
---
|
||
|
||
### P1-12：v0.1 集成测试与移动端验证
|
||
|
||
**目标**
|
||
将所有 v0.1 模块串联，在 iOS Safari 和 Android Chrome 实机上完成完整体验走查。
|
||
|
||
**前置依赖**
|
||
P1-01 ～ P1-11 全部完成
|
||
|
||
**测试场景**
|
||
|
||
| # | 场景 | 步骤 | 预期 |
|
||
|---|------|------|------|
|
||
| 1 | 完整启动流程 | 打开页面 → 点击"开始听仙" | 音频解锁，进入黑屏，播放欢迎语 |
|
||
| 2 | 基础移动 | 从广场右滑选出口 → 上滑移动 | 听到脚步声→氛围渐变→房间播报 |
|
||
| 3 | 焦点循环 | 右滑多次超过出口数量 | 循环回第一个出口 |
|
||
| 4 | 单击查看状态 | 在任意房间单击 | 播报"你在 X，当前焦点：Y" |
|
||
| 5 | 菜单完整流程 | 下滑→上/下滑导航→双击→左滑退出 | 每步均有对应音效和语音 |
|
||
| 6 | 误触容错 | 快速乱滑 | 无崩溃，无无声死锁 |
|
||
| 7 | 页面刷新 | 在某房间刷新页面 | 恢复到该房间，重新播报 |
|
||
| 8 | 后台切换 | 切到其他应用再返回 | 音频恢复正常播放 |
|
||
| 9 | 低电量模式(iOS) | 开启低电量模式 | 音频仍正常 |
|
||
| 10 | 连续使用 10 分钟 | 来回移动，多次开关菜单 | 无内存泄漏迹象（页面不卡顿）|
|
||
|
||
**验收标准（v0.1 阶段门禁）**
|
||
- 测试 #1-8 全部通过
|
||
- 在 iOS Safari 和 Android Chrome 各完成一次完整走查
|
||
- 找 1 位未参与开发的用户试玩 5 分钟，能不借助任何说明完成"移动到3个不同房间"
|
||
|
||
---
|
||
|
||
## Phase 2：v0.2 战斗原型
|
||
|
||
**阶段目标**：玩家在镇北郊外探索时随机遭遇野兔精或灰狼，进入回合制战斗，使用 3 个技能，战斗结束后返回探索态。
|
||
|
||
**验证问题**：纯音频回合制是否可玩？操作节奏是否舒适？玩家能否在不看屏幕的情况下理解战斗状态？
|
||
|
||
---
|
||
|
||
### P2-01：角色属性与数值系统
|
||
|
||
**目标**
|
||
实现角色的基础数值，以 v0.1 中硬编码的占位数值为基础，建立完整的属性对象。
|
||
|
||
**前置依赖**
|
||
P0-04（属性推导公式已确定）
|
||
|
||
**实现方式**
|
||
|
||
`src/game/Player.js`：
|
||
```js
|
||
export class Player {
|
||
constructor() {
|
||
// 基础属性（v0.2 阶段固定初始值，v0.3 才做角色创建）
|
||
this.level = 1;
|
||
this.realm = '练气一层';
|
||
this.rootBone = 10; // 根骨
|
||
this.comprehension = 8; // 悟性
|
||
this.spiritPower = 8; // 灵力
|
||
this.divineSense = 6; // 神识
|
||
this.fortune = 5; // 机缘
|
||
this.element = 'fire'; // 灵根（v0.2 固定火灵根）
|
||
}
|
||
|
||
// 推导属性（按 P0-04 公式）
|
||
get physAtk() { return this.rootBone * 2 + this.weaponBonus; }
|
||
get spellAtk() { return this.spiritPower * 2 + this.spellBonus; }
|
||
get physDef() { return Math.floor(this.rootBone * 1.5); }
|
||
get maxHP() { return this.rootBone * 10 + 50; } // 50=练气基础值
|
||
get maxMP() { return this.spiritPower * 8 + 40; }
|
||
}
|
||
```
|
||
|
||
**交付物**
|
||
- `src/game/Player.js`（属性推导全部实现）
|
||
- v0.2 初始角色数值文档（写入 `docs/MVP任务清单.md` 附录）
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 初始角色 rootBone=10 | `maxHP = 150`，`physAtk = 20` |
|
||
| 2 | 装备一把攻击+10的武器 | `physAtk = 30` |
|
||
| 3 | 修改根骨后 | 推导属性自动更新（getter） |
|
||
|
||
---
|
||
|
||
### P2-02：技能数据定义
|
||
|
||
**目标**
|
||
定义 3 个基础技能的完整数据，包含战斗参数和音频引用。
|
||
|
||
**前置依赖**
|
||
P0-04
|
||
|
||
**实现方式**
|
||
|
||
`src/data/skills.json`：
|
||
```json
|
||
{
|
||
"basic_sword": {
|
||
"id": "basic_sword",
|
||
"name": "御剑术",
|
||
"element": "gold",
|
||
"type": "attack",
|
||
"mpCost": 10,
|
||
"coefficient": 1.2,
|
||
"hitBonus": 0,
|
||
"description": "以灵力驭剑，造成物理伤害。",
|
||
"nameAudio": "voice/skill_basic_sword.mp3",
|
||
"sfxAudio": "sfx/sword_slash.wav"
|
||
},
|
||
"iron_shield": {
|
||
"id": "iron_shield",
|
||
"name": "金钟罩",
|
||
"element": "gold",
|
||
"type": "defense",
|
||
"mpCost": 12,
|
||
"coefficient": 0,
|
||
"defenseBonus": 0.5,
|
||
"duration": 1,
|
||
"description": "护体金光，本回合物理伤害减半。",
|
||
"nameAudio": "voice/skill_iron_shield.mp3",
|
||
"sfxAudio": "sfx/shield_up.wav"
|
||
},
|
||
"heal_spring": {
|
||
"id": "heal_spring",
|
||
"name": "回春术",
|
||
"element": "wood",
|
||
"type": "heal",
|
||
"mpCost": 15,
|
||
"healCoefficient": 0.8,
|
||
"description": "以木灵气疗愈，恢复气血。",
|
||
"nameAudio": "voice/skill_heal_spring.mp3",
|
||
"sfxAudio": "sfx/heal.wav"
|
||
}
|
||
}
|
||
```
|
||
|
||
**交付物**
|
||
- `src/data/skills.json`（3 个技能完整定义）
|
||
- `src/game/SkillSystem.js`：`applySkill(attacker, target, skillId)` 方法
|
||
|
||
**测试用例**
|
||
|
||
| # | 技能 | 预期结果 |
|
||
|---|------|---------|
|
||
| 1 | 御剑术（火灵根使用金系技能）| 伤害 = physAtk × 1.2 × 0.9（异灵根）× 克制系数 |
|
||
| 2 | 金钟罩激活后受击 | 伤害减半 |
|
||
| 3 | 回春术灵力不足 | 技能无法使用，播报"灵力不足" |
|
||
|
||
---
|
||
|
||
### P2-03：怪物数据定义
|
||
|
||
**目标**
|
||
定义野兔精和灰狼两种怪物的完整数据，包含 AI 行为和音频引用。
|
||
|
||
**前置依赖**
|
||
P0-04
|
||
|
||
**实现方式**
|
||
|
||
`src/data/monsters.json`：
|
||
```json
|
||
{
|
||
"wild_rabbit": {
|
||
"id": "wild_rabbit",
|
||
"name": "野兔精",
|
||
"level": 2,
|
||
"element": "wood",
|
||
"hp": 80, "maxHp": 80,
|
||
"physAtk": 12, "physDef": 6, "spellDef": 4,
|
||
"skills": ["scratch"],
|
||
"expReward": 30,
|
||
"moneyReward": [5, 15],
|
||
"dropTable": [{"itemId": "rabbit_fur", "rate": 0.5}],
|
||
"nameAudio": "voice/monster_rabbit.mp3",
|
||
"roarAudio": "sfx/rabbit_cry.wav",
|
||
"aiType": "aggressive",
|
||
"encounterRooms": ["qingfeng_north"]
|
||
},
|
||
"grey_wolf": {
|
||
"id": "grey_wolf",
|
||
"name": "灰狼",
|
||
"level": 3,
|
||
"element": "earth",
|
||
"hp": 120, "maxHp": 120,
|
||
"physAtk": 18, "physDef": 10, "spellDef": 6,
|
||
"skills": ["bite", "howl"],
|
||
"expReward": 60,
|
||
"moneyReward": [10, 25],
|
||
"dropTable": [{"itemId": "wolf_pelt", "rate": 0.4}],
|
||
"nameAudio": "voice/monster_wolf.mp3",
|
||
"roarAudio": "sfx/wolf_howl.wav",
|
||
"aiType": "cautious",
|
||
"encounterRooms": ["qingfeng_north"]
|
||
}
|
||
}
|
||
```
|
||
|
||
怪物 AI 行为（简单规则，非复杂AI）：
|
||
```
|
||
aggressive：每回合使用攻击技能（随机选）
|
||
cautious：HP > 50% 时攻击，HP ≤ 50% 时有 30% 概率防御
|
||
```
|
||
|
||
**交付物**
|
||
- `src/data/monsters.json`（2 种怪物 + 2 种怪物技能：scratch、bite、howl）
|
||
- `src/game/MonsterAI.js`：`chooseAction(monster, combat)` 方法
|
||
|
||
---
|
||
|
||
### P2-04：战斗态状态机
|
||
|
||
**目标**
|
||
实现战斗态的手势映射（上/下切技能，左/右切目标，单击查状态，双击出招）。
|
||
|
||
**前置依赖**
|
||
P1-06（状态机框架）
|
||
|
||
**实现方式**
|
||
|
||
`src/state/CombatState.js`：
|
||
```js
|
||
export class CombatState extends BaseState {
|
||
onEnter({ monster }) {
|
||
this.combat = new Combat(player, monster);
|
||
this.currentSkillIdx = 0;
|
||
this.stateVersion = 0;
|
||
this.playerViewedVersion = 0;
|
||
// 播报战斗开始音效 + "战斗开始！你遭遇了[怪物名]。"
|
||
this._announceRoundStart();
|
||
}
|
||
|
||
handleGesture(g) {
|
||
switch(g) {
|
||
case 'swipe-up': this._prevSkill(); break;
|
||
case 'swipe-down': this._nextSkill(); break;
|
||
case 'swipe-left': this._prevTarget(); break;
|
||
case 'swipe-right':this._nextTarget(); break;
|
||
case 'tap': this._viewStatus(); break; // 更新 playerViewedVersion
|
||
case 'double-tap': this._confirmAttack(); break; // 检查 version 一致性
|
||
}
|
||
}
|
||
|
||
_confirmAttack() {
|
||
if (this.playerViewedVersion !== this.stateVersion) {
|
||
voiceQueue.enqueue({priority:2, text: '状态已更新，请先查看。'});
|
||
return;
|
||
}
|
||
this.combat.playerAction(currentSkill, currentTarget);
|
||
}
|
||
}
|
||
```
|
||
|
||
**交付物**
|
||
- `src/state/CombatState.js`（完整战斗态实现）
|
||
|
||
---
|
||
|
||
### P2-05：回合制战斗引擎
|
||
|
||
**目标**
|
||
实现完整的回合制战斗逻辑：伤害计算、命中判定、属性克制、状态效果、胜负判定。
|
||
|
||
**前置依赖**
|
||
P2-01（属性系统），P2-02（技能系统），P2-03（怪物数据）
|
||
|
||
**实现方式**
|
||
|
||
`src/game/Combat.js`：
|
||
```js
|
||
export class Combat {
|
||
constructor(player, monster) { ... }
|
||
|
||
playerAction(skillId, targetId) {
|
||
const result = this._resolveAction(player, monster, skillId);
|
||
this.stateVersion++;
|
||
return result;
|
||
// result = { hit: bool, damage: int, effects: [], monsterHp: int }
|
||
}
|
||
|
||
monsterAction() {
|
||
const skillId = MonsterAI.chooseAction(this.monster, this);
|
||
return this._resolveAction(this.monster, this.player, skillId);
|
||
}
|
||
|
||
_resolveAction(attacker, target, skillId) {
|
||
const skill = skills[skillId];
|
||
const hit = this._rollHit(attacker, target, skill);
|
||
if (!hit) return { hit: false };
|
||
|
||
let dmg = skill.coefficient * attacker.physAtk - target.physDef * 0.5;
|
||
dmg *= this._elementModifier(skill.element, target.element);
|
||
dmg *= this._elementAffinity(attacker.element, skill.element); // 灵根亲和
|
||
dmg *= this._critModifier(attacker);
|
||
dmg *= 0.9 + Math.random() * 0.2; // 浮动
|
||
dmg = Math.max(1, Math.round(dmg));
|
||
|
||
target.hp = Math.max(0, target.hp - dmg);
|
||
return { hit: true, damage: dmg, targetHp: target.hp };
|
||
}
|
||
|
||
_rollHit(attacker, target, skill) {
|
||
const hitRate = 0.9 + (attacker.level - target.level) * 0.02 + (skill.hitBonus || 0);
|
||
const dodgeRate = 0.05;
|
||
return Math.random() < Math.min(0.99, Math.max(0.5, hitRate - dodgeRate));
|
||
}
|
||
}
|
||
```
|
||
|
||
**交付物**
|
||
- `src/game/Combat.js`（完整战斗引擎）
|
||
- 单元测试 `src/game/Combat.test.js`：验证各公式边界值
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 1级角色打1级野兔精，御剑术 | 伤害在合理范围（约 15-25 点） |
|
||
| 2 | 火灵根用御剑术（金系） | 伤害 × 0.9（异灵根惩罚） |
|
||
| 3 | 金钟罩激活后挨打 | 受到伤害减半 |
|
||
| 4 | 灰狼攻击玩家 | HP 正确减少 |
|
||
| 5 | HP 降到 0 | `isAlive()` 返回 false，触发结算 |
|
||
| 6 | 命中率公式 | 等级差±20 时，最终命中率不超出 50%-99% |
|
||
|
||
---
|
||
|
||
### P2-06：遭遇触发与战斗结算
|
||
|
||
**目标**
|
||
玩家进入镇北郊外时，有概率随机触发遭遇战；战斗结束后结算并返回探索态。
|
||
|
||
**前置依赖**
|
||
P2-04（战斗态），P1-08（探索态）
|
||
|
||
**实现方式**
|
||
|
||
在 `src/state/ExploreState.js` 的 `onEnterRoom()` 中：
|
||
```js
|
||
onEnterRoom(roomId) {
|
||
// 先正常播报房间
|
||
this._announceRoom(roomId);
|
||
|
||
// 检查遭遇
|
||
const room = World.getRoom(roomId);
|
||
if (room.encounterRate && Math.random() < room.encounterRate) {
|
||
const monsterId = this._rollMonster(room);
|
||
setTimeout(() => {
|
||
// 播报遭遇提示，然后切换到战斗态
|
||
voiceQueue.enqueue({priority:1, text: `前方灌木丛中传来异响——${monsters[monsterId].name}出现了！`});
|
||
stateMachine.transition('combat', { monster: createMonsterInstance(monsterId) });
|
||
}, 2000); // 等房间播报完再触发
|
||
}
|
||
}
|
||
```
|
||
|
||
战斗结算（在 `CombatState` 中）：
|
||
```js
|
||
_onCombatEnd(winner) {
|
||
if (winner === 'player') {
|
||
const { exp, money, drops } = this.combat.calculateRewards();
|
||
// 播报"战斗胜利。获得经验 X 点，灵石 Y 枚。[掉落物品]"
|
||
player.gainExp(exp);
|
||
player.money += money;
|
||
} else {
|
||
// 播报"你被击败了。"+ 气血恢复到 30%（不掉级）
|
||
player.hp = Math.floor(player.maxHP * 0.3);
|
||
}
|
||
setTimeout(() => stateMachine.transition('explore'), 3000);
|
||
}
|
||
```
|
||
|
||
**交付物**
|
||
- 遭遇触发逻辑（整合到 `ExploreState.js`）
|
||
- 战斗结算逻辑（整合到 `CombatState.js`）
|
||
- `rooms.json` 中 `qingfeng_north` 添加 `encounterRate: 0.4`
|
||
|
||
---
|
||
|
||
### P2-07：操作窗口机制（state_version）
|
||
|
||
**目标**
|
||
防止玩家在没有听到最新战斗状态时盲目出招（按策划案 6.2 操作窗口设计）。
|
||
|
||
**前置依赖**
|
||
P2-04（战斗态）
|
||
|
||
**实现方式**
|
||
已在 P2-04 的 `CombatState` 中内嵌，此任务确保：
|
||
1. 每次状态变化（回合切换、敌方出招结算）都递增 `stateVersion`
|
||
2. 玩家单击查看状态时，`playerViewedVersion = stateVersion`
|
||
3. 玩家上/下滑切换技能/目标时，也更新 `playerViewedVersion`
|
||
4. 双击出招时校验两个版本是否一致
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 进入新回合，不查看直接双击 | 播报"状态已更新，请先查看"，不出招 |
|
||
| 2 | 单击查看后双击 | 正常出招 |
|
||
| 3 | 切换技能（下滑）后双击 | 视为已"浏览"，正常出招 |
|
||
|
||
---
|
||
|
||
### P2-08：v0.2 音频资源批量生成
|
||
|
||
**目标**
|
||
生成 v0.2 战斗原型所需的全部新增音频资源（约 30 个文件）。
|
||
|
||
**前置依赖**
|
||
P0-03，P0-05
|
||
|
||
**内容清单：**
|
||
|
||
战斗系统提示语音（TTS，旁白音色，10 段）：
|
||
```
|
||
combat_start, "战斗开始！"
|
||
combat_round_N, "第[N]回合。"（需 N=1-10，共10段）
|
||
combat_your_turn, "你的回合。"
|
||
combat_enemy_turn, "敌方行动。"
|
||
combat_victory, "战斗胜利！"
|
||
combat_defeat, "你被击败了。"
|
||
combat_escape_ok, "成功逃脱！"
|
||
combat_escape_fail,"逃脱失败！"
|
||
combat_low_hp, "气血危急！"
|
||
combat_state_update,"状态已更新，请先查看。"
|
||
```
|
||
|
||
数字语音（TTS，10 段）：
|
||
```
|
||
num_0 到 num_9，文本"零一二三四五六七八九"各一段
|
||
```
|
||
|
||
通用战斗词汇（TTS，10 段）：
|
||
```
|
||
word_damage, "点"（伤害后接）
|
||
word_hp_restored, "气血恢复"
|
||
word_mp_cost, "消耗灵力"
|
||
word_miss, "未命中"
|
||
word_crit, "暴击"
|
||
word_blocked, "被格挡"
|
||
word_poisoned, "中毒"
|
||
word_exp_gained, "获得经验"
|
||
word_money_gained, "灵石"
|
||
word_item_dropped, "获得"
|
||
```
|
||
|
||
技能名称语音（TTS，3 段）：
|
||
```
|
||
skill_basic_sword, "御剑术"
|
||
skill_iron_shield, "金钟罩"
|
||
skill_heal_spring, "回春术"
|
||
```
|
||
|
||
怪物名称+叫声（TTS×2 + 音效×2）：
|
||
```
|
||
monster_rabbit.mp3， TTS "野兔精"
|
||
monster_wolf.mp3， TTS "灰狼"
|
||
sfx_rabbit_cry.wav， Stable Audio 生成，高亢短叫 < 1s
|
||
sfx_wolf_howl.wav， ACE-Step 生成，狼嚎 1-2s
|
||
```
|
||
|
||
战斗音效（Stable Audio，6 个）：
|
||
```
|
||
sfx_sword_slash.wav， 剑击 0.5s
|
||
sfx_punch.wav， 拳击 0.3s
|
||
sfx_shield_block.wav， 格挡 0.4s
|
||
sfx_dodge.wav， 闪避风声 0.3s
|
||
sfx_hit.wav， 命中 0.5s
|
||
sfx_combat_start.wav， 战斗开始剑鸣+鼓点 2s
|
||
```
|
||
|
||
战斗 BGM（ACE-Step，1 首）：
|
||
```
|
||
bgm_combat.ogg， 60s 循环，紧张鼓点驱动，中国风
|
||
```
|
||
|
||
**交付物**
|
||
- `assets/voice/`：约 40 条 mp3
|
||
- `assets/sfx/`：6 个 wav
|
||
- `assets/bgm/bgm_combat.ogg`
|
||
|
||
---
|
||
|
||
### P2-09：v0.2 音频质检与验收
|
||
|
||
与 P1-11 相同流程，重点额外检查：
|
||
- 战斗音效（剑击/命中/格挡）在耳机下是否有空间感
|
||
- 战斗 BGM 循环是否流畅，是否与战斗张力匹配
|
||
- 数字语音（0-9）音调是否一致，拼接后是否自然
|
||
|
||
**交付物**
|
||
- `docs/音频质检_v02.md`
|
||
|
||
---
|
||
|
||
### P2-10：战斗音频流集成
|
||
|
||
**目标**
|
||
将战斗引擎的计算结果转化为正确的音频播报序列，实现策划案 7.2 节描述的完整战斗音频流。
|
||
|
||
**前置依赖**
|
||
P2-05（战斗引擎），P2-09（音频通过质检）
|
||
|
||
**实现方式**
|
||
|
||
`src/game/CombatNarrator.js`：将 Combat 的事件结果转为 VoiceQueue 条目：
|
||
```js
|
||
// 输入：combat.playerAction() 返回的 result 对象
|
||
// 输出：VoiceQueue.enqueue() 调用序列
|
||
|
||
narratePlayerAction(result, skill, target) {
|
||
// 音效层：立即播放
|
||
audioEngine.playSFX(skill.sfxAudio);
|
||
|
||
if (!result.hit) {
|
||
voiceQueue.enqueue({priority:2, segments:['voice/word_miss.mp3']});
|
||
return;
|
||
}
|
||
|
||
// 语音层：技能名 → 伤害数值 → 目标状态
|
||
const dmgAudio = this._buildNumberAudio(result.damage); // 拼接数字
|
||
voiceQueue.enqueue({priority:2, segments:[
|
||
skill.nameAudio,
|
||
'voice/word_damage.mp3',
|
||
...dmgAudio,
|
||
'voice/word_damage_suffix.mp3',
|
||
this._buildHpStatusAudio(target),
|
||
]});
|
||
}
|
||
```
|
||
|
||
**测试用例**
|
||
|
||
| # | 战斗事件 | 预期音频序列 |
|
||
|---|---------|------------|
|
||
| 1 | 玩家御剑术命中，造成 25 伤害 | 剑击音→"御剑术"→"造成"→"二十五"→"点伤害"→"野兔精气血剩余XX%" |
|
||
| 2 | 玩家攻击未命中 | 空气划过音→"未命中" |
|
||
| 3 | 怪物攻击玩家 | 怪物叫声→"[怪物名]发动攻击"→"你受到X点伤害" |
|
||
| 4 | 玩家 HP < 20% | 额外播报 P1 优先级"气血危急！" |
|
||
|
||
---
|
||
|
||
### P2-11：v0.2 集成测试与移动端验证
|
||
|
||
**测试场景**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 探索触发遭遇 | 听到警告语音 + 战斗 BGM 切入 |
|
||
| 2 | 完整回合流程 | 回合开始→出招→敌方行动→回合结算，语音流完整 |
|
||
| 3 | 切换技能再出招 | 只使用最后选择的技能 |
|
||
| 4 | 出招版本检查 | 新回合开始后未查看，双击无效 |
|
||
| 5 | 战斗胜利 | BGM 切换，播报经验/金币，返回探索态 |
|
||
| 6 | 战斗失败 | 播报失败，HP 恢复 30%，返回探索态 |
|
||
| 7 | 10 场连续战斗 | 无崩溃，无音频混乱 |
|
||
|
||
**v0.2 验收标准（阶段门禁）**
|
||
- 能完成从遭遇→战斗→胜利/失败→返回探索的完整流程
|
||
- 找 1 位用户不看屏幕，只听音频，能说出当前是第几回合、双方大致血量
|
||
|
||
---
|
||
|
||
## Phase 3：v0.3 内容原型（MVP）
|
||
|
||
**阶段目标**：角色创建 → 接教学任务 → 打怪完成任务 → 回城交任务。菜单/背包/装备/商店全部可用。
|
||
|
||
**验证问题**：能否通过音频完成"接任务→打怪→交任务"完整闭环？
|
||
|
||
---
|
||
|
||
### P3-01：角色创建流程
|
||
|
||
**目标**
|
||
实现纯语音引导的角色创建：道号生成/自定义、灵根选择、出身选择。
|
||
|
||
**前置依赖**
|
||
P2-01（属性系统），P1-05（语音队列）
|
||
|
||
**实现方式**
|
||
|
||
`src/state/CharCreateState.js`，三步流程：
|
||
|
||
```
|
||
步骤1：道号
|
||
→ 系统随机生成 5 个候选道号（从预设词库拼接：云/风/玉/剑/松+子/生/道人等）
|
||
→ 语音："道号——云松子，可对否？双击确认，上滑/下滑换一个，右滑自定义。"
|
||
→ 自定义时：弹出键盘输入，确认后语音播报验证
|
||
|
||
步骤2：灵根
|
||
→ 语音："请选择你的灵根属性。上滑下滑切换，双击确认。"
|
||
→ 5 种灵根轮播，每个附带简短属性说明语音
|
||
|
||
步骤3：出身
|
||
→ 3 种出身，选择决定初始房间和开局语音
|
||
→ 双击确认后播放 15-20 秒出生叙事音频，进入游戏世界
|
||
```
|
||
|
||
**交付物**
|
||
- `src/state/CharCreateState.js`
|
||
- 道号词库（`src/data/names.json`，100+ 个词组元素）
|
||
- 角色创建引导语音（TTS，约 20 段，纳入 P3-11）
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 上/下滑切换道号 | 每次听到新道号语音 |
|
||
| 2 | 右滑自定义道号 | 键盘弹出，输入"青云散人"后双击确认 → 语音"道号——青云散人，可对否？" |
|
||
| 3 | 选择出身后 | 播放专属出生叙事，然后出现在对应初始房间 |
|
||
|
||
---
|
||
|
||
### P3-02：NPC 数据与对话树
|
||
|
||
**目标**
|
||
定义教程 NPC（张道长）的完整对话树，支持首次见面与日常两种开场。
|
||
|
||
**前置依赖**
|
||
无
|
||
|
||
**实现方式**
|
||
|
||
`src/data/npcs.json`：
|
||
```json
|
||
{
|
||
"zhang_daochang": {
|
||
"id": "zhang_daochang",
|
||
"name": "张道长",
|
||
"room": "qingfeng_square",
|
||
"voiceRef": "old_man.wav",
|
||
"nameAudio": "voice/npc_zhang_name.mp3",
|
||
"dialogs": {
|
||
"first_meet": {
|
||
"audio": "voice/npc_zhang_first.mp3",
|
||
"text": "少侠，初来乍到吧？老夫张道长，在此已修行多年。",
|
||
"options": [
|
||
{ "id": "ask_quest", "text": "请教修炼之法", "audio": "voice/npc_zhang_opt1.mp3",
|
||
"next": "give_quest" },
|
||
{ "id": "ask_area", "text": "询问附近情况", "audio": "voice/npc_zhang_opt2.mp3",
|
||
"next": "area_info" },
|
||
{ "id": "farewell", "text": "告辞", "audio": "voice/common_farewell.mp3",
|
||
"action": "end_dialog" }
|
||
]
|
||
},
|
||
"give_quest": {
|
||
"audio": "voice/npc_zhang_quest.mp3",
|
||
"text": "镇北郊外近来妖兽横行，你若有意，可去清剿灰狼10只。",
|
||
"action": "offer_quest:quest_wolf_hunt",
|
||
"options": [ { "id": "accept", "action": "accept_quest" }, { "id": "decline" } ]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**交付物**
|
||
- `src/data/npcs.json`（张道长完整对话树）
|
||
- `src/game/DialogSystem.js`：解析对话树，处理 action
|
||
|
||
---
|
||
|
||
### P3-03：对话态交互实现
|
||
|
||
**目标**
|
||
实现对话态的手势交互，与策划案 3.3 节完全一致。
|
||
|
||
**前置依赖**
|
||
P1-06（状态机），P3-02（NPC数据）
|
||
|
||
**实现方式**
|
||
`src/state/DialogState.js`：
|
||
```
|
||
上/下滑：切换对话选项，播报选项文本
|
||
左滑：结束对话，返回探索态
|
||
右滑：重听 NPC 最后一句话
|
||
单击：播报当前选项内容
|
||
双击：选择当前选项
|
||
60 秒超时：自动结束对话
|
||
```
|
||
|
||
**交付物**
|
||
- `src/state/DialogState.js`
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 双击 NPC | 触发 first_meet 对话，播放对话语音 |
|
||
| 2 | 上/下滑 | 在3个选项间切换 |
|
||
| 3 | 右滑 | 重播 NPC 最后一句 |
|
||
| 4 | 选择"接受任务" | 触发 accept_quest action，播报"接受任务——清剿灰狼" |
|
||
| 5 | 左滑 | 结束对话，返回探索态，播报"你向张道长告辞" |
|
||
|
||
---
|
||
|
||
### P3-04：任务系统
|
||
|
||
**目标**
|
||
实现任务的接取、进度追踪、播报和完成结算。
|
||
|
||
**前置依赖**
|
||
P3-02，P2-06（战斗结算）
|
||
|
||
**实现方式**
|
||
|
||
`src/data/quests.json`（1 条教学任务）：
|
||
```json
|
||
{
|
||
"quest_wolf_hunt": {
|
||
"id": "quest_wolf_hunt",
|
||
"name": "清剿灰狼",
|
||
"giver": "zhang_daochang",
|
||
"objectives": [
|
||
{ "type": "kill", "targetId": "grey_wolf", "required": 3, "current": 0 }
|
||
],
|
||
"rewards": { "exp": 200, "money": 50, "items": [] },
|
||
"progressAudio": "voice/quest_wolf_progress.mp3",
|
||
"completeAudio": "voice/quest_wolf_complete.mp3"
|
||
}
|
||
}
|
||
```
|
||
|
||
`src/game/Quest.js`：
|
||
```js
|
||
// 战斗结算时调用 Quest.onKill(monsterId)
|
||
// 播报进度："灰狼 1/3。"
|
||
// 目标达成时播报："任务目标完成！请回去找张道长。"
|
||
```
|
||
|
||
**交付物**
|
||
- `src/data/quests.json`
|
||
- `src/game/Quest.js`（接取、进度、完成全流程）
|
||
- 任务进度持久化到 `localStorage`
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 接取任务后击杀第一只灰狼 | 播报"灰狼 1/3" |
|
||
| 2 | 击杀第 3 只 | 播报"灰狼 3/3，任务目标完成，请回去找张道长" |
|
||
| 3 | 回到 NPC 对话选择"交任务" | 播报结算语音，获得奖励 |
|
||
| 4 | 刷新页面 | 任务进度保留 |
|
||
|
||
---
|
||
|
||
### P3-05：物品与背包数据
|
||
|
||
**目标**
|
||
定义 5 种 MVP 物品，实现背包数据结构（增删改查）。
|
||
|
||
**前置依赖**
|
||
无
|
||
|
||
**实现方式**
|
||
|
||
`src/data/items.json`（5 种）：
|
||
```json
|
||
{
|
||
"iron_sword": { "id":"iron_sword", "name":"铁剑", "type":"weapon", "slot":"weapon", "physAtkBonus":10, "quality":"common", "nameAudio":"..." },
|
||
"cloth_robe": { "id":"cloth_robe", "name":"布衣", "type":"armor", "slot":"body", "physDefBonus":5, "quality":"common" },
|
||
"healing_pill": { "id":"healing_pill", "name":"续命丹", "type":"consumable", "effect":{"hp":50}, "quality":"common" },
|
||
"spirit_pill": { "id":"spirit_pill", "name":"回灵丹", "type":"consumable", "effect":{"mp":40}, "quality":"common" },
|
||
"wolf_pelt": { "id":"wolf_pelt", "name":"灰狼皮", "type":"material", "quality":"common" }
|
||
}
|
||
```
|
||
|
||
`src/game/Inventory.js`：
|
||
```js
|
||
// 最多 30 格
|
||
// add(itemId, qty)，remove(itemId, qty)，use(itemId)，equip(itemId)
|
||
// 满背包时返回特殊结果，由调用方触发语音提示
|
||
```
|
||
|
||
**交付物**
|
||
- `src/data/items.json`
|
||
- `src/game/Inventory.js`
|
||
|
||
---
|
||
|
||
### P3-06：背包态交互实现
|
||
|
||
**目标**
|
||
实现完整的背包态手势交互（按策划案 3.3 背包/物品操作态）。
|
||
|
||
**前置依赖**
|
||
P1-06，P3-05
|
||
|
||
**实现方式**
|
||
`src/state/BackpackState.js`：
|
||
```
|
||
上/下滑：切换物品
|
||
左滑：返回菜单态
|
||
右滑：切换分类（全部/装备/丹药/材料/其他）
|
||
单击：进入物品详情层，播报详细信息
|
||
双击：默认操作（使用/装备）
|
||
|
||
物品详情层：
|
||
右滑：打开操作子菜单（使用/装备/丢弃/放入交易）
|
||
左滑：返回背包列表
|
||
上/下滑：在子菜单中切换
|
||
双击：执行操作
|
||
```
|
||
|
||
**交付物**
|
||
- `src/state/BackpackState.js`（含物品详情子层）
|
||
|
||
**测试用例**
|
||
|
||
| # | 场景 | 预期 |
|
||
|---|------|------|
|
||
| 1 | 进入背包 | 播报"背包。第一件：[物品名]" |
|
||
| 2 | 单击一件装备 | 播报"铁剑，物理攻击+10，凡品。" |
|
||
| 3 | 双击续命丹 | 播报"你服下续命丹，气血恢复50点" |
|
||
| 4 | 右滑切分类 | 播报"丹药分类，共2件" |
|
||
| 5 | 背包满时拾取物品 | 播报"背包已满。获得灰狼皮。是否丢弃一件物品？" |
|
||
|
||
---
|
||
|
||
### P3-07：装备系统
|
||
|
||
**目标**
|
||
玩家可穿戴/脱下装备，装备效果即时反映到推导属性。
|
||
|
||
**前置依赖**
|
||
P2-01（属性系统），P3-05（物品数据）
|
||
|
||
**实现方式**
|
||
|
||
在 `Player.js` 中添加装备槽：
|
||
```js
|
||
this.equipment = { weapon: null, body: null, accessory1: null, accessory2: null };
|
||
|
||
// 穿戴时：player.physAtkBonus += item.physAtkBonus
|
||
// 推导属性（getter）自动反映变化
|
||
```
|
||
|
||
在 `BackpackState.js` 穿戴逻辑中：播报"你装备了铁剑。物理攻击力提升至30。"
|
||
|
||
**交付物**
|
||
- `Player.js` 装备槽逻辑
|
||
- 装备/脱下操作整合到 `BackpackState.js`
|
||
|
||
---
|
||
|
||
### P3-08：商店态实现
|
||
|
||
**目标**
|
||
实现 NPC 商店的完整交互（进入、浏览、购买）。
|
||
|
||
**前置依赖**
|
||
P3-03（对话态），P3-05（物品系统）
|
||
|
||
**实现方式**
|
||
|
||
在 `npcs.json` 中为张道长添加商品列表，对话选择"交易"后触发 `stateMachine.transition('shop', {npcId})`。
|
||
|
||
`src/state/ShopState.js`：
|
||
```
|
||
上/下滑：浏览商品
|
||
左滑：返回对话态
|
||
右滑：切换分类
|
||
单击：播报商品详情（名称、价格、效果）
|
||
双击：购买当前商品
|
||
→ 确认"购买续命丹×1，花费灵石20枚。剩余灵石：X枚。"
|
||
→ 灵石不足时播报"灵石不足。"
|
||
```
|
||
|
||
**交付物**
|
||
- `src/state/ShopState.js`
|
||
|
||
---
|
||
|
||
### P3-09：菜单态完善
|
||
|
||
**目标**
|
||
完善菜单态的全部 8 个菜单项，使其与实际游戏数据联动。
|
||
|
||
**前置依赖**
|
||
P1-09（菜单框架），P2-01（角色属性），P3-04（任务），P3-06（背包）
|
||
|
||
**实现方式**
|
||
完善各菜单项的双击行为：
|
||
- **角色信息**：播报真实属性（"练气X层，气血Y/Z，灵力A/B，根骨C..."）
|
||
- **修炼/突破**：播报当前经验和下一层需求，v0.3 不实现突破流程
|
||
- **背包**：切换到背包态
|
||
- **功法**：播报已学技能列表
|
||
- **装备**：播报当前穿戴状态
|
||
- **任务**：播报进行中任务列表和进度
|
||
- **社交**：播报"功能尚未开放"
|
||
- **系统**：播报版本号，提供"清除存档"操作
|
||
|
||
**交付物**
|
||
- 更新后的 `MenuState.js`
|
||
|
||
---
|
||
|
||
### P3-10：修炼与升级系统
|
||
|
||
**目标**
|
||
实现练气 1-3 层的自动升级（经验满自动提升）和打坐修炼（获取经验）。
|
||
|
||
**前置依赖**
|
||
P2-01（属性系统），P3-09（菜单）
|
||
|
||
**实现方式**
|
||
|
||
`src/game/Cultivation.js`：
|
||
```js
|
||
// 经验阈值：练气一层→二层=200，二层→三层=500
|
||
// 击杀怪物、完成任务后调用 player.gainExp(amount)
|
||
// 经验满时自动升层（练气1-3层自动，不需要主动突破）
|
||
// 升层时播报："恭喜，你突破至练气X层！气血上限提升！"
|
||
|
||
// 打坐修炼（在安全区或修炼室双击开始）：
|
||
// 每 30 秒播报一次"修炼中..."，每分钟获得经验 5 点（占位值）
|
||
// 单击可查看当前修炼进度
|
||
// 移动/遭遇打断修炼
|
||
```
|
||
|
||
**交付物**
|
||
- `src/game/Cultivation.js`
|
||
- 修炼状态整合到探索态（安全区内检测双击开始修炼）
|
||
|
||
---
|
||
|
||
### P3-11：v0.3 音频资源批量生成
|
||
|
||
**目标**
|
||
生成 v0.3 阶段所需的全部新增音频（约 50 个文件）。
|
||
|
||
**前置依赖**
|
||
P0-03，P0-05
|
||
|
||
**内容清单：**
|
||
|
||
NPC 对话语音（张道长音色，15 段）：
|
||
```
|
||
npc_zhang_first, "少侠，初来乍到吧？..."
|
||
npc_zhang_opt1, "请教修炼之法"
|
||
npc_zhang_opt2, "询问附近情况"
|
||
npc_zhang_quest, "镇北郊外近来妖兽横行..."
|
||
npc_zhang_accept, "好，老夫期待你凯旋。"
|
||
npc_zhang_decline, "无妨，有意时再来找老夫。"
|
||
npc_zhang_complete, "不错，你果然有几分资质..."
|
||
npc_zhang_daily_1, "少侠，今日修行如何？"
|
||
npc_zhang_daily_2, "此地灵气浓厚，适合打坐修炼。"
|
||
（+6 段其余对话选项和过渡语）
|
||
```
|
||
|
||
> 张道长用区别于旁白的另一参考音色（老者声线）
|
||
|
||
角色创建引导语音（旁白音色，10 段）：
|
||
```
|
||
char_create_name, "欢迎来到苍玄大陆。请为自己取一个道号。"
|
||
char_create_confirm, "道号——{X}，可对否？双击确认..."
|
||
char_create_element, "请选择你的灵根属性。上滑下滑切换，双击确认。"
|
||
char_create_fire, "火灵根。法术伤害见长，克金灵根。"
|
||
（+6 段其余灵根+出身介绍）
|
||
```
|
||
|
||
任务相关语音（10 段）：
|
||
```
|
||
quest_accept, "接取任务——清剿灰狼。前往镇北郊外，击败3只灰狼。"
|
||
quest_wolf_progress, "灰狼 {N}/3。"（需要 N=1,2 两段）
|
||
quest_wolf_done, "任务目标完成！请回去找张道长。"
|
||
quest_wolf_complete, "任务完成——清剿灰狼。获得经验200点，灵石50枚。"
|
||
（+6 段其余通用任务语音）
|
||
```
|
||
|
||
物品名称语音（5 段）：
|
||
```
|
||
item_iron_sword, "铁剑"
|
||
item_cloth_robe, "布衣"
|
||
item_healing_pill,"续命丹"
|
||
item_spirit_pill, "回灵丹"
|
||
item_wolf_pelt, "灰狼皮"
|
||
```
|
||
|
||
出生叙事（旁白音色，1 段 15-20s）：
|
||
```
|
||
birth_narration, "苍玄历某年。灵气异动，上古秘境重现。你，一个普通的修士，就此踏上了漫长的修仙之路……"
|
||
```
|
||
|
||
**10.2 张道长参考音色选定**（与 P0-05 相同流程）：
|
||
- 生成 3 段老者声线候选，评估后确定 `assets/voice/ref/old_man.wav`
|
||
|
||
**交付物**
|
||
- `assets/voice/*.mp3`：约 50 条新增语音
|
||
- `docs/音色选定记录.md` 更新：记录张道长音色选择
|
||
|
||
---
|
||
|
||
### P3-12：v0.3 音频质检与验收
|
||
|
||
与 P1-11、P2-09 相同流程。重点额外检查：
|
||
- 旁白音色与张道长音色**可被明显区分**
|
||
- 对话语音的语气与角色性格一致（老者：沉稳慈祥，不急促）
|
||
- 出生叙事：语速、停顿、情绪契合开场氛围
|
||
|
||
**交付物**
|
||
- `docs/音频质检_v03.md`
|
||
|
||
---
|
||
|
||
### P3-13：教学任务完整流程串联
|
||
|
||
**目标**
|
||
确保所有模块正确连接，玩家能完整走通 MVP 核心路径。
|
||
|
||
**前置依赖**
|
||
P3-01 ～ P3-12 全部完成
|
||
|
||
**核心路径验证：**
|
||
|
||
```
|
||
启动游戏
|
||
→ 角色创建（选道号、灵根、出身）
|
||
→ 出现在清风镇广场
|
||
→ 找到张道长（切换焦点→双击进对话）
|
||
→ 接取"清剿灰狼"任务
|
||
→ 前往镇北郊外（移动）
|
||
→ 触发遭遇战（野兔精或灰狼）
|
||
→ 战斗胜利（3只灰狼）
|
||
→ 任务目标完成播报
|
||
→ 返回广场找张道长
|
||
→ 交任务，领奖励
|
||
→ 菜单查看角色信息（级别/经验更新）
|
||
```
|
||
|
||
**交付物**
|
||
- 无新代码，此任务为集成验证
|
||
- `docs/MVP核心路径测试记录.md`：记录走查结果
|
||
|
||
---
|
||
|
||
### P3-14：MVP 完整体验测试与评估
|
||
|
||
**目标**
|
||
在真实移动设备上进行完整的 MVP 用户测试，评估核心假设是否成立。
|
||
|
||
**前置依赖**
|
||
P3-13
|
||
|
||
**测试方案**
|
||
|
||
**A. 自测核查单（开发者完成）**
|
||
|
||
| 类别 | 检查项 | 结果 |
|
||
|------|-------|------|
|
||
| 启动 | iOS Safari + Android Chrome 均能正常启动 | |
|
||
| 音频 | 全程无无声卡住现象 | |
|
||
| 手势 | 6 种手势识别准确率主观 > 90% | |
|
||
| 任务闭环 | 核心路径可从头走到尾 | |
|
||
| 存档 | 刷新后进度保留 | |
|
||
| 边界 | 背包满、灵力不足、触发危险移动均有正确反馈 | |
|
||
|
||
**B. 外部用户测试（≥ 2 人，未参与开发）**
|
||
|
||
观察要点（不提示，只看）：
|
||
1. 启动后能否在 1 分钟内理解"手势=操作"
|
||
2. 能否不看屏幕完成移动和基本战斗
|
||
3. 能否找到并接取任务
|
||
4. 对音频质量的主观感受
|
||
|
||
收集反馈：
|
||
- 最困惑的操作是什么？
|
||
- 最难听清的语音是什么？
|
||
- 整体沉浸感（1-5分）
|
||
|
||
**交付物**
|
||
- `docs/MVP用户测试报告.md`：测试结果 + 问题列表 + 优先级排序
|
||
|
||
**验收标准（MVP 完成门禁）**
|
||
- 外部测试者能在无提示下完成"接任务→打怪→交任务"闭环
|
||
- 无 P0/P1 级别的体验缺陷（无声死锁、崩溃、任务无法完成）
|
||
- 整体沉浸感评分平均 ≥ 3 / 5
|
||
|
||
---
|
||
|
||
## 附录 A：任务依赖关系总览
|
||
|
||
```
|
||
P0-01 ──→ P0-02
|
||
P0-03 ──→ P1-10, P2-08, P3-11
|
||
P0-04 ──→ P1-07, P2-01, P2-02, P2-03
|
||
P0-05 ──→ P1-10
|
||
|
||
P1-01 ──→ P1-02, P1-03, P1-04
|
||
P1-04 ──→ P1-05
|
||
P1-05 ──→ P1-06
|
||
P1-02 ──┐
|
||
P1-03 ──┤
|
||
P1-05 ──┤─→ P1-06 ──→ P1-07 ──→ P1-08 ──→ P1-09
|
||
P1-10 ──→ P1-11 ──→ P1-12
|
||
|
||
P1-06 ──→ P2-04
|
||
P2-01 ──┐
|
||
P2-02 ──┤─→ P2-05 ──→ P2-06 ──→ P2-10
|
||
P2-03 ──┘
|
||
P2-04 ──→ P2-07
|
||
P2-08 ──→ P2-09 ──→ P2-10 ──→ P2-11
|
||
|
||
P2-01 ──→ P3-01
|
||
P3-02 ──→ P3-03 ──→ P3-04
|
||
P3-05 ──→ P3-06, P3-07, P3-08
|
||
P3-03 ──→ P3-08
|
||
P1-09 ──→ P3-09
|
||
P3-01 到 P3-12 全完成 ──→ P3-13 ──→ P3-14
|
||
```
|
||
|
||
---
|
||
|
||
## 附录 B：各阶段音频资产汇总
|
||
|
||
| 阶段 | TTS 语音 | 音效 | 氛围音 | BGM | 合计预生成文件 |
|
||
|------|---------|------|-------|-----|-------------|
|
||
| v0.1 | 30 | 0 | 2 | 1 | ~33 |
|
||
| v0.2 (增量) | 40 | 6 | 0 | 1 | ~47 |
|
||
| v0.3 (增量) | 50 | 0 | 0 | 0 | ~50 |
|
||
| **v0.3 累计** | **~120** | **6** | **2** | **2** | **~130** |
|
||
|
||
> UI 音效（13种）通过 Web Audio API 实时合成，不计入预生成文件。
|
||
|
||
---
|
||
|
||
## 附录 C：v0.2 初始角色数值（固定值，v0.3 才做角色创建）
|
||
|
||
| 属性 | 值 | 推导结果 |
|
||
|------|----|---------|
|
||
| 灵根 | 火 | 同系功法伤害×1.2 |
|
||
| 等级 / 境界 | 1 / 练气一层 | — |
|
||
| 根骨 | 10 | 气血上限=150，物理攻击=20，物理防御=15 |
|
||
| 灵力 | 8 | 灵力上限=104，法术攻击=16 |
|
||
| 悟性 | 8 | — |
|
||
| 神识 | 6 | 法术防御=9 |
|
||
| 机缘 | 5 | — |
|
||
| 初始灵石 | 50 | — |
|
||
| 初始装备 | 无 | — |
|