# R5 开发提示（给《剑与声》开发 agent · 返工注意级）

> 定位：RPG 开发已在并行进行。以下**不是推翻性意见**，是 R3/R4 审查中发现的共性问题在 RPG 语境下的对应检查点——如果你的实现已经正确处理，忽略即可；如果需要返工，按对应条目修。设计依据：05-rpg.md / 05-rpg-chapter1.md / 05-rpg-ch1-voice-ids.md / 05-rpg-addendum.md / 00-global-ux.md。

## 1. 已验证可照抄的健壮性模式（escape/simon/rhythm/space 四款一致落地）

1. **语音链看门狗**：所有"语音播完才推进流程"的地方都要双通道（onComplete + 超时兜底，二者先到先触发、只触发一次），参考 simon `_speakGuarded`。RPG 的场景切换、战斗回合开场、商店对话都依赖语音推进，缺看门狗会在资产缺失/解码失败时卡死整局。
2. **会话令牌**：重开/跳场景时 `session++` 使旧计时器与语音链回调失效。RPG 状态多（探索/战斗/商店/菜单），比前四款更需要。
3. **打断即作废**：状态切换入口统一 `stopVoice()`，不要依赖逐条清理。

## 2. 菜单与手势冲突（round2 裁决② + round3-4 附裁 A）

- RPG 是**菜单豁免游戏**：探索态菜单=左右滑切换+单击确认（00 §5.2），战斗态下滑=逃跑不设菜单。不要套用 escape/simon 的"单击循环+双击确认"。
- ch1 台词表 `sys_menu` 文案（"菜单。左右滑选择，单击确认。"）与豁免口径一致，**不用改**。
- 若你在菜单里加了"保存并回大厅"项：保存成功的反馈=`sys_saved` 语音 + `pickup` 震动，不要用提示音。

## 3. 导航/播报语音的末位语境检查（rhythm 裁定①的教训）

rhythm 在"最后一首"右滑播了"还没解锁"造成语义错位。RPG 同类风险点：

- **章末**：第三章打完 Boss 后播"下一章"类语音会错位——终章结算需单独的完结句（ch3 台词表补发时会含 `evt_ch3_end`，若你先行实现，先用 `btl_win` + `evt_ch1_end` 模式临时顶替，勿复用"前往下一章"句）。
- **场景图边界**：village 的 `back`、boss1 无选项等死端，播报选项时不要念出"返回"之外不存在的去向。
- **商店已购/缺钱的播报**已在台词表（shop_owned/shop_poor），按语境选句，别统一播 shop_poor。

## 4. 震动落点（按 05-rpg-addendum §1 总表 + 两条新收紧）

- 前摇窗口开启震 `beat`（有声敌人）/ `danger`+`heartbeat`（无声敌人）的通道分工**不要混用**：danger 专属于无声威胁。
- 新增收紧（round3-4 裁定④同款）：200ms 去抖——格挡成功的 `confirm` 若与 gesture.js 内置双击 confirm 同刻，只震一次；升级 success 与战斗胜利播报前震动同理。
- iOS 无震动：无声敌人不可格挡是已知设计代价（addendum §2.2），**防御指令必须可用且有效**（减伤 50% 不依赖时机），这是 iOS 兜底，不要在任何分支里把防御禁用。

## 5. 音频层叠（addendum §3 的实现要求）

- 场景 amb_* **不走 bgm 层**（会被 bgm=0 设置误杀，且与战斗 BGM 冲突）：用 `audio._load` + 手动 BufferSource loop 接 `_sfxBus`，rhythm `_startBgm`/`_scheduleSfx` 的手动总线接法可直接参考。
- 战斗 BGM（bgm/battle、bgm/boss）走正常 bgm 层，受 bgm 设置控制；进出战斗 crossfade 切换即可。
- 注意 decodeAudioData 内存：amb 循环 6-10s、BGM 60-90s，全章节资产控制在 ~30MB 压缩内（web-engine-api §移动浏览器的坑 7）。

## 6. 存档（05-rpg-chapter1.md §6 + 审查共性）

- `summary` 必须随每次保存更新（大厅卡片直接显示）；格式"第X章·场景名 · LvN · 金币M"。
- 保存时机四件套：场景切换/战斗结算/商店交易/菜单保存——**战败重生也算战斗结算**，要存（否则死亡丢进度，比死亡本身更劝退）。
- localStorage 与服务器双写，离线静默（四款游戏的 `_putProgress` 模式照抄）。
- 继续/新开二选一（sys_continue_ask）：右滑=新游戏是**破坏性操作**，建议加一次确认（单击确认句可用现有 `sys_new_game` 前的自答："右滑确定重新开始？再右滑确认。"——如需新台词列入 ch2/3 补录，先用现有句拼接流程也行）。

## 7. 教学战（05-rpg-chapter1.md §5.2）

- 锁血保护（HP 最低 1）别忘了在 `_resolve` 类函数里实现为 clamp，不是免疫——教学战要让玩家**看到**掉血才理解格挡的价值。
- 教学句 tut_b1-b5 的触发点：tut_b1 在首次 ENEMY_TELEGRAPH 前、tut_b2 与前摇音**同时**（这是唯一允许语音与前摇叠放的位置，设计如此）、tut_b3 格挡成功后。