Genarrative/docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md

bark-battle 2D Runtime 前端技术方案（2026-05-11）

1. 背景与目标

本方案基于 .hermes/plans/2026-05-11_144229-bark-battle-2d-game-bdd-ddd-tdd-plan.md，为“汪汪声浪大作战 / bark-battle”细化前端与浏览器游戏 runtime 的技术实现路线。

本任务只产出技术方案，不直接实现代码。后续编码应以本文作为 runtime 层设计约束，再按 TDD 小步落地。

1.1 玩法定位

bark-battle 是一个声控拔河式 2D 浏览器小游戏：玩家对麦克风发出狗叫声，系统根据音量峰值、有效叫声次数和节奏计算本方声浪推动力，在限时 30 秒内推动顶部红蓝能量条，时间结束后按能量条偏向判定胜负。

1.2 本文范围

本文覆盖：

• Phaser + TypeScript + Vite 栈选择
• simulation / render / HUD 边界
• 建议目录结构
• 核心 domain 类型
• Web Audio 输入适配
• Phaser Scene 切分
• DOM HUD 设计
• 移动端与权限降级
• 测试与验证命令

本文不覆盖：

• 后端表结构、持久化成绩、作品发布、广场接入
• 实时多人对战协议
• 复杂 AI 狗叫识别模型
• 美术素材正式生产流程

2. 技术栈选择

2.1 推荐栈

Runtime Renderer: Phaser 3
Language: TypeScript
Build: Vite
Host UI: React / DOM overlay
Audio Input: Web Audio API + MediaDevices.getUserMedia
Test: Vitest + Testing Library + 浏览器 smoke / Playwright 可选

2.2 选择理由

1. 玩法是横版 2D 舞台，核心表现是狗狗 sprite、声浪、拟声词、粒子、屏幕震动与能量条反馈，Phaser 对 2D 渲染、时间循环、sprite animation、camera、粒子和 Scene 生命周期支持成熟。
2. 当前项目主前端已使用 TypeScript + Vite，继续复用现有构建和测试体系，避免引入独立构建链。
3. 文字密集、权限提示、结算、设置和移动端响应式布局适合 DOM HUD；Canvas 保持负责 playfield 和动态特效。
4. Web Audio API 可以在浏览器端完成 MVP 所需音量采样、RMS/peak 计算、环境噪音校准和输入归一化，不需要首版接入后端音频处理。

2.3 不选择其它路线的原因

• 不使用 Three.js / 3D：当前玩法画面是 2D 横版舞台，不需要 3D 相机、模型和材质管线。
• 不把 HUD 全部塞入 Phaser Canvas：权限说明、重试、结算、移动端布局和可访问性更适合 DOM。
• 不在前端实现正式业务真相：浏览器 runtime 可承载单局即时 simulation，但若后续涉及成绩、作品、排行榜、发布和奖励，必须交给后端投影/API 裁决。

3. 总体架构

3.1 分层总览

React Runtime Shell
  ├─ DOM HUD / Panels
  │   ├─ PermissionPanel
  │   ├─ TopEnergyBar
  │   ├─ TimerChip
  │   └─ ResultPanel
  │
  ├─ Application Controller
  │   ├─ permission / calibration orchestration
  │   ├─ simulation tick
  │   ├─ audio sample submission
  │   └─ snapshot publish
  │
  ├─ Pure Domain / Simulation
  │   ├─ BarkBattleSession
  │   ├─ BarkDetector
  │   ├─ EnergyTugOfWar
  │   ├─ BarkBattleScoring
  │   └─ OpponentStrategy
  │
  ├─ Infrastructure Adapters
  │   ├─ BrowserMicrophoneInput
  │   ├─ AudioAnalyserSampler
  │   └─ PhaserGameHost
  │
  └─ Phaser Renderer
      ├─ BootScene
      ├─ PreloadScene
      ├─ BattleScene
      ├─ FxScene / DebugScene（可选）
      └─ Asset manifest

3.2 强制边界

1. domain/ 不依赖 Phaser、Web Audio、DOM、React、浏览器全局对象或后端 API。
2. domain/ 只接收 plain data，例如时间增量、归一化音量样本、对手 power、配置参数。
3. application/ 负责编排权限、校准、音频输入、AI 对手、tick 和 snapshot 分发。
4. Phaser Scene 只消费 BarkBattleSnapshot，把 snapshot 映射成 sprite、动画、粒子、camera 和 sound effect；不得持有核心胜负、计数和能量条规则。
5. DOM HUD 只消费 snapshot 和少量 runtime UI 状态，负责展示、按钮和弹层；不得重复实现核心胜负规则。
6. 若后续接入平台作品/成绩/排行榜，前端只调用后端 API 和展示投影，不在本地绕过后端生成正式结论。

