SoundGame/docs/engine-api.md

SoundGame 引擎 API 文档

面向游戏开发 agent：本文档说明如何在共享引擎骨架上开发一款纯音频游戏。 骨架已提供：手势识别（GestureEngine）、分层音频（AudioEngine）、状态机基类 （GameEngine）、全屏封面 Activity（MainActivity）。你只需要实现 Game 接口并提供资产，不需要碰 Activity、Compose 或音频底层。

构建与环境

source /home/ubuntu/SoundGame/env.d/android.sh   # 必须先执行（JDK17 / SDK / ffmpeg）
cd /home/ubuntu/SoundGame

# 构建某一个 flavor（各自独立安装，applicationId 不同）
./gradlew assembleStorylineDebug   # com.soundgame.storyline
./gradlew assembleReflexDebug      # com.soundgame.reflex
./gradlew assembleEscapeDebug      # com.soundgame.escape

# 一次构建全部
./gradlew assembleDebug

APK 输出在 app/build/outputs/apk/<flavor>/debug/。 首次构建会下载依赖，较慢属正常（daemon 有缓存，重跑会快很多）。

工程结构

app/
  build.gradle.kts               # flavor 定义、依赖
  src/
    main/                        # 共享引擎，不要放游戏逻辑
      java/com/soundgame/
        MainActivity.kt          # 全屏封面 + 手势路由（一般不用改）
        engine/
          Gesture.kt             # Gesture 枚举
          GestureEngine.kt       # Modifier.gestureDetector
          AudioEngine.kt         # AudioEngine 接口 + DefaultAudioEngine
          Game.kt                # Game 接口 + GameEngine<S> 状态机基类
      AndroidManifest.xml
    storyline/                   # 你的游戏放这里（以 storyline 为例）
      java/com/soundgame/game/
        GameFactory.kt           # 注册点：创建你的 Game 实现
        ...                      # 你的其他游戏代码，随意组织
      res/drawable/cover.png     # 封面图（1080x1920，必须叫 cover）
      assets/audio/              # 全部音频资产
        bgm/  voice/  sfx/

快速上手：实现一款游戏

第 1 步：在 app/src/<你的flavor>/java/com/soundgame/game/ 下写游戏类。 推荐继承 GameEngine<S>（状态机模式）：

package com.soundgame.game

import com.soundgame.engine.AudioEngine
import com.soundgame.engine.GameEngine
import com.soundgame.engine.Gesture

sealed interface Scene {
    data object Intro : Scene
    data object Hallway : Scene
    data object Ending : Scene
}

class MyGame(audio: AudioEngine) : GameEngine<Scene>(audio) {

    override val initialState = Scene.Intro

    // 状态转移：当前状态 + 手势 -> 新状态（返回原状态表示无转移）
    override fun transition(state: Scene, gesture: Gesture): Scene = when (state) {
        Scene.Intro -> when (gesture) {
            Gesture.TAP -> Scene.Hallway
            else -> state
        }
        Scene.Hallway -> when (gesture) {
            Gesture.SWIPE_LEFT, Gesture.SWIPE_RIGHT -> Scene.Ending
            else -> state
        }
        Scene.Ending -> state
    }

    // 进入新状态时播放音频（onStart 时也会以 previous=null 调一次 initialState）
    override fun onEnterState(state: Scene, previous: Scene?) {
        when (state) {
            Scene.Intro -> {
                audio.playBgm("bgm/main_theme")
                audio.playVoice("voice/intro")
            }
            Scene.Hallway -> audio.playVoice("voice/hallway")
            Scene.Ending -> {
                audio.stopBgm()
                audio.playVoice("voice/ending")
            }
        }
    }
}

如果你的玩法不是状态机（如 reflex 的计时反应），直接实现 Game 接口：

class MyGame(private val audio: AudioEngine) : Game {
    override fun onGesture(gesture: Gesture) { /* 任意逻辑 */ }
    override fun onStart() { /* 开场 */ }
    override fun onStop() { /* 收尾 */ }
}

