Genarrative/.hermes/plans/2026-05-11_144229-bark-battle-2d-game-bdd-ddd-tdd-plan.md

声控狗叫对战 2D 浏览器游戏设计与实现计划

目标

基于用户提供的视频：

C:\Users\DSK\Videos\一款双方比狗叫的游戏 - 1.一款双方比狗叫的游戏(Av116504192360177,P1).mp4

提取其中“双方比狗叫”的核心玩法，并按照 BDD / TDD / DDD 的方法，为 Genarrative 中可运行于浏览器的 2D 游戏方案生成一份可落地设计与实现思路。实现方向遵循仓库内 game-studio 插件工作流，默认采用 2D Phaser + TypeScript + Vite + DOM HUD 的浏览器游戏架构。

本计划仅做方案设计，不直接编码。

当前上下文与输入分析

已识别视频核心画面

通过抽帧观察，视频中的游戏呈现出以下稳定特征：

• 画面是横版 2D 手绘舞台，场景包括公园、海边等固定关卡背景。
• 双方各有一只狗作为对战角色，站在左右两侧。
• 中央有明显倒计时，例如 30、28。
• 顶部有红蓝双方拉锯式能量条 / 进度条。
• 中央提示出现：对着麦克风汪一声、用声音大小 + 叫声次数推动能量条！
• 玩家输入不是传统键鼠，而是麦克风声音。
• 玩家需要模仿狗叫，系统根据声音大小与叫声次数推动能量条。
• 屏幕会根据叫声出现 BARK、WOOF、WAN、WANGOOF 等拟声词与冲击波视觉反馈。
• 回合结束时，根据能量条偏向或推进结果判定胜负。

提炼出的核心玩法

这是一个“声控拔河式狗叫对战”小游戏：

• 两名玩家 / 一名玩家对 AI 分别代表左右两只狗。
• 每局限时 30 秒。
• 玩家通过麦克风持续发出狗叫声。
• 游戏实时分析音量峰值、叫声次数、叫声节奏。
• 声音越大、叫声越密集，己方推动力越强。
• 顶部能量条在双方推动力差值下左右移动。
• 时间结束后，能量条偏向哪一方，哪一方获胜。

需要合理抽象的地方

视频中存在直播弹幕、贴图、表情包、遮挡层，这些不是游戏本体机制。本方案只吸收游戏本体核心：

• 双方狗狗对叫
• 麦克风输入
• 声音强度 + 次数判定
• 红蓝拉锯能量条
• 限时回合
• 夸张拟声词与冲击波反馈

game-studio 插件路线

根据仓库内 .hermes/plugins/game-studio 技能：

• 早期游戏工作先走 game-studio 总入口。
• 2D 浏览器游戏默认选择 Phaser。
• 架构上需要分离 simulation 与 renderer。
• HUD / 菜单 / 设置优先使用 DOM overlay，不把密集文字塞进 canvas。
• 玩法状态不应由 Phaser Scene 直接持有，Scene 只负责渲染、动画、相机、输入适配。

因此本方案采用：

• Runtime：Phaser 3
• Language：TypeScript
• Build：Vite
• UI：React/DOM HUD overlay 或项目现有 DOM UI 层
• Audio input：Web Audio API + MediaDevices.getUserMedia
• Simulation：纯 TS domain/service 层
• Renderer：Phaser Scene 读取 simulation snapshot 并播放动画/特效

游戏概念设计

游戏名建议

• 中文：汪汪声浪大作战
• 英文代号：bark-battle
• Play type ID 建议：bark-battle

玩家幻想

玩家不是通过按键战斗，而是真的对着麦克风“汪汪叫”，把自己的狗狗声浪推向对手。游戏目标是在倒计时结束前用更响、更密集、更有节奏的叫声赢得声浪拔河。

核心动词