4. 建议目录结构

首版建议以独立 runtime 原型落在 src/games/bark-battle/，避免提前侵入平台创作链路。

src/games/bark-battle/
  domain/
    BarkBattleTypes.ts
    BarkBattleSession.ts
    BarkDetector.ts
    EnergyTugOfWar.ts
    BarkBattleScoring.ts
    OpponentStrategy.ts
    __tests__/
      BarkDetector.test.ts
      EnergyTugOfWar.test.ts
      BarkBattleSession.test.ts
      BarkBattleScoring.test.ts

  application/
    BarkBattleController.ts
    BarkBattleConfig.ts
    BarkBattleSnapshotStore.ts
    __tests__/
      BarkBattleController.test.ts

  infrastructure/
    BrowserMicrophoneInput.ts
    AudioAnalyserSampler.ts
    MicrophonePermission.ts
    __tests__/
      AudioAnalyserSampler.test.ts

  phaser/
    BarkBattleGameHost.ts
    scenes/
      BarkBattleBootScene.ts
      BarkBattlePreloadScene.ts
      BarkBattleScene.ts
      BarkBattleFxScene.ts
    assets/
      barkBattleAssetManifest.ts

  ui/
    BarkBattleRuntimeShell.tsx
    BarkBattleHud.tsx
    BarkBattlePermissionPanel.tsx
    BarkBattleResultPanel.tsx
    BarkBattleMobileControls.tsx
    BarkBattleHud.css
    __tests__/
      BarkBattleHud.test.tsx
      BarkBattlePermissionPanel.test.tsx
      BarkBattleResultPanel.test.tsx

若后续进入 Genarrative 正式玩法类型闭环，再按 genarrative-play-type-integration 扩展到：

src/components/bark-battle-runtime/BarkBattleRuntimeShell.tsx
src/components/bark-battle-result/BarkBattleResultView.tsx
src/services/barkBattleRuntimeClient.ts
packages/shared/src/contracts/barkBattle.ts
server-rs/crates/shared-contracts/src/bark_battle.rs

首版不建议直接新增后端表或正式作品链路，除非产品明确要求成绩、发布和广场能力。

5. 核心 Domain 类型

5.1 基础枚举与数值约定

export type BarkBattlePhase =
  | 'permission'
  | 'calibration'
  | 'countdown'
  | 'playing'
  | 'finished'
  | 'unsupported'
  | 'permission-denied'

export type BarkBattleSide = 'player' | 'opponent'

export type BarkBattleWinner = BarkBattleSide | 'draw' | null

export type BarkBattleDifficulty = 'easy' | 'normal' | 'hard'

关键数值：

• energy: -100..100，正数偏玩家侧，负数偏对手侧。
• currentVolume: 0..1，音频采样归一化后的瞬时音量。
• recentPeak: 0..1，短窗口内峰值。
• power: 0..1 或 0..100 二选一，建议 domain 内统一 0..1，HUD 显示再转百分比。
• remainingMs: 单局剩余毫秒。

5.2 Snapshot

export type BarkBattleSnapshot = {
  phase: BarkBattlePhase
  elapsedMs: number
  remainingMs: number
  countdownMs: number
  energy: number
  player: BarkSideState
  opponent: BarkSideState
  winner: BarkBattleWinner
  result: BarkBattleResult | null
  lastEvents: BarkBattleVisualEvent[]
}

export type BarkSideState = {
  side: BarkBattleSide
  barkCount: number
  currentVolume: number
  recentPeak: number
  combo: number
  power: number
  isBarking: boolean
  lastBarkAtMs: number | null
  maxVolume: number
}

export type BarkBattleResult = {
  winner: BarkBattleWinner
  finalEnergy: number
  playerBarkCount: number
  playerMaxVolume: number
  playerAveragePower: number
  score: number
}

5.3 输入样本与叫声事件

export type BarkAudioSample = {
  atMs: number
  volume: number
  peak: number
  rms: number
}

export type BarkDetectedEvent = {
  id: string
  atMs: number
  side: BarkBattleSide
  volume: number
  strength: number
  combo: number
}

