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

562 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 声控狗叫对战 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 只负责渲染、动画、相机、输入适配。
因此本方案采用:
- RuntimePhaser 3
- LanguageTypeScript
- BuildVite
- UIReact/DOM HUD overlay 或项目现有 DOM UI 层
- Audio inputWeb Audio API + MediaDevices.getUserMedia
- Simulation纯 TS domain/service 层
- RendererPhaser 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. 重开 / 返回
- 支持再来一局。
- 支持返回玩法入口或结果页。
## 规则设计
### 关键状态
```ts
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 先用音量 + 峰值节奏。
#### 推动力计算
```text
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 行为场景
### 功能: 麦克风授权与准备
```gherkin
功能: 狗叫对战麦克风准备
场景: 玩家允许麦克风权限后进入准备倒计时
假如
那么
而且
场景: 玩家拒绝麦克风权限
假如
那么
而且
而且
```
### 功能: 声音推动能量条
```gherkin
功能: 声音大小和叫声次数推动能量条
场景: 玩家发出一次有效狗叫
假如 playing
而且
那么 1
而且
而且
场景: 玩家连续大声狗叫压制对手
假如 playing
而且
那么
而且
场景: 环境噪音低于阈值不计入叫声
假如 playing
那么
而且
```
### 功能: 限时胜负结算
```gherkin
功能: 狗叫对战胜负结算
场景: 倒计时结束时玩家侧占优
假如
而且
那么
而且
场景: 倒计时结束时双方接近平衡
假如
而且
那么
而且
```
### 功能: 移动端与无麦克风降级
```gherkin
功能: 声控游戏移动端与无麦克风降级
场景: 当前浏览器不支持麦克风 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 遮挡。
## 建议文件结构
如果作为独立前端玩法原型,可采用:
```text
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` 扩展:
```text
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 |
## 验证命令建议
具体命令以后续实际落地位置为准,建议包括:
```bash
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 后端或玩法配置,还需要追加:
```bash
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 3Phaser 2D runtime
- 新建 Phaser Scene。
- 绘制或占位加载公园背景、左右狗狗、声浪特效。
- Scene 只消费 snapshot不写规则。
- 接入 DOM HUD。
### Phase 4反馈与结算
- 加入拟声词、冲击波、狗狗张嘴动画。
- 加入结算面板。
- 加入再来一局与返回入口。
### Phase 5Genarrative 集成可选项
若要正式接入玩法类型:
-`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。