# 《声命线》(storyline) — 末世互动广播剧 设计文档

- 包名：`com.soundgame.storyline`
- 代码：`app/src/storyline/java/com/soundgame/game/StorylineGame.kt`
- 生成脚本：`app/src/storyline/gen/`（`gen_voice.py` / `gen_sfx.py` / `convert.sh` / `make_cover.py`）

大停电后第 30 天，前急救员林晚靠一台旧收音机寻找妹妹林晨，对抗抢掠者"猎狗"。
3 幕、8 个抉择点、4 种结局，单局 5-7 分钟。

## 手势映射

| 手势 | 剧情模式 (STORY) | 菜单模式 (MENU) |
|---|---|---|
| 单击 | 继续剧情（对白播完才生效）/ 结局后重开 | 返回故事 |
| 双击 | 重听当前节点全部台词 | 重播菜单语音 |
| 左滑/右滑 | 选择节点做抉择（提示音播完才生效，播放中会缓存 `pendingChoice`） | 左滑=重新开始；右滑=返回 |
| 上滑 | 帮助 + 当前幕进度，随后自动重播当前节点 | 听帮助，随后回菜单 |
| 下滑 | 呼出菜单 | — |

实现要点：

- 游戏是 `Mode.STORY / Mode.MENU` 双模式 + 剧情节点表驱动，未用 `GameEngine` 基类。
- `playSeq` 用 `seqToken` 做打断作废：任何重播/菜单/重开都会 `seqToken++`，
  旧语音链的 `onComplete` 回调因此失效，不会错序推进。
- 对白播放中单击**不**跳节点（防误触）；选择提示音播放中的滑动会被缓存，
  播完立即生效（`choiceArmed` / `pendingChoice`）。
- `onStart` 里以音量 0 预播 `sfx/ui_confirm` 预热 SoundPool。

## 剧情树

节点 id 即资产文件名前缀（`voice/n00_intro.ogg` 等）。`◆` 为选择节点，
`【标记】`为选择写入的剧情标记，`※` 为结局。

```
n00 开场+教学 ──> n01 地铁站醒来 ──> n02 ◆p1 检查收音机 / 摸黑找出口
                                   ├─ 左: n03 收音机(林晨录音) ─┐
                                   └─ 右: n04 出口(红漆警告) ──┤
                                                               v
                              n06 口哨包围 <── n05 避难所广播(坐标37.5)
                                   │
                              n07 ◆p2 钻通风管 / 尸体堆装死
                                   ├─ 左: n08 通风管 ──────────┐
                                   └─ 右: n09 装死(听到陷阱情报) ┤   【knowTrap 死标记，见缺陷】
                                                               v
                        n10 ◆p3 酸雨夜，哭声：查看 / 不理会
                           ├─ 左: n11 ◆p4 小满：带上他 / 留下食物
                           │        ├─ 左: n12 带上小满 【companion=true】 ─┐
                           │        └─ 右: n13 独自上路 ──────────────────┤
                           └─ 右: n14 无视哭声 ──────────────────────────┤
                                                                         v
                        n15 ◆p5 断桥：涵洞 / 钢索
                           ├─ 左: v_culvert → n16 / n16b(带小满版) ──┐
                           └─ 右: v_cable   → n17 / n17b(带小满版) ──┤
                              （v_* 虚拟节点由 resolve() 按 companion 解析）
                                                                     v
                        n18 ◆p6 猎狗索坐标：交出 / 周旋
                           ├─ 左: n19 交出坐标 【betrayed=true】 ──> n20 ◆p7
                           │        ├─ 左: n21 追上去警告 ──> ※e2 代价
                           │        └─ 右: 自己逃命 ────────> ※e3 孤声(坏结局)
                           └─ 右: n22 扬沙脱身(中弹) ──> n23 ◆p8 广播频道
                                    ├─ 左: n24 公开频道 ──> ※e4 静默
                                    └─ 右: n25 加密频段 ──> ※e1 黎明(好结局)
                                                              （companion 时追加
                                                               e1_child 彩蛋台词）
```