5.4 视觉事件

视觉事件由 domain 或 application 生成，但只包含 plain data，不包含 Phaser 对象：

export type BarkBattleVisualEvent =
  | {
      type: 'bark-word'
      id: string
      side: BarkBattleSide
      atMs: number
      strength: number
      text: 'BARK' | 'WOOF' | 'WAN' | 'WANGOOF'
    }
  | {
      type: 'shockwave'
      id: string
      side: BarkBattleSide
      atMs: number
      strength: number
    }
  | {
      type: 'combo-burst'
      id: string
      side: BarkBattleSide
      atMs: number
      combo: number
    }

Phaser 只根据这些事件播放一次性特效，并维护已消费事件 ID，避免重复播放。

6. Domain 模块职责

6.1 BarkDetector

职责：把连续音频样本转换为有效叫声事件。

输入：

• BarkAudioSample
• 校准后的 ambientNoiseFloor
• barkThreshold
• minBarkGapMs
• minBarkDurationMs
• maxBarkDurationMs

规则建议：

1. 音量超过动态阈值进入 candidate 状态。
2. 峰值回落到阈值以下或持续时长达到上限时结束 candidate。
3. candidate 持续时间在 80ms..1200ms 且与上一次有效叫声间隔足够时，记为一次叫声。
4. 长时间持续噪音不应无限计数，只能按冷却和峰值回落形成新事件。
5. MVP 不要求识别“是否真狗叫”，先基于音量峰值、时长和间隔判断。

6.2 EnergyTugOfWar

职责：更新红蓝拉锯条。

建议公式：

playerPower = volumeScore * 0.65 + barkRateScore * 0.35 + comboBonus
opponentPower = opponentStrategy.tick(...)
energyDelta = (playerPower - opponentPower) * deltaSeconds * balanceFactor
energy = clamp(energy + energyDelta, -100, 100)

约束：

• EnergyTugOfWar 不知道玩家来自麦克风还是 mock input。
• EnergyTugOfWar 不知道 Phaser 能量条宽度。
• 平衡参数集中在 BarkBattleConfig，不要散落在 Scene 或 HUD 中。

6.3 BarkBattleSession

职责：管理局内 phase、计时、胜负和 snapshot。

状态机建议：

permission → calibration → countdown → playing → finished
        ↘ permission-denied
        ↘ unsupported

关键规则：

• countdown 结束才进入 playing。
• playing 时 remainingMs 随 tick 递减。
• remainingMs <= 0 后进入 finished。
• energy > drawThreshold 判定玩家胜利。
• energy < -drawThreshold 判定对手胜利。
• abs(energy) <= drawThreshold 判定平局。

6.4 OpponentStrategy

职责：为单机 MVP 提供对手推动力。

export interface OpponentStrategy {
  tick(input: OpponentTickInput): OpponentTickOutput
}

普通难度建议：

• 周期性小叫声提供基础压力。
• 每 3~6 秒一次短爆发。
• 玩家大幅领先时可轻微增强，但不能追到不可赢。

7. Web Audio 输入适配

7.1 BrowserMicrophoneInput

职责：封装浏览器麦克风权限与音频流生命周期。

建议 API：

export interface MicrophoneInputPort {
  isSupported(): boolean
  requestPermission(): Promise<MicrophoneSession>
  stop(): void
}

export interface MicrophoneSession {
  sample(atMs: number): BarkAudioSample
  stop(): void
}

实现要点：

1. 使用 navigator.mediaDevices?.getUserMedia({ audio: true })。
2. 在用户点击“开始”后创建或 resume AudioContext，避免移动端自动播放策略拦截。
3. 使用 AnalyserNode 读取时域数据，计算 RMS 与 peak。
4. 输出归一化样本，不把 MediaStream、AudioContext、AnalyserNode 泄漏到 domain。
5. 退出、重开、页面卸载时停止 track，避免麦克风占用残留。

7.2 校准流程

calibration 阶段建议持续 800ms..1500ms：

1. 收集静默环境样本。
2. 计算 ambientNoiseFloor，例如 p75 或均值 + 标准差。
3. 设置动态阈值：

barkThreshold = clamp(ambientNoiseFloor + 0.12, 0.18, 0.55)

4. 若环境噪音过高，HUD 给出简短提示和“继续 / 重新校准”入口，但不要把长说明常驻在画面上。

7.3 权限与错误分类