• 叫：对麦克风发出狗叫声。
• 推：通过叫声推动能量条。
• 压制：让能量条持续向对手方向倾斜。
• 爆发：短时间内连续高质量叫声触发冲击波。
• 防守：对手强势时通过持续叫声把能量条拉回。

单局流程

1. 准备阶段

   • 展示双方狗狗、地图、麦克风权限提示。
   • 用户授权麦克风。
   • 系统检测环境噪音并校准阈值。

2. 倒计时阶段

   • 3、2、1 或中央 30 倒计时开始。
   • 玩家看到提示：对着麦克风汪一声。

3. 对战阶段

   • 每帧或固定 tick 采集麦克风音量。
   • 根据音量峰值与短促叫声次数计算本方 barkPower。
   • AI 或远端对手产生 opponentPower。
   • 能量条根据 playerPower - opponentPower 拉锯。
   • 狗狗张嘴动画、拟声词、冲击波按声音强度生成。

4. 结算阶段

   • 30 秒结束。
   • 能量条偏玩家侧则胜利，偏对手侧则失败，接近中线则平局。
   • 展示叫声次数、最大音量、平均节奏、声浪评分。

5. 重开 / 返回

   • 支持再来一局。
   • 支持返回玩法入口或结果页。

规则设计

关键状态

type BarkBattlePhase = 'permission' | 'calibration' | 'countdown' | 'playing' | 'finished'

type BarkBattleSnapshot = {
  phase: BarkBattlePhase
  remainingMs: number
  energy: number // -100 到 100，负数偏对手，正数偏玩家
  player: BarkSideState
  opponent: BarkSideState
  winner: 'player' | 'opponent' | 'draw' | null
}

type BarkSideState = {
  barkCount: number
  currentVolume: number
  recentPeak: number
  combo: number
  power: number
  isBarking: boolean
}

输入判定

音量采样

• 使用 Web Audio API 创建 AnalyserNode。
• 每个 simulation tick 读取频域或时域数据。
• 计算 RMS 或 peak volume。
• 根据校准后的环境噪音设置动态阈值。

一次“叫声”的判定

一次有效叫声建议满足：

• 音量超过 barkThreshold。
• 与上一次叫声峰值至少间隔 minBarkGapMs，避免持续噪音被无限计数。
• 持续时长在合理范围，例如 80ms 到 1200ms。
• 可选：频谱能量集中在中高频，不强制做复杂语音识别，MVP 先用音量 + 峰值节奏。

推动力计算

playerPower = volumeScore * 0.65 + barkRateScore * 0.35 + comboBonus
opponentPower = aiPower 或远端玩家 power
energyDelta = (playerPower - opponentPower) * deltaTime * balanceFactor
energy = clamp(energy + energyDelta, -100, 100)

AI 对手 MVP

若先做单机浏览器版，右侧对手可由 AI 模拟：

• 简单难度：周期性小叫，power 低。
• 普通难度：有节奏地爆发，power 中等。
• 困难难度：根据玩家领先程度自适应追赶，但不得作弊到不可赢。

后续可扩展为多人实时对战。

BDD 行为场景

功能: 麦克风授权与准备

功能: 狗叫对战麦克风准备
  为了让玩家能用声音参与对战
  作为浏览器玩家
  我希望游戏在开局前明确请求麦克风权限并完成环境校准

  场景: 玩家允许麦克风权限后进入准备倒计时
    假如玩家打开狗叫对战页面
    当玩家同意浏览器麦克风授权
    那么系统应进入环境噪音校准阶段
    而且校准完成后应显示开局倒计时

  场景: 玩家拒绝麦克风权限
    假如玩家打开狗叫对战页面
    当玩家拒绝浏览器麦克风授权
    那么系统应显示无法声控游玩的提示
    而且应提供重试授权入口
    而且不应直接开始对战

功能: 声音推动能量条

