From 51714d25321c8d82cd96b45d57ef02818af8a444 Mon Sep 17 00:00:00 2001 From: Super_Z <1401203083@qq.com> Date: Tue, 23 Jun 2026 13:36:44 +0000 Subject: [PATCH] =?UTF-8?q?feat(v0.2.1):=20=E7=A8=8B=E5=BA=8F=E5=8C=96?= =?UTF-8?q?=E9=9F=B3=E9=A2=91=E7=B3=BB=E7=BB=9F=20+=2014=E9=A1=B9=E6=88=90?= =?UTF-8?q?=E5=B0=B1=E7=B3=BB=E7=BB=9F=20+=20=E8=84=89=E5=86=B2=E7=B2=92?= =?UTF-8?q?=E5=AD=90=E6=89=93=E7=A3=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 音频: Web Audio API 程序化合成 15 种音效(脉冲/解码/探险/飞升/成就), 零资源文件 - 成就: 14项成就, 跨周目永久产能/洞见加成, Toast通知+专属音效 - 视觉: 脉冲粒子爆发, 扩散环, 浮动数字按连击变色 - UI: 标签栏5列(+成就页), 统计面板扩展, 设置页音效试听 - 兼容: 旧存档自动补全 achievements 字段 --- docs/06-音频与成就系统-v0.2.1.md | 161 +++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/06-音频与成就系统-v0.2.1.md diff --git a/docs/06-音频与成就系统-v0.2.1.md b/docs/06-音频与成就系统-v0.2.1.md new file mode 100644 index 000000000..d3f7b0d04 --- /dev/null +++ b/docs/06-音频与成就系统-v0.2.1.md @@ -0,0 +1,161 @@ +# 回响星核 v0.2.1 — 音频系统 + 成就系统 + 视觉打磨 + +> 版本：v0.2.1 +> 日期：2026-06-23 +> 范围：程序化音频引擎、14 项成就系统、脉冲粒子爆发、UI 打磨 + +--- + +## 一、程序化音频系统（Web Audio API，零资源文件） + +### 设计目标 +- 无需任何外部音频文件，全部由振荡器 + 噪声 + 包络合成 +- 音色契合"深空考古 / 全息晶体"美学：谐振、水晶、低频脉冲 +- 受 `soundOn` 开关控制，支持浏览器自动播放策略（首次用户交互后初始化 AudioContext） + +### 实现 +- **文件**：`src/lib/game/audio.ts`（AudioEngine 单例 + 15 种音效） +- **Hook**：`src/hooks/useAudio.ts`（`useAudioSync` 同步开关，`sfx()` 便捷播放） + +### 音效清单 +| 音效名 | 触发场景 | 合成方式 | +|--------|---------|---------| +| pulse | 主动脉冲 | 上升正弦短音 + 三角波泛音 | +| pulseCombo | 连击≥3 脉冲 | 更高基频 + 多泛音 | +| decodeClick | 解码点击节点 | 按颜色变调（C5/D5/E5/F5）+ 泛音 | +| decodeFail | 解码点击错误 | 低频锯齿 + 噪声脉冲 | +| decodeSuccess | 解码成功 | 大三和弦琶音上扬 | +| fragmentUnlock | 记忆碎片浮现 | 空灵长音 + 扫频 | +| techBuy | 购买技术 | 双音确认 | +| expeditionStart | 探险出发 | 低频锯齿扫频 + 噪声（引擎启动感） | +| expeditionNode | 探险节点结算 | 三角波中频 | +| expeditionVictory | 探险胜利 | 上行凯旋和弦 | +| expeditionDefeat | 探险失败 | 下行低音 | +| prestige | 飞升 | 宏大扫频 + 和弦堆叠 | +| achievement | 成就解锁 | 亮丽四音琶音 | +| uiHover | 界面悬停 | 极轻正弦 | +| uiClick | 界面点击 | 轻确认 | + +### 接入点 +- `CrystalOrb`：pulse / pulseCombo +- `DecodeArray`：decodeClick（按颜色变调）/ decodeFail / decodeSuccess / fragmentUnlock +- `ExpeditionPanel`：expeditionStart / expeditionNode / expeditionVictory / expeditionDefeat +- `TechTree`：techBuy +- `PrestigeDialog`：prestige +- `AchievementNotifier`：achievement +- `SettingsDialog`：新增「试听」按钮（播放 decodeSuccess） + +--- + +## 二、成就系统（14 项，跨周目永久加成） + +### 设计目标 +- 给玩家长期目标与即时正反馈 +- 成就奖励包含即时资源 + 永久产能/洞见百分比加成（跨周目保留，与蓝图叠加） +- 解锁时 Toast 通知 + 专属音效 + +### 实现 +- **定义**：`src/lib/game/achievements.ts`（14 项成就 + `achievementBonuses` 聚合） +- **状态**：`GameState.achievements: Record` +- **检测**：`gameStore.checkAchievements()` 每秒由主循环调用；页面可见性恢复时立即检测 +- **通知**：`AchievementNotifier` 组件消费 `_achievementQueue`，弹 Toast + 播音效 +- **UI**：`AchievementsPanel` 组件，作为第 4 个标签页 + +### 成就列表 +| ID | 名称 | 条件 | 奖励 | +|----|------|------|------| +| ach_first_pulse | 初次触碰 | 发起第一次脉冲 | +5 晶体 | +| ach_first_decode | 谐振初鸣 | 解码第一颗晶体 | +3 洞见 | +| ach_decoded_10 | 回响解码者 | 累计解码 10 颗 | +15 洞见 · 产能 +5% | +| ach_decoded_25 | 记忆织匠 | 累计解码 25 颗 | +40 洞见 · 产能 +8% | +| ach_decoded_50 | 星核解密师 | 累计解码 50 颗 | +100 洞见 · 产能 +12% · 洞见 +10% | +| ach_tech_3 | 初窥门径 | 解锁 3 项技术 | +20 洞见 | +| ach_tech_all | 全谱精通 | 解锁全部 12 项技术 | 产能 +15% · 洞见 +15% | +| ach_frag_4 | 残篇拾遗 | 拼凑 4 段碎片 | +10 接触 · +25 洞见 | +| ach_frag_all | 回响全谱 | 拼凑全部 8 段碎片 | +25 接触 · 产能 +10% | +| ach_exp_1 | 初探遗迹 | 完成 1 次探险 | +10 洞见 | +| ach_exp_5 | 遗迹猎手 | 出发 5 次探险 | +30 洞见 · 产能 +5% | +| ach_prestige_1 | 初次接触 | 飞升 1 次 | 产能 +10% · 洞见 +10% | +| ach_prestige_3 | 维度行者 | 飞升 3 次 | 产能 +20% · 洞见 +20% | +| ach_warehouse | 满仓时刻 | 晶体达仓库上限 | +8 洞见 | + +### 加成计算 +`recomputeStats()` 现聚合三层数值来源： +1. 技术树节点效果 +2. 飞升蓝图加成（每张 +5% 产能 / +3% 洞见 / +4% 接触） +3. **成就永久加成**（跨周目保留，飞升后仍生效） + +### 旧存档兼容 +- `init()` 补全缺失的 `achievements` 字段为 `{}` +- `partialize` 排除 `_achievementQueue`（运行时临时队列不持久化） + +--- + +## 三、视觉打磨 + +### CrystalOrb 增强 +- **粒子爆发**：每次脉冲生成 6–12 个粒子，沿径向发散（连击越高粒子越多） +- **脉冲扩散环**：点击时从晶体向外扩散的绿色光环 +- **浮动数字变色**：连击≥3 紫色、≥5 琥珀色，带对应颜色光晕 +- 新增 `echo-ring` / `echo-burst` 关键帧动画 + +### 标签栏 +- 从 4 列扩展为 5 列（新增「成就」） +- 成就标签有未解锁时显示琥珀色脉冲点 +- 标签字号微调以适配 5 列 + +### StatsPanel +- 新增「已解锁成就」「累计探险」「探险能量」三行 + +--- + +## 四、QA 验证 + +### agent-browser 自动化测试 +- ✅ 页面加载 HTTP 200，无运行时错误 +- ✅ 解码谜题：生成 → 求解（按目标色序点击相邻同色节点）→ 奖励入账（绕过仓库上限） +- ✅ 探险系统：出发 → 探索节点 → 获得奖励 → 前进 → 日志记录 +- ✅ 成就面板：14 项渲染，3 项已解锁（初次触碰/谐振初鸣/满仓时刻），永久加成区域正确显示 +- ✅ 统计面板：成就计数 3/14，探险次数，能量条 +- ✅ 设置面板：音效试听按钮可点击，开关可用 + +### VLM 视觉验证 +- 成就面板：深色背景 + 科技光效 + 锁/解锁状态分明，色彩对比鲜明 +- 晶体集群：渐变晶核 + 旋转环 + 粒子爆发正常 + +### Lint +- `bun run lint` 零错误 + +--- + +## 五、文件变更清单 + +**新增**： +- `src/lib/game/audio.ts` — 程序化音频引擎 +- `src/hooks/useAudio.ts` — 音频 React 适配 +- `src/lib/game/achievements.ts` — 成就定义与聚合 +- `src/components/game/AchievementsPanel.tsx` — 成就面板 +- `src/components/game/AchievementNotifier.tsx` — 成就 Toast 消费者 + +**修改**： +- `src/lib/game/types.ts` — GameState 新增 `achievements` 字段 +- `src/lib/game/config.ts` — INITIAL_STATE 新增 `achievements: {}` +- `src/lib/game/engine.ts` — recomputeStats 聚合成就加成；performPrestige/createInitialState 保留成就 +- `src/store/gameStore.ts` — checkAchievements / consumeAchievementQueue；init/hardReset/partialize 兼容 +- `src/hooks/useGameLoop.ts` — 每秒检测成就 + 可见性恢复检测 +- `src/app/page.tsx` — 5 列标签 + 成就页 + AchievementNotifier + useAudioSync +- `src/components/game/CrystalOrb.tsx` — 粒子爆发 + 扩散环 + 浮动数字变色 + pulse 音效 +- `src/components/game/DecodeArray.tsx` — decodeClick/fail/success/fragment 音效 +- `src/components/game/ExpeditionPanel.tsx` — start/node/victory/defeat 音效 +- `src/components/game/TechTree.tsx` — techBuy 音效 +- `src/components/game/PrestigeDialog.tsx` — prestige 音效 +- `src/components/game/SettingsDialog.tsx` — 音效试听按钮 + 文案更新 + +--- + +## 六、下一步规划 + +- **v0.3 剩余**：socket 全局「星潮」实时事件（需 mini-service） +- **v0.4**：云存档 + 排行榜 +- **v0.5**：全 5 纪元叙事扩展 +- 持续关注 Gitea 工单