docs: v0.5 深空信标系统文档
This commit is contained in:
@@ -0,0 +1,151 @@
|
||||
# 深空信标系统 · v0.5（每日挑战 + 本地排行榜）
|
||||
|
||||
> 版本：v0.5 · 日期：2026-06-23
|
||||
> 路线图对应：v0.5 排行榜（本地版先行）+ 每日挑战动机注入
|
||||
|
||||
## 动机
|
||||
|
||||
v0.4 编年史系统完成后，游戏已有 6 大玩法层（采矿/解码/技术树/图谱/飞升 + 探险 + 星图 + 星潮 + 编年史），但缺少"今日目标"型的短期动机。玩家进入游戏后没有明确的"今天该做什么"指引。
|
||||
|
||||
本版本新增**深空信标（Deep Space Beacon）**系统：
|
||||
- **每日挑战**：基于 UTC 日期种子的确定性挑战，全球同一天同一挑战，每天 0 点（UTC）刷新
|
||||
- **本地排行榜**：记录历次挑战得分，Top 20，纯 localStorage 持久化，无需后端
|
||||
- 给放置循环注入"今日目标"，并为 v0.5 路线图的"云排行榜"奠定数据结构基础
|
||||
|
||||
## 核心设计
|
||||
|
||||
### 每日挑战（Daily Challenge）
|
||||
|
||||
- **确定性生成**：`generateDailyChallenge(now)` 基于 UTC 日期 key（YYYY-MM-DD）派生 FNV-1a 种子 → mulberry32 PRNG，保证同一天全球玩家看到同一挑战
|
||||
- **5 种挑战类型**：
|
||||
| 类型 | 标签 | 目标范围 | 单位 |
|
||||
|------|------|----------|------|
|
||||
| `decode` | 解码协议 | 6-15 × 难度倍率 | 颗 |
|
||||
| `expedition` | 远征指令 | 1-3 × 难度倍率 | 次 |
|
||||
| `pulse` | 脉冲任务 | 20-49 × 难度倍率 | 次 |
|
||||
| `boss` | 猎杀契约 | 1 × 难度倍率 | 处 |
|
||||
| `insight` | 洞见采集 | 40-119 × 难度倍率 | 点 |
|
||||
- **3 档难度**（加权抽取）：
|
||||
| 难度 | 标签 | 倍率 | 权重 | 颜色 |
|
||||
|------|------|------|------|------|
|
||||
| `routine` | 常规信标 | ×1.0 | 55% | 翠 |
|
||||
| `anomaly` | 异常波动 | ×1.6 | 33% | 琥 |
|
||||
| `singular` | 奇点回响 | ×2.4 | 12% | 玫 |
|
||||
- **奖励**：完成时按类型 + 难度发放洞见 / 接触进度
|
||||
- **倒计时**：显示距 UTC 次日 0 点的 HH:MM:SS 倒计时
|
||||
|
||||
### 得分计算
|
||||
|
||||
```
|
||||
得分 = 完成度 × 1000 × 难度倍率 + 速度奖励
|
||||
速度奖励 = max(0, 500 - 完成时长秒 × 0.5) // 仅完成时计算
|
||||
```
|
||||
|
||||
例：常规难度 × 1.0，90 秒完成 → 1000 + (500 - 45) = 1455 分
|
||||
|
||||
### 进度追踪（独立 localStorage）
|
||||
|
||||
- 进度独立存储于 `echo-nexus-beacon-prog-v1`，**不污染 GameState**，避免触发存档迁移
|
||||
- 在 gameStore 关键动作后调用 `trackBeacon(type, delta)`：
|
||||
- `pulse`：每次脉冲 +1
|
||||
- `decode`：每次解码完成 +1（手动 + 自动解码均计）
|
||||
- `expedition`：每次探险结束 +1（胜负都计）
|
||||
- `boss`：每次 BOSS 胜利 +1
|
||||
- `insight`：每次洞见获取按数值累加
|
||||
- 挑战类型与今日挑战不匹配时 `trackBeacon` 直接 return，零开销
|
||||
|
||||
### 本地排行榜
|
||||
|
||||
- 存储于 `echo-nexus-beacon-lb-v1`，Top 20，按得分降序
|
||||
- 每条记录含：时间戳 / 日期 key / 挑战类型 / 难度 / 完成度 / 得分 / 用时
|
||||
- UI：奖牌图标（1st 金 / 2nd 银 / 3rd 铜）+ 难度色点 + 类型名 + 用时 + 得分
|
||||
- 今日记录高亮（fuchsia 边框）
|
||||
|
||||
## 文件变更
|
||||
|
||||
### 新增
|
||||
- `src/lib/game/beacon.ts`（~290 行）：核心逻辑模块
|
||||
- `generateDailyChallenge()` — 确定性挑战生成
|
||||
- `computeBeaconScore()` — 得分计算
|
||||
- `loadLeaderboard()` / `pushLeaderboardEntry()` — 排行榜 CRUD
|
||||
- `loadDailyProgress()` / `saveDailyProgress()` / `addBeaconProgress()` — 进度 CRUD
|
||||
- `claimBeaconReward()` — 领取奖励 + 推送排行榜
|
||||
- `msUntilNextDay()` / `formatCountdown()` — 倒计时
|
||||
- `src/components/game/BeaconPanel.tsx`（~280 行）：UI 面板
|
||||
- 每日挑战卡片（难度色 + 脉冲环动画 + 进度条 + 领取按钮）
|
||||
- 本地排行榜（Top 20 + 奖牌 + 今日高亮）
|
||||
- 难度图例
|
||||
- 倒计时
|
||||
|
||||
### 修改
|
||||
- `src/store/gameStore.ts`：
|
||||
- 新增 `trackBeacon()` 模块级辅助函数
|
||||
- 新增 `grantBeaconReward(insights, contact)` action
|
||||
- 在 `pulse` / `clickNode`(完成) / `autoDecodeTick` / `resolveCurrentNode` 后接入 `trackBeacon`
|
||||
- `src/app/page.tsx`：
|
||||
- 新增第 7 个标签页「信标」（grid-cols-7）
|
||||
- 新增 `beaconClaimable` 状态（2s 轮询，可领取时显示绿点）
|
||||
- StatsPanel 新增「信标最高分」行
|
||||
- 版本号 v0.4 → v0.5
|
||||
- `src/lib/game/chronicle.ts`：
|
||||
- 导出 `buildLore()`（原私有）
|
||||
- 新增 `regenerateLoreFromEntry(entry)` — 显示时重新生成 lore，修复历史条目中 `tide_ruins` 等原始键名
|
||||
- `src/components/game/ChronicleDialog.tsx`：叙事文本改用 `regenerateLoreFromEntry(entry)` 替代 `entry.lore`
|
||||
|
||||
## BUG 修复
|
||||
|
||||
### 编年史历史条目显示原始 tide 键名
|
||||
- **现象**：v0.4 之前创建的编年史条目 lore 中显示 `tide_ruins` 而非「遗迹共振」（最新条目已修复，旧条目未回填）
|
||||
- **根因**：lore 文本在条目创建时一次性生成并存储，历史条目存储了修复前的错误文本
|
||||
- **修复**：新增 `regenerateLoreFromEntry()`，在 ChronicleDialog 显示时从 entry 的结构化数据（tidesThisRun / perksThisAscension / milestones）重新生成 lore，保证历史与未来条目命名一致
|
||||
- **验证**：第二纪元 lore 现正确显示「遗迹共振、晶体潮、虚空低语、谐振风暴」
|
||||
|
||||
## QA 验证（agent-browser + VLM）
|
||||
|
||||
### 编年史 BUG 修复验证
|
||||
- ✅ 第二纪元 lore 显示「遗迹共振、晶体潮、虚空低语、谐振风暴」（修复前显示 `tide_ruins` 等原始键）
|
||||
- ✅ 第三纪元 lore 保持正确「星核悸动」
|
||||
- ✅ 徽章显示正确
|
||||
|
||||
### 深空信标系统验证
|
||||
- ✅ 第 7 个标签页「信标」渲染正确
|
||||
- ✅ 每日挑战卡片：难度标签 + 类型标签 + 标题 + 描述 + 进度条 + 奖励 + 领取按钮
|
||||
- ✅ 倒计时显示「08:47:12」并每秒更新
|
||||
- ✅ 难度图例显示 3 档（×1 / ×1.6 / ×2.4）
|
||||
- ✅ 进度追踪：解码 1 颗晶体 → 洞见采集进度 +12（解码奖励的洞见值）
|
||||
- ✅ 完成挑战后按钮变为「领取奖励」
|
||||
- ✅ 领取奖励后：contact +5.1（13.47 → 18.57），按钮变「已领取」
|
||||
- ✅ 排行榜生成条目：「洞见采集 ✓ 1m30s 1.46K」
|
||||
- ✅ 统计面板新增「信标最高分」行
|
||||
- ✅ 可领取时标签页显示绿点提示
|
||||
- ✅ VLM 视觉评估：高美观度，颜色搭配佳，无重叠 bug
|
||||
|
||||
### 全系统回归验证
|
||||
- ✅ 主视图（资源条 / 晶体球 / 解码面板）正常
|
||||
- ✅ 探险全流程（出发 → 探索 → 前进 → BOSS → 结束 → 日志）正常
|
||||
- ✅ 解码谜题生成 + 自动求解通过
|
||||
- ✅ 星潮事件触发 + 指示器 + Footer 联动正常
|
||||
- ✅ 成就解锁 Toast 正常
|
||||
- ✅ 星图标签页（9/18 天赋，6 类别）正常
|
||||
- ✅ 编年史对话框（2 条目，时间轴，里程碑）正常
|
||||
- ✅ lint 零错误；HTTP 200；编译 < 250ms
|
||||
|
||||
## 路线图进展
|
||||
|
||||
- [x] v0.1 MVP：放置采矿 + 解码 + 技术树 + 图谱 + 飞升
|
||||
- [x] v0.1.1：解码可解性修复
|
||||
- [x] v0.2：遗迹探险肉鸽
|
||||
- [x] v0.2.1：程序化音频 + 成就系统
|
||||
- [x] v0.3：星潮事件系统
|
||||
- [x] v0.3.1：星图天文台元进程
|
||||
- [x] v0.4：回响编年史
|
||||
- [x] **v0.5：深空信标（每日挑战 + 本地排行榜）** ← 本轮
|
||||
- [ ] v0.5+：云存档 + 云排行榜（后端同步）
|
||||
- [ ] v0.5+：全 5 纪元手写叙事节点
|
||||
- [ ] 后续：socket 多人同步星潮
|
||||
|
||||
## 下一阶段优先
|
||||
|
||||
1. 云存档 + 云排行榜（需后端 API，可将本地 localStorage 同步到服务端）
|
||||
2. 全 5 纪元手写叙事节点（替换模板化 lore）
|
||||
3. socket 多人同步星潮（全局事件，所有在线玩家同时经历）
|
||||
Reference in New Issue
Block a user