功能: 声音大小和叫声次数推动能量条
  为了复刻双方比狗叫的核心体验
  作为玩家
  我希望自己的叫声能实时推动顶部能量条

  场景: 玩家发出一次有效狗叫
    假如游戏处于 playing 阶段
    而且麦克风输入音量超过有效叫声阈值
    当系统检测到一次新的叫声峰值
    那么玩家叫声次数应增加 1
    而且玩家狗狗应播放张嘴吠叫动画
    而且画面应出现拟声词反馈

  场景: 玩家连续大声狗叫压制对手
    假如游戏处于 playing 阶段
    而且玩家在短时间内产生多次有效叫声
    当玩家推动力高于对手推动力
    那么顶部能量条应向玩家侧移动
    而且玩家侧声浪特效应增强

  场景: 环境噪音低于阈值不计入叫声
    假如游戏处于 playing 阶段
    当麦克风只有低于阈值的背景噪音
    那么玩家叫声次数不应增加
    而且能量条不应因为背景噪音明显移动

功能: 限时胜负结算

功能: 狗叫对战胜负结算
  为了让单局对抗有明确目标
  作为玩家
  我希望倒计时结束后根据能量条位置判定胜负

  场景: 倒计时结束时玩家侧占优
    假如游戏剩余时间归零
    而且能量条位于玩家侧
    当系统进入结算阶段
    那么系统应判定玩家胜利
    而且展示玩家叫声次数、最大音量和声浪评分

  场景: 倒计时结束时双方接近平衡
    假如游戏剩余时间归零
    而且能量条处于平局阈值范围内
    当系统进入结算阶段
    那么系统应判定为平局
    而且展示再来一局入口

功能: 移动端与无麦克风降级

功能: 声控游戏移动端与无麦克风降级
  为了让不同设备玩家都能理解当前状态
  作为移动端或无麦克风环境玩家
  我希望系统给出清晰、可操作的降级路径

  场景: 当前浏览器不支持麦克风 API
    假如玩家设备不支持 getUserMedia
    当玩家进入狗叫对战页面
    那么系统应显示设备不支持麦克风输入
    而且提供返回入口

  场景: 移动端进入对战页面
    假如玩家使用移动端浏览器
    当玩家进入狗叫对战页面
    那么主要能量条、倒计时和狗狗角色应保持可见
    而且非关键设置应收起到菜单中

DDD 领域划分

领域层：bark-battle domain

职责：只处理玩法规则，不依赖 Phaser、DOM、Web Audio、后端。

建议模块：

• BarkBattleSession
  • 管理 phase、remainingMs、energy、winner。
• BarkDetector
  • 根据音量样本判断是否形成一次有效叫声。
• EnergyTugOfWar
  • 根据双方 power 更新能量条。
• BarkBattleScoring
  • 计算最大音量、叫声次数、combo、评分。
• OpponentStrategy
  • 单机 AI 对手策略接口。

领域规则必须可用纯单元测试验证。

应用层：use case / controller

职责：编排麦克风输入、simulation tick、AI 对手、结果输出。

建议用例：

• requestMicrophonePermission()
• calibrateAmbientNoise()
• startBarkBattleSession()
• submitAudioSample(sample)
• tickBarkBattle(deltaMs)
• finishBarkBattle()

基础设施层

职责：浏览器 API 与引擎适配。

• BrowserMicrophoneInput
  • 封装 navigator.mediaDevices.getUserMedia。
  • 输出 normalized volume samples。
• PhaserBarkBattleScene
  • 渲染狗狗、背景、拟声词、冲击波。
  • 不持有核心玩法规则。
• DomBarkBattleHud
  • 展示倒计时、能量条、权限提示、结算面板。

表现层

• Phaser Canvas：地图、狗狗、声浪、粒子、拟声词。
• DOM HUD：顶部能量条、倒计时、权限/结算/设置面板。

TDD 落地顺序

第一轮：领域规则 RED-GREEN-REFACTOR