三幕划分（`actOf()`，用于上滑报进度）：n00–n09 第一幕（地铁站与街面），
n10–n17b 第二幕（雨夜与断桥），n18 起及所有结局 第三幕（广播塔）。

## 角色音色分配（gen_voice.py）

| 角色 | speaker | instruct 变体 |
|---|---|---|
| 旁白 | Uncle_Fu（低沉醇厚中年男声） | NARR 冷静苍凉 / NARR_WARM 转温暖 / NARR_COLD 冷漠空洞 / NARR_EPIC 悲壮 |
| 林晚（主角） | Serena（温暖柔和年轻女声） | LIN_CALM 虚弱强撑 / LIN_SOFT 温柔坚定 / LIN_CRY 哭腔 / LIN_RUN 奔跑喘息 / LIN_SHOUT 嘶哑呼喊 / LIN_LOW 压低克制 |
| 猎狗（反派） | Dylan（北京话年轻男声） | DOG_PLAY 阴冷戏谑 / DOG_COLD 残忍带杀气 |
| 小满 / 林晨 / 广播 | Vivian（明亮年轻女声） | KID 稚嫩童声 / CHEN 急切压低（电台感） / BCAST 机械无感情 |

无线电失真不在 TTS 侧做：`convert.sh` 转码时对 `n03_msg` / `n05_bcast`
两条加 ffmpeg 带通（highpass 400Hz + lowpass 3200Hz + 压缩器）模拟电台。

## 资产清单

| 层 | 数量 | 内容 |
|---|---|---|
| voice | 48 | 系统语音 5（help/status1-3/menu）+ 选择提示 8（p1-p8）+ 剧情 30 + 结局 5 |
| sfx | 12 | ui_confirm, ui_menu, heartbeat, radio_static, whistle, footsteps, rubble, water, gunshot, struggle, wind, signal_beep（全部程序合成） |
| bgm | 1 | dark_drone.ogg（Mureka 生成，117s 无缝循环；原程序合成版备份在 tools/bgm_backup/） |

## 已知缺陷 / 遗留线索

- **`knowTrap` 是死标记**：`choose()` 里 `when (nodeId)` 的 `"n09"` 分支永远不会
  命中——`choose` 只在选择节点被调用，而 n09 不是选择节点（它是 n07 抉择的
  目标节点）。也就是说"装死听到北区陷阱情报"这个情报没有任何后续剧情消费它。
  修复方向：把判定移到 `playNode("n09")` 处，或在 n10/n18 处消费该标记。
- **`betrayed` 只写不读**：n18 交出坐标后标记置位，但后续节点没有任何分支
  读取它（e2/e3 的分化完全由 n20 的抉择决定）。可用于让旁白在结局前追加
  一句"赎罪"差分。
- 菜单模式下双击重播菜单语音，但如果菜单语音正在播则无响应（`voicePlaying`
  守卫），手感上像"双击失灵"，属有意为之。
- 结局后任意单击直接重开，没有确认；误触会丢失当前结局画面（音频游戏
  影响较小）。

## 调参入口

| 位置 | 参数 | 控制什么 |
|---|---|---|
| `StorylineGame.nodes` | 整张剧情表 | 节点增减、分支结构、台词文件映射 |
| `gen_voice.py` `LINES` | 台词/instruct | 文案与语气 |
| `gen_voice.py` `CHUNK = 6` | TTS 批量大小 | 显存/吞吐 |
| `gen_sfx.py` 各函数 | 合成参数 | 音效质感（采样率 24kHz，峰值归一 0.85） |
| `gen_sfx.py` `bgm_drone()` | 程序合成 BGM | 已被 Mureka 版替换，仅留作备份复现 |
| `convert.sh` | `-q:a 4`（voice/sfx）/ `-q:a 3`（bgm） | ogg 码率/体积 |
| 引擎层 | `playBgm` fadeMs=800 | BGM 淡入淡出时长 |