echo-nexus/docs/06-音频与成就系统-v0.2.1.md

回响星核 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<string, boolean>
• 检测：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 工单