SoundGame/docs/architecture.md

SoundGame — 架构文档

本文档描述共享引擎（app/src/main/）的内部实现与设计决策。 如何基于引擎开发新游戏见 docs/engine-api.md（面向使用的 API 手册）； 本文面向需要读懂/改动引擎本身的人。

模块划分

app/src/main/java/com/soundgame/
├── MainActivity.kt            # 唯一 Activity：全屏封面 + 手势路由 + 生命周期
└── engine/
    ├── Gesture.kt             # Gesture 枚举（6 种手势）
    ├── GestureEngine.kt       # Modifier.gestureDetector：手势识别
    ├── AudioEngine.kt         # AudioEngine 接口 + DefaultAudioEngine 实现
    └── Game.kt                # Game 接口 + GameEngine<S> 状态机基类

调用关系：

MainActivity ──创建──> DefaultAudioEngine ──注入──> GameFactory.create(audio)
     │                                                    │
     └─ gestureDetector { game.onGesture(it) } <──────────┘
                       （每个 flavor 提供自己的 GameFactory/Game 实现）

• MainActivity：只做四件事——沉浸式全屏 + 屏幕常亮、显示 res/drawable/cover.png（带 TalkBack 描述）、把手势回调路由给 game.onGesture、在 onDestroy 里 game.onStop() + audioEngine.release()。 它通过硬编码约定 com.soundgame.game.GameFactory.create(audio) 拿到游戏实例， 三个 flavor 各自在隔离的源码集里提供同名类，互不冲突。
• GestureEngine：一个 Compose Modifier 扩展，把触摸事件翻译成 Gesture 枚举回调。
• AudioEngine：接口 + 唯一实现 DefaultAudioEngine，三层音频分发。
• Game / GameEngine：游戏侧契约。Game 是三个方法的极简接口； GameEngine<S> 是其上的状态机抽象（见下文）。

音频三层架构（DefaultAudioEngine）

层	id 前缀	播放器	特性
BGM	bgm/	ExoPlayer（单实例轮换）	循环播放，切换时交叉淡入淡出
对白	voice/	ExoPlayer（单实例轮换）	播放期间 duck BGM 到 20%，播完恢复
音效	sfx/	SoundPool（maxStreams=8）	低延迟，可叠加

play(id) 按前缀分发；id 可省略扩展名，依次尝试 .ogg → .mp3 → .wav （resolveAssetPath）；找不到资产打 Log.e("AudioEngine", ...) 并静默跳过， 不会崩溃——拼写错误只能靠 adb logcat -s AudioEngine 发现。

BGM 交叉淡入时序

playBgm(id) 被调用时：

t=0        新 player 以 volume=0 启动（prepare+play），旧 player 仍在响
t=0~fadeMs 协程逐帧推音量：新 player 0 → 目标音量；旧 player 当前音量 → 0
t=fadeMs   旧 player release()

默认 fadeMs=800，步进 30ms 一格（fadeVolume）。stopBgm(fadeOutMs) 同理淡出后 release。切 BGM 不会停止对白层。

对白 ducking 时序

playVoice(id) ──> 新 voice player 开播，同时 duckBgm()：
                  BGM 音量 300ms 内渐降到 baseVolume × 0.2
播放自然结束 ────> onPlaybackStateChanged(ENDED)：
                  unduckBgm()（300ms 恢复）→ release player → 回调 onComplete

• duck 比例为 duckVolume = 0.2（构造参数）。
• stopVoice() 打断的对白不触发 onComplete——游戏层（storyline 的 playSeq、escape 的 speak、reflex 的 say 队列）都依赖这一点实现 "打断即作废整条语音链"。
• onComplete 是"台词说完再推进剧情"的核心驱动机制。

SFX 层注意事项

