# 回响星核 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 工单