先写纯 TS 单元测试，不接 Phaser，不接麦克风。

目标测试：

• BarkDetector：超过阈值且间隔足够时计为一次叫声。
• BarkDetector：持续噪音不会无限增加叫声次数。
• EnergyTugOfWar：玩家 power 高于对手时 energy 向玩家侧移动。
• EnergyTugOfWar：energy 被 clamp 在 -100 到 100。
• BarkBattleSession：倒计时归零后进入 finished。
• BarkBattleSession：根据 energy 判定 player/opponent/draw。

第二轮：应用层测试

• 模拟音频 sample 输入，验证 session snapshot 更新。
• 模拟 AI 对手 power，验证能量条拉锯。
• 模拟权限失败，验证 phase 不进入 playing。

第三轮：组件 / 集成测试

• HUD 根据 snapshot 显示倒计时。
• HUD 根据 energy 渲染红蓝能量条比例。
• 权限拒绝时显示重试入口。
• 结算阶段显示胜负与再来一局。

第四轮：浏览器 smoke / playtest

• 本地启动页面。
• 授权麦克风。
• 对麦克风发声后看到拟声词与能量条变化。
• 移动端宽度下主游戏画面不被 HUD 遮挡。

建议文件结构

如果作为独立前端玩法原型，可采用：

src/games/bark-battle/
  domain/
    BarkBattleSession.ts
    BarkDetector.ts
    EnergyTugOfWar.ts
    BarkBattleScoring.ts
    OpponentStrategy.ts
  application/
    BarkBattleController.ts
    BrowserMicrophoneInput.ts
  phaser/
    BarkBattleScene.ts
    BarkBattlePreloadScene.ts
    barkBattleAssets.ts
  ui/
    BarkBattleHud.tsx
    BarkBattleResultPanel.tsx
    BarkBattlePermissionPanel.tsx
  tests/
    BarkDetector.test.ts
    EnergyTugOfWar.test.ts
    BarkBattleSession.test.ts

如果接入 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

MVP 阶段建议先做浏览器单机 runtime 原型，再决定是否进入创作入口、作品发布、广场和后端持久化。

UI / 视觉方向

画面

• 横版固定舞台。
• 左右两只狗对峙。
• 背景可先做公园一张图，后续扩展海边、街区等地图。
• 狗狗用 2D sprite 或简单骨架帧动画。

HUD

• 顶部：红蓝声浪能量条。
• 中央：大号倒计时，只在开局和关键时间突出显示。
• 左右：双方狗狗状态，不堆叠复杂面板。
• 底部或角落：麦克风状态、小型重试按钮。
• 结算：居中弹出简洁面板，显示胜负和关键数据。

动效

• 叫声触发狗狗张嘴。
• 声音越大，拟声词越大，冲击波越宽。
• combo 时触发短暂屏幕震动，但不能遮挡能量条。
• 尊重 reduced motion，非必要动画可降级。

测试映射

BDD 场景	测试层级	目标文件	状态
玩家允许麦克风权限后进入准备倒计时	application/component	BarkBattleController.test.ts, BarkBattlePermissionPanel.test.tsx	planned
玩家拒绝麦克风权限	application/component	BarkBattleController.test.ts, BarkBattlePermissionPanel.test.tsx	planned
玩家发出一次有效狗叫	unit	BarkDetector.test.ts	planned
玩家连续大声狗叫压制对手	unit/integration	EnergyTugOfWar.test.ts, BarkBattleController.test.ts	planned
环境噪音低于阈值不计入叫声	unit	BarkDetector.test.ts	planned
倒计时结束时玩家侧占优	unit	BarkBattleSession.test.ts	planned
倒计时结束时双方接近平衡	unit	BarkBattleSession.test.ts	planned
当前浏览器不支持麦克风 API	component	BarkBattlePermissionPanel.test.tsx	planned
移动端进入对战页面	visual/smoke	Playwright 或人工 playtest 清单	planned