第 2 步：在 GameFactory.kt（已在骨架中，包名必须是 com.soundgame.game） 里把 stub 换成你的实现：

object GameFactory {
    fun create(audio: AudioEngine): Game = MyGame(audio)
}

MainActivity 只认 com.soundgame.game.GameFactory.create(audio)，不要改它的签名。

第 3 步：放资产、构建、验证。

Gesture 枚举

com.soundgame.engine.Gesture，共 6 种：

值	含义	判定
SWIPE_UP / SWIPE_DOWN / SWIPE_LEFT / SWIPE_RIGHT	四向滑动	位移 ≥ 64dp 且平均速度 ≥ 400px/s，方向取位移较大的轴（防误触）
TAP	单击	标准 tap
DOUBLE_TAP	双击	标准 double tap

注意：因为注册了双击，单击回调会延迟约 300ms（等双击判定窗口）才触发。 设计玩法时把关键即时反馈尽量放在滑动或双击上，或接受该延迟。 阈值可在 GestureConfig 调整（骨架用默认值，如需改动在 MainActivity 的 gestureDetector(config = ...) 处传参——这影响所有 flavor，改动前先沟通）。

AudioEngine 接口

interface AudioEngine {
    fun play(id: String)                                   // 按 id 前缀分发
    fun playBgm(id: String, loop: Boolean = true, fadeMs: Long = 800)
    fun stopBgm(fadeOutMs: Long = 800)
    fun playVoice(id: String, duckBgm: Boolean = true, onComplete: (() -> Unit)? = null)
    fun stopVoice()
    fun playSfx(id: String, volume: Float = 1f)
    fun setBgmVolume(volume: Float)
    fun release()                                          // Activity 已调用，你不用管
}

• 三层分离：BGM 用 ExoPlayer（切换时自动交叉淡入淡出）；对白用另一个 ExoPlayer，播放期间自动把 BGM 压到 20%（ducking），播完恢复；短音效用 SoundPool，低延迟可叠加。
• id 约定：相对 assets/audio/ 的路径，如 "sfx/door_open"。 前缀 bgm/、voice/、sfx/ 决定走哪一层；play(id) 就靠前缀分发。 扩展名可省略，引擎依次尝试 .ogg → .mp3 → .wav。
• playVoice 的 onComplete 在对白自然播完时回调（被 stopVoice 打断不回调）， 适合做"台词说完再开选项"的剧情驱动。
• 找不到资产时引擎打 Log.e("AudioEngine", ...) 并静默跳过，不会崩溃—— 但请用 logcat 检查拼写：adb logcat -s AudioEngine。

资产放哪

app/src/<flavor>/assets/audio/
  bgm/    背景音乐（循环长音频，建议 .ogg）
  voice/  对白/旁白（建议 .ogg 或 .mp3）
  sfx/    短音效（建议 .wav 或短 .ogg，SoundPool 低延迟）

封面图：app/src/<flavor>/res/drawable/cover.png（1080x1920 竖图，骨架已生成 占位渐变图，换成正式图时保持文件名 cover.png 不变，MainActivity 按名引用）。

生成/处理音频用 ffmpeg（已配好）：如 ffmpeg -i in.wav -c:a libvorbis -q:a 5 app/src/storyline/assets/audio/bgm/theme.ogg。

规则与注意事项

• 不要修改 app/src/main/ 下的引擎代码和 MainActivity，除非你 flavor 的 需求所有游戏都需要——那是共享代码。确需扩展引擎能力时，加新方法而不要改 已有签名。
• 每个 flavor 的包结构固定为 com.soundgame.game.GameFactory + 任意其他类， 三个 flavor 的同名类互不冲突（源码集隔离）。
• 全屏沉浸式、屏幕常亮、竖屏锁定已在 MainActivity/Manifest 处理，不用自己弄。
• 封面图已带 TalkBack 无障碍描述（contentDescription），换图不影响。
• 音频游戏注意节奏：手势回调在主线程，音频 API 均非阻塞，可以直接在 onGesture 里调用。