176 lines
9.4 KiB
Markdown
Executable File
176 lines
9.4 KiB
Markdown
Executable File
# v0.4 回响编年史 · Chronicle of Echoes
|
||
|
||
> 跨周目叙事时间轴系统。每次飞升自动铭刻一条纪元条目，记录本周目的解码、探险、星潮、天赋觉醒与里程碑，形成永恒叙事流。朝 v0.5「全 5 纪元叙事」目标推进。
|
||
|
||
## 动机
|
||
|
||
- **回应 Issue #1**「就一直连连看？」的进一步反馈：星潮+星图解决了「玩法单一」，但仍缺**叙事深度**与**进度回顾**。
|
||
- 玩家完成多次飞升后无回顾入口，对「自己走过多远」缺乏感知，影响长线留存。
|
||
- v0.5 路线图为「全 5 纪元叙事」，编年史是其底层骨架——先把数据结构与展示框架立起来。
|
||
|
||
## 核心模块
|
||
|
||
### 数据模型（`src/lib/game/types.ts`）
|
||
|
||
```ts
|
||
export interface ChronicleEntry {
|
||
ascensionNumber: number; // 第几次飞升（1-based）
|
||
epochName: string; // 程序化生成的纪元名（5 纪元循环）
|
||
timestamp: number;
|
||
durationSec: number; // 本周目持续时间
|
||
summary: {
|
||
techsUnlocked: number;
|
||
constellationsTotal: number;
|
||
expeditionsCompleted: number;
|
||
bossKills: number;
|
||
starTidesEncountered: number;
|
||
blueprintsAfter: number;
|
||
crystalsDecoded: number;
|
||
crystalsDecodedThisRun: number;
|
||
};
|
||
perksThisAscension: string[]; // 本次飞升后选择的天赋
|
||
tidesThisRun: string[]; // 本周目新遇到的星潮 ID
|
||
lore: string; // 程序化生成的叙事文本
|
||
milestones: string[]; // 里程碑标签
|
||
}
|
||
|
||
export interface RunStartSnapshot {
|
||
timestamp: number;
|
||
techsUnlocked: number;
|
||
expeditionsCompleted: number;
|
||
bossKills: number;
|
||
starTidesEncountered: string[];
|
||
crystalsDecoded: number;
|
||
}
|
||
```
|
||
|
||
GameState 新增字段：
|
||
- `chronicle: ChronicleEntry[]` — 编年史条目列表（上限 50）
|
||
- `runStart: RunStartSnapshot` — 当前周目起始快照（用于 delta 计算）
|
||
- `bossKills: number` — 累计 BOSS 击破数（跨周目）
|
||
- `starTidesEncountered: string[]` — 累计遇到的星潮 ID 集合（去重）
|
||
|
||
### 编年史逻辑（`src/lib/game/chronicle.ts`，新建）
|
||
|
||
- `EPOCH_NAMES` — 5 纪元 × 4 后缀 = 20 种纪元名组合（如「第一纪元 · 觉醒之晨」「第三纪元 · 虚空回望」）
|
||
- `generateEpochName(ascensionNumber, seed)` — 按 ascensionNumber 循环 5 纪元，seed 决定后缀
|
||
- `buildLore(entry)` — 模板化叙事生成：开场 → 核心活动 → 星潮段落 → 觉醒段落 → 里程碑 → 收尾
|
||
- `detectMilestones(state, deltas)` — 9 种里程碑检测（首次飞升/首杀 BOSS/单周目解码 10+/技术狂人/星潮亲历者/星图六分等）
|
||
- `computeRunDeltas(state)` — 基于 runStart 快照计算本周目 delta（持续时间/解码数/技术数/探险数/BOSS/新星潮）
|
||
- `buildChronicleEntry(state, perks)` — 飞升时构建一条 ChronicleEntry
|
||
- `createRunStartSnapshot(state)` — 飞升后创建新 runStart
|
||
- `migrateChronicleFields(state)` — 旧存档兼容：补全 chronicle=[]/runStart/bossKills=0/starTidesEncountered=[]
|
||
- `withPerks(entry, perks)` — 飞升后选天赋时回填 perksThisAscension，并重新生成 lore 包含天赋名
|
||
- `getPerkCategoryBreakdown(perks)` / `getCategoryName` / `getCategoryColor` — UI 辅助
|
||
|
||
### 引擎接入（`src/lib/game/engine.ts`）
|
||
|
||
- `performPrestige` 在重置前：
|
||
1. `buildChronicleEntry(state, [])` 构建本周目条目（perks 暂为空，待玩家选择后回填）
|
||
2. 追加到 `chronicle` 数组（上限 50 条）
|
||
3. `createRunStartSnapshot(state)` 创建新周目的快照
|
||
- 保留跨周目字段：`chronicle`, `bossKills`, `starTidesEncountered`
|
||
- 重置 `runStart` 为新快照
|
||
|
||
### Store 接入（`src/store/gameStore.ts`）
|
||
|
||
- `init()` — 调用 `migrateChronicleFields` 补全旧存档
|
||
- `tickTide` — 新星潮触发时，将 `tide_${type}` 追加到 `starTidesEncountered`（去重）
|
||
- `resolveCurrentNode` — BOSS 战胜利结算时，`bossKills++`
|
||
- `chooseConstellationPerk` — 选择天赋后，调用 `withPerks` 回填最近一条 chronicle entry 的 `perksThisAscension`，并重新生成 lore
|
||
|
||
### UI 组件（`src/components/game/ChronicleDialog.tsx`，新建）
|
||
|
||
- 顶部 BookOpen 图标按钮（带 badge 显示条目数）
|
||
- 全屏对话框，深紫黑渐变背景 + 顶部三色装饰条
|
||
- 顶部总览统计：飞升次数 / BOSS 击破 / 星潮亲历
|
||
- 垂直时间轴：
|
||
- 左侧渐变时间轴线
|
||
- 每条卡片左侧有发光圆形节点（5 纪元循环色：翠/玫/琥/紫/金），最新一条带 ping 动画
|
||
- 卡片含：#编号 / 纪元名（带 textShadow 光晕）/ 时间戳+持续时长 / 叙事文本（衬线字体）/ 6 项统计芯片 / 星潮徽章列表 / 天赋徽章 / 里程碑徽章
|
||
- 入场动画：fade-in + slide-up，错峰 80ms
|
||
- 空状态：根据 ascensions 是否 > 0 显示不同提示
|
||
- 打开时播放 `chronicleOpen` 翻页音效
|
||
|
||
### 音频（`src/lib/game/audio.ts`）
|
||
|
||
- `chronicle` — 编年史铭刻音效：G3 基音 + C4/G4/C5/G5 多层泛音，深沉钟声感
|
||
- `chronicleOpen` — 翻页音效：A4→D5→A5 轻柔上升 + 短促气流
|
||
- 飞升成功时延迟 600ms 触发 `chronicle` sfx，与飞升音分层
|
||
|
||
### 成就（`src/lib/game/achievements.ts`）
|
||
|
||
新增 6 项成就：
|
||
- `ach_chronicle_1` 「首部编年」— 完成首次飞升（+40 洞见 · 产能 +6%）
|
||
- `ach_chronicle_3` 「三纪元回响」— 完成 3 次飞升（产能 +10% · 洞见 +10%）
|
||
- `ach_chronicle_5` 「五纪元闭环」— 完成 5 次飞升（产能 +15% · 洞见 +15%）
|
||
- `ach_boss_1` 「首杀维度」— 击破首个 BOSS（+25 洞见 · 产能 +4%）
|
||
- `ach_boss_5` 「维度猎手」— 累计击破 5 个 BOSS（产能 +10% · 洞见 +8%）
|
||
- `ach_tides_all` 「星潮亲历者」— 经历全部 6 种星潮（产能 +8% · 洞见 +8%）
|
||
|
||
### 飞升对话框增强（`src/components/game/PrestigeDialog.tsx`）
|
||
|
||
- 新增「编年史铭刻预告」卡片，提示本次飞升将记录入编年史
|
||
- **修复关键 BUG**：原 `disabled={newBp <= 0 || confirming}` 当 `confirming=true` 时按钮永久禁用，玩家无法完成飞升！现已改为 `disabled={confirming && !canReconfirm}` 并加 900ms 冷却窗口
|
||
- **修复 UX**：当 newBp=0（无可获蓝图）时不再永久禁用飞升按钮——v0.3.1 星图天赋 + v0.4 编年史已为飞升提供足够动机。按钮文字改为「飞升（无新蓝图）」
|
||
- 飞升成功 toast 增加「编年史已铭刻新纪元」提示
|
||
|
||
### 统计面板增强（`src/app/page.tsx`）
|
||
|
||
新增 3 行统计：
|
||
- BOSS 击破次数
|
||
- 星潮亲历数（X/6）
|
||
- 编年史条目数（X 纪元）
|
||
|
||
## QA 验证
|
||
|
||
### 修复的关键 BUG
|
||
- 飞升按钮 `disabled` 逻辑错误导致玩家永远无法飞升（`confirming` 变 true 后按钮被禁用）
|
||
- 验证：agent-browser 端到端测试，第一次点飞升 → 900ms 冷却 → 第二次点击成功触发，星图觉醒对话框弹出
|
||
|
||
### 编年史端到端测试
|
||
1. 设置 contact=100 + 资源，触发飞升 → ascensions 1→2, chronicle 0→1 ✓
|
||
2. 选择天赋「二周目经验」→ constellation 增加 c_cos_2, chronicle 末条 perksThisAscension=["c_cos_2"] ✓
|
||
3. 打开编年史对话框 → 显示 1 条卡片，含完整 lore、统计芯片、星潮徽章、天赋徽章、里程碑 ✓
|
||
4. 再次飞升 → ascensions 2→3, chronicle 1→2 ✓
|
||
5. 第二条卡片正确显示新纪元名「第三纪元 · 虚空回望」+ 正确的星潮名「星核悸动」+ 正确的 duration delta（2分42秒） ✓
|
||
6. 成就解锁：`ach_chronicle_1`「首部编年」+ `ach_prestige_3`自动检测 ✓
|
||
7. 统计面板新增「BOSS 击破」「星潮亲历」「编年史条目」3 行 ✓
|
||
8. VLM 视觉评估：8/10，无瑕疵，时间轴清晰，纪元颜色区分明显
|
||
|
||
### 视觉细节
|
||
- 5 纪元循环色：翠 #34d399 / 玫 #fb7185 / 琥 #fbbf24 / 紫 #e879f9 / 金 #fcd34d
|
||
- 时间轴节点带 boxShadow 光晕（12px + 24px 双层）
|
||
- 最新条目带 animate-ping 脉冲
|
||
- 卡片入场动画：fade-in + slide-in-from-bottom-2，错峰 80ms
|
||
- 叙事文本使用 font-serif 衬线字体增加文学感
|
||
- 统计芯片按类别用对应颜色 tint
|
||
|
||
### 旧存档兼容
|
||
- `migrateChronicleFields` 自动补全 chronicle=[]/runStart/bossKills=0/starTidesEncountered=[]
|
||
- 玩家旧存档不丢失进度，新字段以默认值初始化
|
||
|
||
## 文件清单
|
||
|
||
新增：
|
||
- `src/lib/game/chronicle.ts` — 编年史核心逻辑
|
||
- `src/components/game/ChronicleDialog.tsx` — 编年史对话框 UI
|
||
- `docs/repo/docs/09-回响编年史系统-v0.4.md` — 本文档
|
||
|
||
修改：
|
||
- `src/lib/game/types.ts` — 新增 ChronicleEntry / RunStartSnapshot 类型 + GameState 字段
|
||
- `src/lib/game/config.ts` — INITIAL_STATE 新增 chronicle/runStart/bossKills/starTidesEncountered
|
||
- `src/lib/game/engine.ts` — performPrestige 构建编年史条目 + 重置 runStart
|
||
- `src/lib/game/achievements.ts` — 新增 6 项成就
|
||
- `src/lib/game/audio.ts` — 新增 chronicle / chronicleOpen 音效
|
||
- `src/store/gameStore.ts` — init 兼容 + tickTide 记录 + resolveCurrentNode BOSS 计数 + chooseConstellationPerk 回填
|
||
- `src/components/game/PrestigeDialog.tsx` — 修复 BUG + 编年史预告卡片 + 音效
|
||
- `src/app/page.tsx` — 头部编年史按钮 + 对话框渲染 + 统计面板新行 + 版本号 v0.4
|
||
|
||
## 已知限制 / 后续
|
||
|
||
- 编年史上限 50 条（超过自动丢弃最早的）
|
||
- v0.4 之前发生的飞升不会被回填（无数据可恢复）—— 空状态有对应提示
|
||
- 5 纪元叙事内容仍为模板化生成，v0.5 将加入手写剧情节点
|
||
- 编年史目前纯本地，v0.4 云存档+排行榜会将其纳入同步范围
|