export type MicrophoneFailureReason =
  | 'unsupported'
  | 'permission-denied'
  | 'not-found'
  | 'not-readable'
  | 'audio-context-blocked'
  | 'unknown'

前端只根据错误分类展示可操作状态：重试授权、返回、或使用调试备用输入。不要把浏览器原始错误堆栈展示给玩家。

8. Phaser Scene 切分

8.1 BarkBattleBootScene

职责：

• 初始化 Phaser 全局配置。
• 注册 scale、background color、全局事件桥。
• 不加载重资源，不处理玩法规则。

8.2 BarkBattlePreloadScene

职责：

• 根据 barkBattleAssetManifest 加载背景、狗狗 sprite、声浪 FX、拟声词 bitmap / atlas、轻量音效。
• 使用稳定 manifest key，不在 gameplay 代码中散写文件路径。
• 加载完成后进入 BarkBattleScene。

8.3 BarkBattleScene

职责：

• 创建横版舞台、左右狗狗、背景层、声浪层、拟声词层。
• 每帧读取最新 BarkBattleSnapshot。
• 根据 snapshot 更新：
  • 狗狗 idle / bark / win / lose 动画
  • 声浪强度
  • camera shake
  • transient bark words
  • shockwave
• 把可选的调试输入 action 传给 controller，但不处理麦克风和规则。

不得在 Scene 中实现：

• 叫声计数
• 胜负判定
• 能量条规则
• 权限流程
• 结算数据计算

8.4 BarkBattleFxScene（可选）

如果特效复杂，可拆出叠加 Scene：

• 专门处理拟声词、粒子、冲击波和 camera shake。
• 通过视觉事件 ID 去重。
• 对 prefers-reduced-motion 或低端设备降级。

首版也可以先把 FX 保持在 BarkBattleScene 内，但必须仍然只消费 snapshot / visual events。

9. DOM HUD 设计

9.1 HUD 层级

DOM HUD 建议覆盖在 Phaser Canvas 上方：

BarkBattleRuntimeShell
  ├─ <div className="bark-battle-canvas-host" />
  └─ <BarkBattleHud snapshot={snapshot} uiState={uiState} />

HUD 分区：

• 顶部：红蓝声浪能量条 + 小型剩余时间。
• 中央：仅在倒计时、关键提示或结算时短暂展示大号状态。
• 左右边缘：双方简洁状态，例如叫声次数 / combo chip。
• 底部角落：麦克风状态、重试、小菜单。
• 结算：独立居中面板，显示胜负、叫声次数、最大音量、评分、再来一局、返回。

9.2 Playfield 保护

遵循 game UI 约束：

1. 正常 playing 阶段保持中心和下中部 playfield 清爽，不常驻长文案。
2. 不把规则说明、长控制说明、多段提示默认铺在画面上。
3. 权限、设置、结算使用独立面板或弹层，不在当前面板下面展开一大块内容。
4. 移动端优先保证顶部能量条、倒计时、狗狗和重试入口可见可点。
5. 大动效不能遮挡顶部能量条和倒计时。

9.3 CSS 设计建议

• 使用局部 CSS class 或 CSS module，避免污染全站。
• 使用 CSS 变量定义主题：
  • --bark-player-color
  • --bark-opponent-color
  • --bark-panel-bg
  • --bark-safe-bottom
• 使用 dvh / svh 和 safe-area inset 处理移动端地址栏与刘海。
• pointer-events 分层：HUD 容器默认 pointer-events: none，按钮和面板恢复 pointer-events: auto。

10. 移动端与权限降级

10.1 移动端输入约束

移动端浏览器通常要求用户手势才能启动 AudioContext。开局流程必须是：

玩家点击“开始” → requestPermission → 创建/恢复 AudioContext → calibration → countdown → playing

不要在页面加载时自动请求或自动启动 AudioContext。

10.2 响应式布局

移动端建议：

• 横屏优先呈现完整舞台；竖屏可保持舞台居中并缩小 HUD。
• 顶部能量条高度保持可读，但不要占满大面积。
• 结算面板宽度使用 min(92vw, 420px)。
• 底部按钮避开 env(safe-area-inset-bottom)。
• 非关键设置折叠进小菜单。

10.3 权限失败降级

权限失败时：

• unsupported：展示“当前浏览器不支持麦克风输入”，提供返回入口。
• permission-denied：展示简短说明和“重新授权”入口。
• not-found：提示未检测到麦克风，提供返回入口。
• audio-context-blocked：提示点击重试。