• SoundPool load() 是异步的：首次播放某音效时若尚未加载完成，play() 返回 0， 静默失败（见 playSfx 注释）。因此每个游戏 onStart 都必须以音量 0 预播一遍 全部短音效（storyline/reflex/escape 均已实现 prewarm）。
• 音效按 assetPath.hashCode 缓存 soundId，重复播放不重复加载。

手势识别（GestureEngine）

实现：两个叠加的 pointerInput——detectTapGestures（单击/双击）+ detectDragGestures（滑动）。

滑动判定（GestureConfig 默认值）：

参数	默认值	含义
minSwipeDistance	64dp	累积位移低于此值不识别为滑动（防误触）
minSwipeVelocityPxPerSec	400 px/s	平均速度（位移/拖动时长）低于此值不触发

方向取位移较大的轴（|dx| > |dy| 判左右，否则判上下），斜滑归一到最近主轴。

单击 300ms 延迟：因为同时注册了 onDoubleTap，Compose 的 detectTapGestures 必须等双击判定窗口（约 300ms）关闭后才能回调 onTap。 这是全引擎级的行为，游戏设计必须绕开它：

• reflex：正面攻击要求单击格挡，因此其反应窗口强制 ≥ 1100ms （FRONT_MIN_WINDOW_MS），且"无正面攻击时单击不惩罚"；
• storyline：单击只用于"继续剧情"这种非即时操作；
• escape：单击检查房间，同样非即时。

关键即时反馈尽量放在滑动或双击上。

状态机模式（GameEngine）

abstract class GameEngine<S>(protected val audio: AudioEngine) : Game

• 游戏定义状态类型 S，实现 transition(state, gesture): S（纯函数， 返回原状态表示无转移）和 onEnterState(state, previous)（副作用：播音频）。
• onGesture 是 final 的：算 transition，状态变了才更新并回调 onEnterState。
• onStart 以 previous=null 进一次 initialState。

实际采用情况：三个游戏都没有用 GameEngine——

• storyline：剧情树 + STORY/MENU 双模式 + 选择缓存（pendingChoice）， 状态不是简单枚举，直接实现 Game；
• reflex：计时器驱动的反应玩法（Handler 调度出怪），非状态机；
• escape：INTRO/PLAY/END 三 phase + 位置/物品等多维状态，直接实现 Game。

GameEngine 仍是新游戏（线性剧情类）的推荐起点。

flavor 机制

app/build.gradle.kts 中 flavorDimensions += "game" + 三个 productFlavor （storyline / reflex / escape），各自独立 applicationId，可同机共存安装。

每个 flavor 源码集（app/src/<flavor>/）包含：

java/com/soundgame/game/GameFactory.kt   # 注册点（包名/签名固定）
java/com/soundgame/game/<Xxx>Game.kt     # 游戏实现
res/drawable/cover.png                   # 封面（1080x1920，文件名固定）
assets/audio/{bgm,voice,sfx}/            # 全部音频资产（ogg）
gen/                                     # 资产生成脚本（可复现，不入 APK）

minSdk = 26，compileSdk = 36，依赖 Compose BOM 2025.06.01 + media3-exoplayer 1.6.1。

已知限制

• 单击延迟 ~300ms（双击判定窗口），引擎级，见上。
• SoundPool 首次播放丢失：靠各游戏预热缓解，引擎层未做加载完成队列。
• 引擎静默容错：资产缺失只打日志不崩溃，拼写错误不易发现。
• 手势参数全局共享：GestureConfig 在 MainActivity 处对所有 flavor 生效， 不能单游戏定制。
• 无持久化：reflex 最高分为进程内变量（companion object var highScore）， 杀进程即丢；三款游戏均无存档。
• 单 voice 通道：同时只有一条对白在播，新 playVoice 会顶掉旧的； 需要"背景环境音 + 对白"时环境音只能走 sfx 层（escape 的做法）或并进 BGM。
• 未真机听测：反应窗口、响度平衡、立体声分离度等手感参数只验证到 构建层面，需实机试听调整（见 README 待办）。