验证命令建议

具体命令以后续实际落地位置为准，建议包括：

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

若接入 Genarrative 后端或玩法配置，还需要追加：

cd server-rs && cargo check -p api-server -p shared-contracts --no-default-features
npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts

实施阶段拆分

Phase 0：产品与技术定稿

• 确认玩法 ID：bark-battle。
• 确认 MVP 只做单机玩家 vs AI，不做实时多人。
• 确认是否只做 runtime 原型，还是接入 Genarrative 创作入口。
• 确认是否允许浏览器麦克风权限作为核心输入。

Phase 1：纯领域模型

• 建立 bark-battle domain。
• 按 TDD 写 BarkDetector、EnergyTugOfWar、BarkBattleSession 测试。
• 实现最小规则让测试通过。

Phase 2：麦克风输入适配

• 封装 Web Audio API。
• 支持权限请求、权限失败、环境噪音校准。
• 使用 mock input 完成自动化测试，真实麦克风做 smoke。

Phase 3：Phaser 2D runtime

• 新建 Phaser Scene。
• 绘制或占位加载公园背景、左右狗狗、声浪特效。
• Scene 只消费 snapshot，不写规则。
• 接入 DOM HUD。

Phase 4：反馈与结算

• 加入拟声词、冲击波、狗狗张嘴动画。
• 加入结算面板。
• 加入再来一局与返回入口。

Phase 5：Genarrative 集成可选项

若要正式接入玩法类型：

• 补 shared-contracts 中 bark-battle runtime/result DTO。
• 补前端 service 与 runtime shell。
• 补入口配置数据库 seed。
• 补作品架 / 发布 / 广场链路，若需要持久化成绩或作品。
• 按 genarrative-play-type-integration 执行完整闭环验证。

风险与权衡

麦克风权限风险

浏览器麦克风权限受 HTTPS、浏览器策略、用户设置影响。MVP 需要明确：

• 本地开发可在 localhost 使用。
• 线上必须 HTTPS。
• 权限拒绝需要可恢复。

声音识别准确性风险

MVP 不建议做复杂“是否真的是狗叫”的 AI 识别，否则实现成本高、误判多。建议先用：

• 音量阈值
• 峰值次数
• 节奏间隔
• 环境噪音校准

后续再考虑加入频谱特征或 ML 分类。

噪音作弊风险

玩家可以喊叫、拍桌子或播放音频。若是娱乐派对玩法可以接受；若要竞技公平，需要后续加入：

• 频谱特征
• 输入冷却
• 异常持续噪音削弱
• 本地/服务端反作弊策略

移动端兼容风险

移动端 Web Audio 可能需要用户手势激活 AudioContext。计划中需把“开始”按钮作为显式用户手势，避免自动启动失败。

UI 遮挡风险

视频原型中的核心可读信息非常少：倒计时、能量条、狗狗、拟声词。实现时应避免把说明文案、复杂面板长期铺在画面上。

开放问题

1. MVP 是“玩家 vs AI”，还是需要从第一版开始支持双人同屏 / 联机？
2. 是否要作为 Genarrative 新玩法入口完整接入，还是先做独立 runtime 原型？
3. 是否需要记录成绩、发布作品、进入作品架和广场？
4. 狗狗与背景素材是使用临时占位、AI 生成，还是需要复用项目既有素材系统？
5. 是否允许游戏强依赖麦克风权限，还是必须提供键盘备用输入？

推荐下一步

建议下一步先执行 Phase 0 + Phase 1：

1. 明确 MVP 边界：单机玩家 vs AI。
2. 写 BarkDetector / EnergyTugOfWar / BarkBattleSession 的 BDD 对应单元测试。
3. 不接 Phaser、不接麦克风，先把核心规则用 TDD 跑通。
4. 规则稳定后再接 Web Audio 与 Phaser runtime。