guide层v1: 全局向导交互层落地(状态签名earcon/turn cue/静默看门狗/纠错) + 6游戏接线 + 8句向导语音 + 测试全绿
- engine/guide.js 运行时合成8个签名earcon(方法论L2硬参数)，off档零定时器，插播queue不顶对白 - settings: guide三档(full/standard/off默认full) + 语速2.2视障档；audio: isVoicePlaying()/setRateBoostEnabled() 清两个已知问题 - 6游戏按schemes§2接线: storyline看门狗+无效手势纠错、simon免扣重听看门狗、escape turn cue+提前卡关提示、rhythm gd_answer/gd_miss+结算看门狗+快进豁免、space首撞指令提示+结算看门狗、rpg格挡纠错+60s催促+状态签名 - 大厅设置面板+向导文档(14-guide-layer.md)+00-global-ux §6；R5台词表补4条一致性 - 试玩转写含向导事件；6 playtest(guide=off断言零改动)+guide.test(34断言)+资产终检全绿
This commit is contained in:
SoundGame Dev
@@ -1,7 +1,7 @@
|
||||
# 00 · 全局交互规范（Global UX）
|
||||
|
||||
> **给开发者的实现要点摘要**
|
||||
> 1. 设置项（voice / speed / bgm）只在大厅页用 `<select>` 可视化 UI 修改，存 `localStorage["soundgame.settings"]`，由 `engine/settings.js` 管理；游戏启动时只读生效，游戏内不提供修改入口（菜单里只播报当前值）。**R1 已落地，本文 §1/§2/§4 已按实现修订（R2 修订版）。**
|
||||
> 1. 设置项（voice / speed / bgm / guide）只在大厅页用 `<select>` 可视化 UI 修改，存 `localStorage["soundgame.settings"]`，由 `engine/settings.js` 管理；游戏启动时只读生效，游戏内不提供修改入口（菜单里只播报当前值）。**R1 已落地，本文 §1/§2/§4 已按实现修订（R2 修订版）；R7 增补 guide 设置与向导层（§6，见 14 号文档）。**
|
||||
> 2. 所有提示音反馈改为震动：`engine/haptics.js`（**已实现**，震型名小写：`confirm/error/success/warning/swipe/heartbeat`）；iOS Safari 不支持时**静默降级，绝不回退到提示音**。
|
||||
> 3. 旁白全部整句预生成：禁止数字/碎片拼接（音色漂移根因），每款游戏旁白固定同一 `speaker` + 同一 `instruct` 常量。
|
||||
> 4. 手势全局约定：上滑=帮助/状态、下滑=菜单、单击=确认/继续、双击=重听、左右滑=选择/移动；以滑动为核心玩法的游戏可偏离（见 §5 豁免表），但必须在开场交互教学中讲清。
|
||||
@@ -11,25 +11,26 @@
|
||||
|
||||
## 1. 设置系统（已实现：engine/settings.js + 大厅设置面板）
|
||||
|
||||
### 1.1 三个设置项的精确语义
|
||||
### 1.1 四个设置项的精确语义
|
||||
|
||||
| 设置项 | 取值（实现值） | 精确语义 |
|
||||
|---|---|---|
|
||||
| `voice` | `"female"`（默认）/ `"male"` | 切换 **voice 资产目录**。`play('voice/xxx')` 实际解析为 `audio/voice/<gender>/xxx.{ogg,m4a,mp3,wav}`，找不到时**回退平铺的 `audio/voice/xxx.*`**（已实现；storyline 角色台词靠此回退）。两性别的 id 集合由资产侧保证完全一致（见 docs/audio/round1-report.md），因此不做"回退另一性别"的逻辑。 |
|
||||
| `speed` | `1.0`（默认）/ `1.35` / `1.7` | **只作用于 voice 层**的 `playbackRate`（创建 voice source 时实时读取，**从下一句开始生效**，正在播的句子不变速）。BGM、sfx 速率不变。TTS 一律按 1.0 语速生成；`instruct` 里禁止出现语速描述词。 |
|
||||
| `speed` | `1.0`（默认）/ `1.35` / `1.7` / `2.2` | **只作用于 voice 层**的 `playbackRate`（创建 voice source 时实时读取，**从下一句开始生效**，正在播的句子不变速）。BGM、sfx 速率不变。TTS 一律按 1.0 语速生成；`instruct` 里禁止出现语速描述词。**2.2 档为视障档**（R7 增补：资深读屏用户听速 250+ WPM，见 research/01-literature/03）。 |
|
||||
| `bgm` | `1.0`（默认）/ `0.3` / `0` | BGM 层独立增益总线系数。`0` = 不加载、不播放任何 `bgm/` 资产（`_playBgm` 短路），ducking 逻辑保持原样。改设置即时生效（已实现 subscribe 机制）。 |
|
||||
| `guide` | `"full"`（默认）/ `"standard"` / `"off"` | **向导帮助等级**（R7 增补，engine/guide.js 实时读取，见 §6 与 14 号文档）：`full`=签名 earcon+向导语音+震动（新手全托管）；`standard`=只留 earcon+震动（无向导语音，尊重专家）；`off`=全静且**不挂任何看门狗定时器**（老手/回归测试）。 |
|
||||
|
||||
存储：localStorage key = `soundgame.settings`，值形如：
|
||||
|
||||
```json
|
||||
{ "voice": "female", "speed": 1.0, "bgm": 1.0 }
|
||||
{ "voice": "female", "speed": 1.0, "bgm": 1.0, "guide": "full" }
|
||||
```
|
||||
|
||||
注意（与设计初稿的差异，**以实现为准**）：`speed`/`bgm` 存**数值**（1.0/1.35/1.7、1.0/0.3/0），不是字符串枚举；`engine/settings.js` 对非法键/值逐项丢弃，永不炸。
|
||||
|
||||
### 1.2 修改入口：只在大厅页（已实现）
|
||||
|
||||
- `web/index.html` 大厅已有"设置"面板：三个 `<select>`（旁白音色：女声/男声；语速：正常/快/特快；背景音乐：正常/小/关闭），变更即 `settings.set()` 写 localStorage。
|
||||
- `web/index.html` 大厅已有"设置"面板：四个 `<select>`（旁白音色：女声/男声；语速：正常/快/特快/特快++；背景音乐：正常/小/关闭；向导帮助：详细/只听提示音/关闭），变更即 `settings.set()` 写 localStorage。
|
||||
- 试听句（设计有、R1 未做）：变更后播一句样例语音演示 voice+speed，列为 R3 打磨项，非阻塞。
|
||||
- 游戏内：**只读**。`audio.js` 自动应用三项设置，游戏代码无需改动；下滑呼出的菜单里用语音播报当前设置（如"当前：女声，正常语速"），并提示"请回到大厅修改设置"。
|
||||
|
||||
@@ -172,3 +173,13 @@ PUT /api/progress { game, data } (Bearer) -> 200 { ok, game }
|
||||
- 任何游戏里，**做了一个手势 3 秒内必须有反馈**（引擎内置震动 + 内容音/语音），被判定无效的手势给 `error` 震动；教学阶段除外（教学里错误手势给纠正语音）。
|
||||
- 单击有 ~300ms 引擎级延迟：即时判定（格挡、节奏打击）一律绑滑动或双击，单击只用于非即时操作（确认、检查、菜单）。新设计继续遵守。
|
||||
- 结算画面统一：单击=再来一局，下滑=菜单（回大厅）。教学可跳过：任何游戏的引导阶段，下滑=跳过引导（首次强制完整引导的标志位存进度里）。
|
||||
|
||||
## 6. 向导层（R7 增补，已实现：engine/guide.js）
|
||||
|
||||
> 设计裁定与台词表全录：[14-guide-layer.md](14-guide-layer.md)。本节只列与全局约定交叉的部分。
|
||||
|
||||
1. **四个全局机制**（方法论 research/02 §3 的 L3/L4 落地）：状态签名 earcon（6 状态+2 功能音，运行时合成，全项目统一词表）；回合标记 `turn`（等待输入开始处）；静默看门狗（等待输入无操作→轻提醒→升级上下文提示，用尽即停不轰炸）；纠错 `error`（error 震+一句"该做什么"）。
|
||||
2. **等级语义**：`full`=earcon+向导语音+震动；`standard`=earcon+震动（**无向导语音**）；`off`=全部 no-op 且不注册定时器。向导语音一律 `queue:true`，**绝不顶掉在播对白**（A3 信息分层）。
|
||||
3. **与既有约定的边界**：向导不改变任何手势映射与玩法判定；向导震动只用既有震型（confirm/error/nudge 复用），不新增语义震；向导 earcon 是**系统音**（P2 系统音/叙事音分离），不占用 sfx 内容音语义域。
|
||||
4. **看门狗通用参数**（各游戏已按此接）：第 1 级 8~10s（nudge+一句提示），第 2 级 20~25s（上下文提示/复述），之后停止；玩家任意手势复位。escape 三级卡关计时器（60/120/180s）保持独立，不受影响。
|
||||
5. **测试约定**：既有 playtest 一律 `settings.set({guide:'off'})` 验证纯玩法逻辑；向导行为由 `web/harness/guide.test.mjs`（full 档）覆盖。
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
# 14 · 向导交互层设计裁定（v1 基线）
|
||||
|
||||
> 依据：research/02-methodology/methodology.md §3（L3 状态层 / L4 引导层）→
|
||||
> research/03-schemes/schemes.md §1/§2（实施蓝图，唯一事实源）。
|
||||
> 本文存档 v1 已落地的裁定与新增语音资产台词表，供后续轮次回溯。
|
||||
> 实现载体：`web/engine/guide.js`（引擎向导模块）+ 各游戏 game.js 接线。
|
||||
|
||||
## 1. 裁定摘要
|
||||
|
||||
| # | 裁定 | 内容 |
|
||||
|---|---|---|
|
||||
| 1 | 分期 | v1 只做「全局基线」= 引擎向导层 + 逐游戏接线；场景参数包（A 通勤/B 摸鱼/C 睡前/D 下班）与人设旋钮在试玩验证后分期（schemes §3）。 |
|
||||
| 2 | 等级 | `settings.guide`：`'full'`（默认，earcon+语音+震动）/ `'standard'`（earcon+震动，无语音）/ `'off'`（全静 no-op，**不挂任何定时器**）。大厅设置面板「向导帮助：详细/只听提示音/关闭」。 |
|
||||
| 3 | earcon | 8 个签名（6 状态 menu/explore/battle/choice/settle/danger + 2 功能 turn/nudge）**全项目统一**，全部运行时 WebAudio 合成（零资产、可复现）；总长 0.25~0.4s、单音 ≥0.08s、125Hz~5kHz、总增益 ≈0.12；家族=波形音色、子类=节奏轮廓（schemes §1.4）。 |
|
||||
| 4 | 语音纪律 | 向导插播语音一律 `queue:true`（等当前对白播完），**绝不顶掉正在播的内容**；抉择提示（storyline p*）播完即可选的等待点不插任何语音。 |
|
||||
| 5 | 看门狗 | 统一模板：静默 N 秒 → nudge 轻 earcon（+ full 档语音）→ 二次升级播上下文提示 → 级数用尽自动停止；任何手势/向导动作复位。escape 的三级卡关骨架保留，仅加「连续撞墙 ≥2 次 → full 档阈值提前一级」。 |
|
||||
| 6 | 引擎配套 | `audio.isVoicePlaying()` 公开只读 API（收编 5 处私有 `_voice` 读）；`audio.setRateBoostEnabled(bool)` 长按快进 per-game 开关（rhythm/space 对局期豁免）；`settings.speed` 增加 2.2 档（视障档，250+ WPM）。 |
|
||||
| 7 | 语义分工铁律 | 语音说「你要做什么」、earcon 说「哪类事/哪个状态」、BGM 说「宏观状态」、震动说「刚才那下对不对」——向导层不越界（L2 铁律：earcon 只做粗标记，语义靠语音）。 |
|
||||
|
||||
## 2. 逐游戏接线裁定（v1 落地范围）
|
||||
|
||||
| 游戏 | 接线 |
|
||||
|---|---|
|
||||
| storyline | W1/W3 静默看门狗 [8s]=nudge+`gd_continue`、[20s]=复用 `playHelpAndResume`；选择节点外左右滑的静默 return 处加 error 震+`gd_invalid`；抉择态（p* 播完）不插语音不挂看门狗；状态签名 explore/menu 与状态 BGM 同点。 |
|
||||
| simon | input 看门狗 [10s]=nudge+`gd_relisten`、[25s]=免扣机会自动重听（每局 2 次）；`your_turn` 泛化为 turn earcon（每轮，第 1 轮保留原语音）；状态签名 settle/menu。 |
|
||||
| escape | REOPEN 提示播完与引导步解锁给 turn cue；连续撞墙 ≥2 次 → full 档卡关三级阈值提前一级；其余（wrong/blunt/stuck/nav）保持既有完备体系。 |
|
||||
| rhythm | 每曲首次领奏→应答切换推 `gd_answer`（谱面排程处入 `_timed`）；连续 2 Miss 播 `gd_miss`（queue 插播，同曲一次）；结算链换 `_speakGuarded`；main 演奏期 `setRateBoostEnabled(false)`；状态签名 menu/battle/settle。 |
|
||||
| space | 对局第 1 次受击（保护期外）追加 `gd_hit_hint`；结算链换 `_speakGuarded`；对局期 `setRateBoostEnabled(false)`；状态签名 battle/menu/settle。 |
|
||||
| rpg | 格挡窗口内做错手势 → error 震+`gd_parry_miss`（每局一次）；PLAYER_SELECT 挂看门狗 [60s]=nudge+`gd_stall`；状态签名 explore/battle/menu/settle 与四状态 BGM 同点补齐。 |
|
||||
|
||||
## 3. 新增语音资产台词表（8 句 ×2 性别 = 16 文件）
|
||||
|
||||
定稿依据 schemes.md §1.5，台词全文一字不改；speaker/instruct 沿用各游戏旁白常量
|
||||
（见 `tools/gen_voice_dual.py` SPEAKERS 与各 `_XXX` pair）：
|
||||
|
||||
| 游戏 | id | 全文 | 触发 | female speaker / instruct | male speaker / instruct |
|
||||
|---|---|---|---|---|---|
|
||||
| storyline | `gd_continue` | 轻触屏幕，继续。 | W1/W3 叙事节点播完静默 8s（看门狗第 1 级） | Vivian / _SL_NARR[1] | Uncle_Fu / _SL_NARR[0] |
|
||||
| storyline | `gd_invalid` | 这个操作在这里用不上。 | 无效手势（选择节点外左右滑静默 return，同局限次） | Vivian / _SL_NARR[1] | Uncle_Fu / _SL_NARR[0] |
|
||||
| simon | `gd_relisten` | 需要的话，双击可以重新听一遍序列。 | input 阶段 10s 无输入（不改变重听扣机会规则） | Serena / _SIMON | Uncle_Fu / _SIMON |
|
||||
| rhythm | `gd_answer` | 现在跟着我打。 | 每曲首次领奏→应答切换 | Vivian / _RHY | Uncle_Fu / _RHY |
|
||||
| rhythm | `gd_miss` | 慢了半拍，下一小节跟上我就行。 | 连续 2 次 Miss（同曲限 1 次，queue 插播） | Vivian / _RHY | Uncle_Fu / _RHY |
|
||||
| space | `gd_hit_hint` | 被撞了。听方位，同向滑动就能拨开。 | 对局第 1 次受击（保护期外，同局 1 次） | Serena / _SPC | Uncle_Fu / _SPC |
|
||||
| rpg | `gd_parry_miss` | 前摇声起的时候双击，才能格挡。 | 格挡窗口内做错手势（每局限次） | Serena / _RPG | Uncle_Fu / _RPG |
|
||||
| rpg | `gd_stall` | 想好了吗？左右滑动选择，单击出手。 | PLAYER_SELECT 60s 无输入 | Serena / _RPG | Uncle_Fu / _RPG |
|
||||
|
||||
资产落位：`web/<game>/audio/voice/{female,male}/gd_*.{ogg,m4a}`（管线
|
||||
`tools/gen_voice_dual.py --game <g> --only gd_xxx` 生成 + `--convert` 落盘，
|
||||
双格式配对由 `tools/check_all_assets.py` 终检保证）。
|
||||
|
||||
## 4. 已知边界与后续候选
|
||||
|
||||
- `onceKey` 语义为「同局（游戏会话）一次」；schemes §1.5 中 storyline `gd_invalid`
|
||||
「同局限 2 次」、rpg `gd_parry_miss`「每场战斗 1 次」为更细粒度限次，v1 统一收敛到
|
||||
onceKey（一次教学提示足矣），如试玩反馈不足再引入 per-run 限次 API。
|
||||
- 教学义务（schemes §1.4「full 档开场教学带教签名 earcon」）：v1 未在各游戏教学链中
|
||||
逐个口播签名音，列为 v2 候选（需逐游戏改教学台词，涉及台词表返工）。
|
||||
- 向导插播语音目前挂在引擎 voice 队列；若游戏层 `stopVoice()` 会顺带丢弃排队中的
|
||||
向导句（作废语义，可接受）。
|
||||
Reference in New Issue
Block a user