可选开发调试降级：

• 本地 dev 可启用键盘 mock input，例如按住空格模拟音量峰值。
• mock input 必须标记为开发/调试能力，不作为正式竞技能力。

11. 测试策略

11.1 Domain 单元测试（优先）

目标：不接 Phaser、不接 DOM、不接 Web Audio。

建议测试：

• BarkDetector：超过阈值且间隔足够时计为一次有效叫声。
• BarkDetector：持续噪音不会无限计数。
• BarkDetector：低于环境噪音阈值不计入叫声。
• EnergyTugOfWar：玩家 power 高于对手时 energy 向玩家侧移动。
• EnergyTugOfWar：energy clamp 在 -100..100。
• BarkBattleSession：倒计时结束进入 playing。
• BarkBattleSession：剩余时间归零进入 finished。
• BarkBattleSession：按 energy 和 drawThreshold 判定胜 / 负 / 平。

11.2 Application 测试

目标：验证输入样本、AI、tick 和 snapshot 编排。

建议测试：

• 权限允许后进入校准，再进入倒计时。
• 权限拒绝后 phase 为 permission-denied，不进入 playing。
• 提交 mock audio sample 后 snapshot 中玩家状态更新。
• AI 对手 power 参与能量条拉锯。
• lastEvents 只发布新增视觉事件。

11.3 HUD 组件测试

目标：验证 snapshot 到 DOM 的展示映射。

建议测试：

• playing 阶段展示倒计时和能量条。
• energy 正负值映射到玩家 / 对手侧比例。
• permission-denied 展示重试入口。
• finished 展示胜负、叫声次数和再来一局。
• 移动端 class / 结构不依赖 Phaser Canvas 才能渲染。

11.4 Phaser 集成与 smoke

自动化层面不强行在 Vitest 中完整启动 Phaser。建议：

• 用 adapter mock 测试 Scene 消费 snapshot 的纯映射函数。
• 浏览器 smoke 验证真实 Canvas、Web Audio 和动画。
• 若后续引入 Playwright，再做最小视觉和交互 smoke。

12. 验证命令建议

文档阶段只需要编码检查和 diff 检查：

npm run check:encoding
git diff -- docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md

后续实现 domain 后建议：

npm run test -- --run src/games/bark-battle/domain/**/*.test.ts
npm run typecheck
npm run check:encoding

后续实现 HUD 后建议：

npm run test -- --run src/games/bark-battle/ui/**/*.test.tsx
npm run lint:eslint
npm run typecheck
npm run check:encoding

后续接入浏览器 runtime 后建议：

npm run dev:web
# 人工 smoke：授权麦克风 → 校准 → 发声 → 能量条变化 → 结算 → 再来一局

若未来接入 Genarrative 正式玩法类型、后端持久化或发布链路，再追加对应契约、api-server 和 SpacetimeDB 验证；首版 runtime 原型不应提前新增这些命令作为门槛。

13. 后续落地顺序

建议后续实现按以下顺序推进：

1. 先建 domain/ 和纯单元测试。
2. 实现 BarkDetector、EnergyTugOfWar、BarkBattleSession 的最小规则。
3. 建 application/ controller，用 mock audio sample 跑通 snapshot。
4. 实现 DOM HUD 的 permission / energy / timer / result 展示。
5. 接入 BrowserMicrophoneInput 和校准流程。
6. 接入 Phaser host、Scene 和 asset manifest，占位素材先跑通视觉反馈。
7. 做移动端视口和权限失败 smoke。
8. 产品确认后再决定是否进入正式玩法类型、作品发布和后端真相链。

14. 关键技术决策

1. 默认采用 Phaser 3 + TypeScript + Vite，符合 2D 浏览器游戏默认路线。
2. 核心 simulation 放在纯 TypeScript domain，严格不依赖 Phaser / Web Audio / DOM。
3. Web Audio 只作为输入 adapter，输出归一化 BarkAudioSample。
4. Phaser Scene 是 renderer，只消费 snapshot 和 visual events，不承载规则真相。
5. HUD 使用 DOM overlay，承载权限、能量条、倒计时、结算和移动端响应式布局。
6. MVP 不做复杂狗叫语义识别，先用音量峰值、持续时长、冷却和环境噪音校准。
7. MVP 建议玩家 vs AI 单机 runtime，正式成绩、排行榜、发布和奖励后续再交给后端链路。