diff --git a/.gitignore b/.gitignore index 3d67daa87..e2fc7eaaa 100644 --- a/.gitignore +++ b/.gitignore @@ -1,54 +1,148 @@ -# See https://help.github.com/articles/ignoring-files/ for more about ignoring files. - -# dependencies -node_modules -/.pnp -.pnp.* -.yarn/* -!.yarn/patches -!.yarn/plugins -!.yarn/releases -!.yarn/versions - -# testing -/coverage - -# next.js -/.next/ -/out/ - -# production -/build - -# misc -.DS_Store -*.pem - -# debug +# ---> Node +# Logs +logs +*.log npm-debug.log* yarn-debug.log* yarn-error.log* +lerna-debug.log* .pnpm-debug.log* -# env files (can opt-in for committing if needed) -.env* +# Diagnostic reports (https://nodejs.org/api/report.html) +report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json -# vercel -.vercel +# Runtime data +pids +*.pid +*.seed +*.pid.lock +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov -# typescript +# Coverage directory used by tools like istanbul +coverage +*.lcov + +# nyc test coverage +.nyc_output + +# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) +.grunt + +# Bower dependency directory (https://bower.io/) +bower_components + +# node-waf configuration +.lock-wscript + +# Compiled binary addons (https://nodejs.org/api/addons.html) +build/Release + +# Dependency directories +node_modules/ +jspm_packages/ + +# Snowpack dependency directory (https://snowpack.dev/) +web_modules/ + +# TypeScript cache *.tsbuildinfo -next-env.d.ts + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Optional stylelint cache +.stylelintcache + +# Microbundle cache +.rpt2_cache/ +.rts2_cache_cjs/ +.rts2_cache_es/ +.rts2_cache_umd/ + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# Yarn Integrity file +.yarn-integrity + +# dotenv environment variable files +.env +.env.development.local +.env.test.local +.env.production.local +.env.local + +# parcel-bundler cache (https://parceljs.org/) +.cache +.parcel-cache + +# Next.js build output +.next +out + +# Nuxt.js build / generate output +.nuxt +dist + +# Gatsby files +.cache/ +# Comment in the public line in if your project uses Gatsby and not Next.js +# https://nextjs.org/blog/next-9-1#public-directory-support +# public + +# vuepress build output +.vuepress/dist + +# vuepress v2.x temp and cache directory +.temp +.cache + +# vitepress build output +**/.vitepress/dist + +# vitepress cache directory +**/.vitepress/cache + +# Docusaurus cache and generated files +.docusaurus + +# Serverless directories +.serverless/ + +# FuseBox cache +.fusebox/ + +# DynamoDB Local files +.dynamodb/ + +# TernJS port file +.tern-port + +# Stores VSCode versions used for testing VSCode extensions +.vscode-test + +# yarn v2 +.yarn/cache +.yarn/unplugged +.yarn/build-state.yml +.yarn/install-state.gz +.pnp.* + + +# Echo Nexus 本地文件 local-* .claude .z-ai-config -*.log dev.log dev.out.log -test -prompt - -server.log -# Skills directory -/skills/ \ No newline at end of file +*.tsbuildinfo +next-env.d.ts +.vercel diff --git a/README.md b/README.md new file mode 100644 index 000000000..5ff51c8e5 --- /dev/null +++ b/README.md @@ -0,0 +1,35 @@ +# 回响星核 / Echo Nexus + +> 原创深空考古放置策略游戏 · Original deep-space archaeology idle strategy game + +你是一名深空考古指挥官，驾驶自治勘探舰回收已「飞升」的以太文明遗留的记忆晶体，解码碎片拼凑出他们的故事，并最终跨越维度发起「接触」。 + +## 项目状态 + +- **版本**：v0.1（MVP 开发中） +- **栈**：Next.js 16 · TypeScript · Tailwind · shadcn/ui · Canvas · Zustand · Prisma +- **仓库**：https://git.atdunbg.xyz/Super_Z/echo-nexus + +## 文档 + +- [`docs/01-调研报告.md`](docs/01-调研报告.md) — 游戏市场调研 +- [`docs/02-游戏设计文档.md`](docs/02-游戏设计文档.md) — GDD 策划设计 +- [`docs/03-技术架构.md`](docs/03-技术架构.md) — 技术架构 + +## 核心特色 + +- **解码共振谜题**：把放置游戏的「等待」变成有节奏的主动小谜题 +- **碎片涌现叙事**：故事从解码中自然浮现，不打断玩法 +- **深空全息美学**：晶体 + 粒子 + 共振波纹的差异化视觉 +- **飞升多周目**：终局「接触」后保留蓝图开启新周目 + +## 开发路线 + +- v0.1 放置 + 解码 + 技术树 + 图谱 + 飞升（当前） +- v0.2 遗迹探险肉鸽 +- v0.3 音频 + 全局星潮 socket 事件 +- v0.4 云存档 + 排行榜 +- v0.5 全 5 纪元叙事 + 隐藏内容 + +--- +© Super_Z · 持续开发中 diff --git a/docs/01-调研报告.md b/docs/01-调研报告.md new file mode 100644 index 000000000..a17096b82 --- /dev/null +++ b/docs/01-调研报告.md @@ -0,0 +1,95 @@ +# 游戏市场调研报告 + +> 调研日期：2025 年（持续更新） +> 调研者：Super_Z +> 目的：为原创游戏《回响星核 / Echo Nexus》的设计提供数据支撑，避免落入「1:1 复刻」陷阱。 + +--- + +## 一、市场大盘（数据时效性已核实，多源交叉验证） + +### 1.1 浏览器 / HTML5 游戏市场 +- **市场规模**：2025 年浏览器游戏市场约 **78 亿 ~ 118 亿美元**（不同机构口径略有差异），预计 2033-2034 年达到 **92 亿 ~ 163 亿美元**，CAGR 约 3.5%。 + - 来源：Research and Markets（78.1 亿→80.1 亿）、Dataintelo（118 亿→163 亿）、Business Research Insights。 +- **HTML5 游戏细分**：2024 年约 53.2 亿美元，2033 年预计 92.2 亿美元，CAGR 约 7.7%（LinkedIn / Metastat）。 +- **供给爆发**：2025 年有 **15,000+** 款 HTML5 新作上线，同比增长 **2.7 倍**（Business Research Insights）。 +- **技术趋势**：WebAssembly 让浏览器游戏性能逼近原生；WebGL/WebGPU 渲染能力持续提升。 + +**结论**：浏览器游戏是增长赛道，**可及性高、潜在受众巨大（尤其国际市场）**，但供给端竞争激烈，**必须靠差异化创新突围**。 + +### 1.2 独立游戏品类格局（Steam 视角） +- **2025 年叙事游戏**成为 Steam 达到 1000 评价数量最多的品类（#1），超越传统品类（HowToMarketAGame 年度报告）。 +- **新一代独立原生品类**：开放世界生存、卡牌构筑（deckbuilder）、Roguelike 持续走强（SuperJump）。 +- **红海/饱和品类**（Reddit 独开者共识，建议避开正面对撞）：Roguelike Deckbuilder、视觉小说、本地合作、4X。 +- **2025 独立代表作**：Hades II、Deltarune、Ways of Alchemy、Cluckmech Oasis 等。 + +**结论**：纯复刻热门品类（如又一款肉鸽卡牌）会被淹没；**叙事 + 创新机制组合**是突破口。 + +### 1.3 放置 / 增量（Idle / Incremental）品类 +- **极强留存**：Idle 类天然契合浏览器场景，代表作 Cookie Clicker、Universal Paperclips、Melvor Idle 长盛不衰。 +- **2025 热度持续**：GameSpot、Bits N' Pixels 年度榜单均大量收录 idle/clicker 游戏。 +- **典型玩法**：资源自动累积 + 主动操作 + 解锁/重置（prestige）循环。 +- **优势**：开发成本可控、留存曲线平缓、适合持续迭代。 + +### 1.4 玩家留存关键洞察 +- **核心循环（core loop）**是留存的根基；D1/D7/D30 是关键基准。 +- **渐进式功能发现**：让玩家逐步解锁新机制，避免一次性信息过载。 +- **社交连接 + 流畅运营**：长期留存的两大支柱。 +- **动机分层**：成就型、探索型、社交型玩家需要差异化设计。 + +--- + +## 二、竞品分析与差异化机会 + +| 维度 | 主流放置游戏 | 主流叙事游戏 | 主流肉鸽 | 《回响星核》定位 | +|---|---|---|---|---| +| 核心 | 数值增长 | 剧情推进 | 战斗随机 | **解码谜题 + 放置 + 探险** | +| 叙事 | 弱/无 | 强但线性 | 弱 | **碎片化叙事，由玩法涌现** | +| 美术 | 简笔画/像素 | 插画 | 像素 | **全息晶体 + 深空粒子美学** | +| 留存钩子 | prestige | 章节 | 随机性 | **「接触」终局 + 多周目** | +| 单局 | 长 | 中 | 短 | **可长可短（放置 + 主动）** | + +**差异化结论**： +1. 没有任何一款主流游戏同时是「深空考古 + 记忆解码谜题 + 放置 + 肉鸽探险 + 碎片叙事」。 +2. 叙事由解码行为**涌现**而非过场灌输，符合 2025 叙事品类崛起趋势。 +3. 放置核心保证留存，解码谜题提供主动乐趣，探险提供随机性重玩价值。 + +--- + +## 三、技术选型调研结论 + +- **框架**：Next.js 16（App Router）+ TypeScript —— 本项目既有栈，SSR/路由/API 一体化，适合 web 游戏。 +- **渲染**：2D 场景用 **HTML5 Canvas**（星空/粒子/晶体动画），UI 用 **React + shadcn/ui**。3D 暂不需要，控制复杂度。 +- **状态**：Zustand（客户端）+ localStorage 持久化；后续可接 API 同步存档。 +- **后端**：Next.js API Routes + Prisma(SQLite)，承载存档同步、全局统计、（后续）排行榜。 +- **实时**：socket.io 小服务，用于全局「星潮」事件（后续阶段）。 + +**结论**：在既有 Next.js 栈内即可实现，无需引入重框架，性能与可维护性平衡良好。 + +--- + +## 四、设计原则（源自调研） + +1. **原创优先**：不做任何现有游戏的 1:1 复刻，机制组合与世界观均自创。 +2. **核心循环扎实**：放置产出 → 解码消耗 → 解锁成长 → 探险扩张 → 终局「接触」。 +3. **叙事涌现**：故事从解码碎片中拼出，不打断玩法。 +4. **渐进披露**：功能随进度解锁，符合留存最佳实践。 +5. **视觉差异化**：全息晶体 + 深空粒子，第一眼即与同类区分。 +6. **可持续迭代**：模块化架构，便于后续通过工单需求持续扩展。 + +--- + +## 五、数据来源清单（真实性/时效性核验） + +1. Business Research Insights — Browser Games Market Report +2. Research and Markets — Browser Games Market 2026 +3. Dataintelo — Browser Game Market Research 2034 +4. Metastat Insights — HTML5 Games Market 2030 +5. LinkedIn (行业分析) — Casual HTML5 Games 2024-2033 +6. HowToMarketAGame — 2025 Steam 品类年度报告 +7. SuperJump — State of Indie Games 2025 +8. GameSpot / Bits N' Pixels — 2025 Idle 游戏榜单 +9. GameDesignSkills / GameDeveloper — 留存策略 17 条 +10. Reddit r/incremental_games、r/gamedev 社区共识 + +所有数据均为 2024-2026 年发布，时效性满足设计决策需要。 diff --git a/docs/02-游戏设计文档.md b/docs/02-游戏设计文档.md new file mode 100644 index 000000000..a6ed61ad4 --- /dev/null +++ b/docs/02-游戏设计文档.md @@ -0,0 +1,141 @@ +# 《回响星核 / Echo Nexus》游戏设计文档 (GDD) + +> 版本：v0.1（首发概念版） +> 作者：Super_Z +> 状态：设计已定稿，进入实现阶段 + +--- + +## 一、一句话概念 + +**你是一名深空考古指挥官，驾驶自治勘探舰回收已「飞升」的以太文明遗留的记忆晶体，解码碎片拼凑出他们的故事，并最终跨越维度发起「接触」。** + +## 二、游戏定位 + +- **品类**：深空考古放置策略 + 记忆解码谜题 + 肉鸽探险 + 涌现叙事 +- **平台**：现代浏览器（桌面优先，移动适配） +- **单局时长**：可长可短（放置 30 秒也有产出；主动游玩 10-30 分钟一轮探险） +- **目标留存**：D1 > 40%，D7 > 15%（idle 品类基准之上） +- **差异化**：业界首个「解码谜题驱动叙事涌现」的放置游戏 + +## 三、世界观 + +数万年前，银河系存在一个高度发达的文明——**以太族（Aetherians）**。他们没有灭亡，而是集体「飞升」到了更高维度。临走前，他们将文明的知识与记忆封存在遍布星系的**记忆晶体（Memory Crystals）**中，作为留给后来者的「面包屑」——只待某个文明能解读足够多的晶体，便有资格发起「接触」。 + +玩家扮演人类深空考古局的指挥官，舰载 AI「回响（Echo）」辅助你勘探遗迹、回收晶体、解码记忆。 + +## 四、核心循环 + +``` + ┌─────────────────────────────────────────────┐ + ▼ │ + [自治无人机采矿] ──产出──> [记忆晶体库存] │ + │ │ + [解码谜题] <── 主动操作 │ + │ │ + ┌──────────────┼──────────────┐ │ + ▼ ▼ ▼ │ + [记忆碎片] [技术洞见] [剧情片段] │ + (叙事资源) (解锁升级) (拼凑故事) │ + │ │ │ │ + └──────────────┴──────────────┘ │ + │ │ + [发起遗迹探险] ─肉鸽─> 新晶体类型 + │ │ + [「接触」进度条 ↑] │ + │ │ + ────── 达成 100% ───── 终局 / 新周目 +``` + +**核心循环一句话**：采矿→解码→成长→探险→填满接触条→新周目。 + +## 五、核心系统 + +### 5.1 记忆晶体采集（Idle 核心） +- 自治无人机以 **晶体/秒** 速率自动产出记忆晶体。 +- 玩家可主动「脉冲扫描」（点击/按键）获得瞬时增量 + 连击加成。 +- 离线时按 50% 效率持续产出（最多累积 8 小时）。 + +### 5.2 解码系统（主动玩法核心 ⭐） +每颗晶体需经「解码」才能释放其中内容。解码是一个**原创的图案共振谜题**： +- 屏幕呈现一个由发光节点构成的**共振阵列**（类似星图）。 +- 玩家需在限定步数内，按特定**共振顺序**点亮节点，使能量流闭合形成回路。 +- 成功 → 释放记忆碎片 + 技术洞见 + 剧情片段。 +- 不同晶体等级 / 类型 → 阵列规模与共振规则不同（渐进难度）。 +- **设计意图**：把「解码」从被动等待变成有节奏的主动小谜题，避免放置游戏「只挂机不动手」的枯燥。 + +### 5.3 技术树（成长系统） +四个分支，由「技术洞见」解锁： +- **采矿**：提升晶体/秒、仓库上限、离线效率。 +- **解码**：降低解码步数消耗、解锁阵列提示、自动解码低级晶体。 +- **探险**：提升探险成功率、降低风险、增加稀有晶体掉落。 +- **叙事**：解锁更深记忆层、揭示隐藏剧情、提升「接触」进度转化率。 + +### 5.4 遗迹探险（Roguelike 层） +- 消耗「能量」向随机生成的遗迹节点图派出探险队。 +- 每个节点有事件（战斗/解谜/宝藏/抉择），路径分支。 +- 失败损失探险队，成功带回稀有晶体 + 大量洞见 + 独有剧情。 +- 单次探险 10-30 分钟，提供短期目标与随机性重玩价值。 + +### 5.5 碎片叙事（叙事层） +- 解码与探险产出的「记忆碎片」自动归档到**记忆图谱（Memory Codex）**。 +- 图谱以星图形式呈现，碎片拼合后揭示以太族编年史（5 个纪元）。 +- 关键碎片触发**「回响回放」**——一段沉浸式全息短叙（文字 + 视觉），但**绝不打断玩法**（可随时关闭）。 + +### 5.6 「接触」终局与多周目 +- 全部行为累积「接触进度」。 +- 达 100% → 触发终局「接触」事件（戏剧性叙事高潮）。 +- 之后可选择**飞升（Prestige）**进入新周目：保留叙事图谱与技术蓝图的一部分，重置数值，开启更高难度与隐藏内容。 + +## 六、美术与音频方向 + +- **视觉**：深空黑紫底色 + 全息青/品虹光晶体 + 流动星尘粒子。整体「冷峻神秘 + 科技仪式感」。 +- **字体**：标题用未来感无衬线，正文清晰可读。 +- **动效**：晶体生长、解码共振波纹、粒子涌动、飞升白光。 +- **音频**：环境氛围 pad + 解码成功清脆音 + 关键叙事轻旋律（后续阶段）。 + +## 七、UI 信息架构 + +``` +顶栏：晶体库存 | 接触进度 | 能量 | 设置 +左侧：主视图（Canvas 星空 + 晶体集群 + 解码阵列） +右侧：标签面板 + - 采矿 (Mining) + - 解码 (Decode) ⭐默认 + - 技术 (Tech) + - 探险 (Expedition) + - 记忆图谱 (Codex) +底栏：当前目标提示 | 在线/离线收益 | 版本号 +``` + +## 八、首版（v0.1）MVP 范围 + +为快速验证核心乐趣，首版聚焦： +- [x] 放置采矿（晶体/秒 + 主动脉冲） +- [x] 解码共振谜题（3 种阵列规模） +- [x] 技术树 4 分支 × 3 级 = 12 个升级 +- [x] 记忆图谱（首纪元 8 个碎片） +- [x] 接触进度 + 飞升（Prestige） +- [x] localStorage 存档 + 离线收益 +- [x] 精美 Canvas 星空背景 + 晶体动画 +- [x] 响应式布局（桌面/移动） + +**v0.1 暂不做**：遗迹探险肉鸽、socket 全局事件、音频、多语言切换、账号云存档（留待后续版本/工单驱动）。 + +## 九、后续路线图 + +- **v0.2**：遗迹探险肉鸽系统 +- **v0.3**：音频系统 + 全局「星潮」socket 事件 +- **v0.4**：账号云存档 + 排行榜 +- **v0.5**：多周目隐藏内容 + 全 5 纪元叙事 +- **持续**：根据工单需求迭代 + +## 十、设计风险与对策 + +| 风险 | 对策 | +|---|---| +| 解码谜题单调 | 多种阵列规则 + 自动解码低级晶体 | +| 放置枯燥 | 主动脉冲 + 连击 + 探险提供短期目标 | +| 叙事打断玩法 | 所有叙事可跳过，图谱自愿浏览 | +| 数值膨胀 | 飞升重置 + 指数曲线校准 | +| 移动端操作 | 解码阵列适配触控，UI 自适应 | diff --git a/docs/03-技术架构.md b/docs/03-技术架构.md new file mode 100644 index 000000000..139366264 --- /dev/null +++ b/docs/03-技术架构.md @@ -0,0 +1,109 @@ +# 技术架构设计 + +## 一、技术栈 + +| 层 | 技术 | 说明 | +|---|---|---| +| 框架 | Next.js 16 (App Router) | 既有栈，SSR + API 一体 | +| 语言 | TypeScript 5 | 全量类型 | +| 样式 | Tailwind CSS 4 + shadcn/ui | 既有 UI 组件库 | +| 渲染 | HTML5 Canvas 2D | 星空/粒子/晶体/解码阵列 | +| 客户端状态 | Zustand + persist | 游戏状态 + localStorage 持久化 | +| 服务端状态 | TanStack Query（按需） | 存档同步、统计 | +| 后端 | Next.js API Routes | 存档同步、全局统计 | +| 数据库 | Prisma + SQLite | 存档、统计（v0.4+） | +| 实时 | socket.io mini-service | 全局「星潮」事件（v0.3+） | + +## 二、目录结构 + +``` +src/ + app/ + page.tsx # 游戏主入口（唯一用户可见路由） + layout.tsx + api/ + save/route.ts # 存档同步（v0.4+） + stats/route.ts # 全局统计 + components/ + game/ # 游戏专属组件 + StarfieldCanvas.tsx # 星空背景 + CrystalCluster.tsx # 晶体集群 + DecodeArray.tsx # 解码共振阵列 ⭐ + ResourceBar.tsx # 顶栏资源 + MiningPanel.tsx + TechTree.tsx + Codex.tsx # 记忆图谱 + PrestigeDialog.tsx + ui/ # shadcn/ui 既有 + lib/ + game/ # 游戏逻辑（纯函数，可测） + config.ts # 数值配置 + types.ts # 类型 + engine.ts # 核心 tick 引擎 + decode.ts # 解码谜题逻辑 + tech.ts # 技术树 + codex.ts # 叙事数据 + prestige.ts # 飞升 + db.ts # Prisma + store/ + gameStore.ts # Zustand 游戏状态 + hooks/ + useGameLoop.ts # 主循环 + use-toast.ts # 既有 +``` + +## 三、状态模型（Zustand） + +```ts +interface GameState { + // 资源 + crystals: number; // 记忆晶体（主货币） + insights: number; // 技术洞见 + fragments: Record; // 已获碎片 + contact: number; // 接触进度 0-100 + + // 产能 + crystalsPerSec: number; // 由技术树计算 + pulsePower: number; // 主动脉冲产出 + + // 技术 + tech: Record; // 各技术等级 + + // 飞升 + ascensions: number; + blueprints: string[]; // 保留的蓝图 + + // 解码 + currentCrystal: Crystal | null; + + // 元 + lastTick: number; + prestige: PrestigeBonus; +} +``` + +## 四、核心循环引擎 + +- 客户端 `setInterval` 每 100ms tick 一次。 +- 每次 tick：`crystals += crystalsPerSec * dt`。 +- 离线收益：加载时计算 `now - lastTick`，按 50% 效率补发（上限 8h）。 +- 状态自动持久化到 localStorage（Zustand persist，节流 1s）。 + +## 五、解码谜题实现 + +- 阵列 = 节点图（邻接表），每节点有 `resonance` 值。 +- 共振规则：玩家依序点击节点，相邻点击须满足 `resonance` 差值 ≤ 阈值，且最终形成闭合回路。 +- 步数限制：规模 3×3=9 节点 / 4×4=16 / 5×5=25，步数上限分别为 6/10/15。 +- 成功 → 结算奖励 + 动画；失败 → 晶体不损耗，可重试。 + +## 六、Canvas 渲染策略 + +- 单一全屏 Canvas 作为背景层（星空 + 星尘 + 远景星云）。 +- 晶体集群与解码阵列用**独立 Canvas 或 SVG**叠加，便于交互。 +- requestAnimationFrame 驱动，设备像素比适配，低性能设备降帧。 + +## 七、可扩展性 + +- 数值配置集中在 `config.ts`，便于平衡调整与工单需求响应。 +- 叙事数据集中在 `codex.ts`，新增碎片只需追加数据。 +- 技术树/解码规则/探险地图均数据驱动，支持后续模块化扩展。 diff --git a/docs/04-解码系统修复-v0.1.1.md b/docs/04-解码系统修复-v0.1.1.md new file mode 100644 index 000000000..938e59beb --- /dev/null +++ b/docs/04-解码系统修复-v0.1.1.md @@ -0,0 +1,57 @@ +# 解码系统修复说明 (v0.1.1) + +## 问题 +用户反馈「解码大量的无法通过」。经分析，根因是 `generatePuzzle` **没有保证生成的局面有解**：随机填色后可能根本不存在一条满足「按目标顺序、四邻接、不重复」的路径，导致大量死局。 + +## 修复方案 + +### 1. 路径构造法生成器（核心修复） +重写 `generatePuzzle`，采用**路径构造法**： +1. 先随机生成目标序列 target。 +2. 在网格上**主动构造一条合法路径**：随机起点，每步走向一个未使用的四邻接节点，长度 = target.length。 +3. 把路径上第 i 个节点颜色**强制设为 target[i]**。 +4. 其余非路径节点随机填色（60% 偏向目标色，提升多解性）。 + +这样**至少存在一条解**（即构造的路径），玩家不会遇到「怎么都过不了」的死局。 + +### 2. 精确可解性检测 `isSolvable` +新增 DFS 函数，从当前路径末端出发，精确判断是否存在一条按 target 剩余顺序、四邻接、不重复的完成路径。用于： +- 玩家点击后检测「此路不通」，提示撤销。 +- `isStuck` 复用此判定。 + +### 3. 撤销功能 `undoStep` +新增 store action，支持单步回退（恢复节点 used 状态）。走错时无需整个重排。 + +### 4. 卡死提示横幅 +当局面不可解时，顶部显示「谐振受阻，此路已无解」横幅 + 快捷撤销按钮。 + +### 5. 可行起点高亮（体验增强） +选起点阶段，用 `canStartFrom` 检测每个目标色节点「选了之后是否仍可解」： +- **可行起点**：强光圈 + 2px 边框 + 快脉冲，引导玩家。 +- **死起点**：淡化(opacity 0.5)，避免玩家踩坑。 + +### 6. 旧存档兼容 +`init` 时检测存档中的活跃谜题，若不可解（旧算法生成）则自动放回晶体队列，避免老玩家卡死。 + +## 验证结果 + +### 算法验证（1000 次/档位） +- Tier 1: 1000/1000 可解 (100.0%) +- Tier 2: 1000/1000 可解 (100.0%) +- Tier 3: 1000/1000 可解 (100.0%) +- 总计: 3000/3000 (100.00%) + +### 模拟游玩（带可解性筛选的贪心玩家） +- 500 局: 100% 解出，平均撤销 0 次 + +### agent-browser 端到端验证 +- T1 (3×3): 通过 ✓ +- T2 (4×4): 通过 ✓ +- 死路检测: 触发「谐振受阻」横幅 ✓ +- 撤销: 单步回退正常 ✓ +- 可行起点高亮: 准确标记（4 个玫色节点中仅 1 个为可行起点，与手算一致）✓ + +## 影响文件 +- `src/lib/game/decode.ts` — 重写生成器 + 新增 isSolvable/canStartFrom +- `src/store/gameStore.ts` — clickNode 可解性检测 + undoStep + init 兼容 +- `src/components/game/DecodeArray.tsx` — 撤销按钮 + 卡死横幅 + 可行起点高亮 diff --git a/docs/05-遗迹探险系统-v0.2.md b/docs/05-遗迹探险系统-v0.2.md new file mode 100644 index 000000000..755b65e59 --- /dev/null +++ b/docs/05-遗迹探险系统-v0.2.md @@ -0,0 +1,107 @@ +# v0.2 遗迹探险肉鸽系统 + +> 版本：v0.2.0 +> 日期：2025-06-23 +> 作者：Super_Z + +## 概述 + +实现路线图中的 v0.2 旗舰功能——**遗迹探险肉鸽系统**。玩家消耗能量派出探险队，进入程序化生成的遗迹节点路径，沿途遭遇战斗、宝藏、抉择、解谜与休整事件，击败终点 BOSS 获取丰厚奖励。 + +## 新增系统 + +### 1. 能量系统 +- 新增「探险能量」资源，初始 3 点，上限 5 点。 +- 每 45 秒自动恢复 1 点能量（tick 驱动，离线也恢复）。 +- 每次探险消耗 1 点能量。 + +### 2. 探险力与生命 +- **探险力**：由基础值 10 + 探险分支技术加成 + 飞升蓝图加成 + 飞升周目加成计算。 +- **探险生命**：基础 100 + 技术/飞升加成。归零则探险失败结束。 +- **战斗胜率**：`clamp(power / (power + difficulty × 8), 0.25, 0.95)`。 + +### 3. 节点路径 +- 每次探险生成 5-7 个节点的线性路径。 +- 末位固定为 BOSS 节点。 +- 首节点强制为友好类型（宝藏/休整），保证开局体验。 +- 6 种节点类型： + +| 类型 | 图标 | 颜色 | 机制 | +|---|---|---|---| +| 战斗 combat | 剑 | 玫红 | 按胜率决定胜负，胜获奖、败扣血或全灭 | +| 宝藏 treasure | 宝石 | 琥珀 | 直接获得晶体+洞见 | +| 抉择 choice | 问号 | 青 | 55% 好结果（奖励）/45% 坏结果（扣血） | +| 解谜 puzzle | 拼图 | 紫 | 探险力越高越可能解出，成功获大奖 | +| 休整 rest | 心 | 翠 | 恢复生命 | +| BOSS boss | 骷髅 | 红 | 必定战斗，高难度，胜则大量奖励+探险胜利 | + +### 4. 奖励机制 +- **实时入账**：每个节点结算后奖励立即加入玩家资源。 +- **晶体绕过仓库上限**：探险奖励晶体不受 idle 产能仓库上限限制（仅闲置产能受限）。 +- **失败保留**：探险失败（HP 归零）仍保留已获得的全部奖励。 +- **BOSS 胜利**：额外给予大量晶体、洞见、接触进度。 +- **撤退**：玩家可随时主动撤退，保留已获奖励。 + +### 5. 探险日志 +- 记录最近 30 条探险事件，含节点类型、结果描述、奖励明细。 +- 飞升后保留日志。 + +## UI 设计 + +### 探险标签页（主页面第 4 个标签） +- **入口态**（无活跃探险）： + - 能量条（含恢复倒计时） + - 出发按钮（消耗 1 能量） + - 探险说明文案 + - 最近探险记录（最近 4 条） +- **进行态**（有活跃探险）： + - 探险力 + 当前节点位置 + - 生命条（HP/maxHP，<30% 变红） + - 节点路径图（横向，已通过/当前/未知，含类型图标与颜色） + - 路径进度条 + - 当前节点事件卡（类型标签、难度、胜率、标题、描述、结算结果） + - 操作按钮（探索节点 / 前进 / 撤退） + - 本次累计奖励 + +### 视觉细节 +- 每种节点类型有专属颜色与图标 +- 当前节点放大 1.25 倍 + 光晕 +- 已通过节点显示绿色对勾 +- 事件卡使用对应节点类型的渐变背景与边框光晕 +- 能量条渐变（琥珀→黄） +- 生命条渐变（玫红→翠绿） + +## 配套修复与增强 + +### 仓库满仓警告 +- 晶体达上限 98% 时，底部状态栏变琥珀色 + 脉冲动画 + 警告文案。 +- 引导玩家解码或升级仓库。 + +### 闲置产能上限优化 +- 仓库满时不再自动产出晶体（而非产出后截断）。 +- 探险奖励晶体可超出上限，不被浪费。 + +### 技术树探险分支增强 +- 远征推进器：探险力 +3 +- 遗迹图谱：探险力 +5，探险生命 +20 +- 维度信标：探险力 +8，接触进度 +50% + +## 验证结果 + +- ✅ 探险出发/节点结算/前进/BOSS/撤退全流程通过 +- ✅ HP clamp 修复（休整不超上限） +- ✅ 探险奖励绕过仓库上限（101 晶体 > 50 cap） +- ✅ 探险失败保留奖励 +- ✅ 能量恢复计时 +- ✅ 探险日志记录 +- ✅ 探险标签红点提示（有能量/有进行中探险） + +## 影响文件 + +- `src/lib/game/types.ts` — 新增探险类型定义 +- `src/lib/game/expedition.ts` — **新建**，探险逻辑（生成/结算/能量恢复） +- `src/lib/game/config.ts` — 初始状态增加探险字段，技术树描述更新 +- `src/lib/game/engine.ts` — createInitialState/performPrestige 包含探险字段 +- `src/store/gameStore.ts` — 探险 actions + 能量恢复 tick + HP clamp + 产能上限优化 +- `src/components/game/ExpeditionPanel.tsx` — **新建**，探险 UI +- `src/app/page.tsx` — 新增探险标签页 + 仓库满仓警告 + 能量红点 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 工单 diff --git a/docs/07-星潮事件系统-v0.3.md b/docs/07-星潮事件系统-v0.3.md new file mode 100644 index 000000000..60b863636 --- /dev/null +++ b/docs/07-星潮事件系统-v0.3.md @@ -0,0 +1,113 @@ +# 回响星核 v0.3 — 星潮事件系统（周期性全局玩法修饰） + +> 版本：v0.3 +> 日期：2026-06-23 +> 范围：6 种星潮事件、周期触发、全屏视觉叠层、程序化音效、寂静期补偿机制 + +--- + +## 一、设计动机 + +回应 Gitea Issue #1「就一直连连看？」的玩法单一反馈。星潮事件为放置循环注入**动态变化**：深空中偶发的「星潮」会短暂改变物理法则，让玩家在 75 秒内体验产能翻倍、解码加成、探险增强等不同玩法侧重，打破单调感。 + +## 二、6 种星潮事件 + +| 类型 | 名称 | 效果 | 色调 | 性质 | +|------|------|------|------|------| +| crystal | 晶体潮 | 采矿产能 ×2 | 翠绿 | 正面 | +| resonance | 谐振风暴 | 解码奖励 ×1.6 | 玫红 | 正面 | +| ruins | 遗迹共振 | 探险力 +5、生命 +30 | 琥珀 | 正面 | +| void | 虚空低语 | 洞见获取 ×2 | 紫红 | 正面 | +| core | 星核悸动 | 接触率 ×3、脉冲威力 ×2 | 青色 | 正面 | +| silence | 寂静期 | 产能 ×0.5；结束时按时长补偿洞见 | 灰蓝 | 负面（有补偿） | + +## 三、触发机制 + +- **首次星潮**：游戏开始 30 秒后触发（`TIDE_CONFIG.firstDelay`） +- **常规间隙**：星潮结束后 40 秒触发下一次（`TIDE_CONFIG.gap`） +- **持续时间**：75 秒（`TIDE_CONFIG.duration`） +- **权重抽取**：6 种事件按权重随机（正面事件权重高，寂静期权重最低 10%） +- **飞升重置**：飞升后清空当前星潮，重置计时，30 秒后重新开始 + +## 四、修饰器应用层 + +| 修饰器 | 应用点 | +|--------|--------| +| crystalsPerSecMult | `tick()` 即时乘（显示基础值，实际翻倍积累） | +| pulsePowerMult | `pulse()` 即时乘 | +| decodeRewardMult | `clickNode()` / `autoDecodeTick()` 结算时乘 | +| insightMultAdd | 进 `recomputeStats` 缓存（星潮起止时重算） | +| contactRateMult | 进 `recomputeStats` 缓存 | +| expeditionPowerBonus / hpBonus | `startExpedition()` 即时加 | +| silenceInsightPerSec | 星潮结束时 `computeSilenceCompensation` 结算 | + +## 五、UI 表现 + +### 顶部指示器（`StarTideIndicator`） +- 活跃时在 header 右侧显示彩色芯片：图标 + 名称 + 倒计时秒数 +- 芯片背景为对应色半透明，带光晕，进度条随时间推进 + +### 全屏背景叠层（`StarTideOverlay`） +- 顶部 + 底部对应色渐变色带 +- 边缘 `inset box-shadow` 呼吸光效（3 秒周期） +- 活跃时整页笼罩对应色调氛围 + +### 通知（`StarTideNotifier`） +- 星潮降临时 Toast + `tideStart` 音效（神秘扫频） +- 星潮结束时 Toast + `tideEnd` 音效（柔和消退） +- 寂静期结束时显示「虚空回赠 N 洞见」+ `techBuy` 音效 + +### Footer 联动 +- 活跃时 footer 提示文字变为「✺ 星潮「晶体潮」进行中 · 深空晶体涌动…」 +- footer 边框点亮对应色光晕 + +## 六、程序化音效 + +新增 2 种音效（`audio.ts`）： +- `tideStart`：330→660Hz 正弦扫频 + 440→880Hz 三角波 + 523/784Hz 长音（神秘降临感） +- `tideEnd`：659→523→392Hz 下行三音（柔和消退） + +## 七、状态与兼容 + +- `GameState` 新增 `activeTide: StarTide | null`、`lastTideEnd: number` +- 旧存档兼容：`init()` 补全字段为 `null/0` +- `partialize` 排除运行时队列 `_tideEvents` +- `performPrestige` 重置星潮（清空 activeTide，lastTideEnd 设为 now） + +## 八、QA 验证 + +### agent-browser 自动化 +- ✅ 强制触发星潮：`lastTideEnd=0` → 重载 → 30s 内自动触发，状态显示 `activeTide: crystal` +- ✅ 顶部指示器渲染：「✺ 晶体潮 64s」绿色芯片 +- ✅ 背景叠层：VLM 确认绿色调背景光晕 + 顶部/底部色带 + 边缘呼吸光 +- ✅ 寂静期补偿：设置 `type=silence, endsAt=now+3s` → 等待结束 → insights 从 50 增至 81（补偿 30） +- ✅ Footer 联动：活跃时显示「✺ 星潮「晶体潮」进行中 · 深空晶体涌动…」 +- ✅ 版本号 v0.3 显示 +- ✅ lint 零错误，HTTP 200，无运行时错误 + +### VLM 视觉确认 +- 指示器芯片：绿色文字「晶体潮 11s」 +- 背景光晕：深绿色，顶部/底部色带 + 边缘呼吸光 +- 视觉完成度：界面清晰、风格统一、细节良好 + +## 九、文件变更清单 + +**新增**： +- `src/lib/game/starTide.ts` — 星潮定义、修饰器、触发逻辑 +- `src/components/game/StarTide.tsx` — 指示器 + 叠层 + 通知三组件 + +**修改**： +- `src/lib/game/types.ts` — GameState 新增 `activeTide` / `lastTideEnd` +- `src/lib/game/config.ts` — INITIAL_STATE 新增潮汐字段 +- `src/lib/game/engine.ts` — `recomputeStats` 应用 insightMultAdd/contactRateMult；`performPrestige`/`createInitialState` 处理潮汐 +- `src/lib/game/audio.ts` — 新增 `tideStart` / `tideEnd` 音效 +- `src/store/gameStore.ts` — `tickTide` / `consumeTideEvents`；tick/pulse/clickNode/autoDecodeTick/startExpedition 应用修饰器；init/hardReset/partialize 兼容 +- `src/hooks/useGameLoop.ts` — 主循环调用 `tickTide`，可见性恢复补检测 +- `src/app/page.tsx` — 接入 StarTideOverlay/Indicator/Notifier；Footer 联动；版本号 v0.3 + +## 十、下一步规划 + +- v0.3 已完成客户端星潮（原计划 socket 全局事件，现以单机版先行，后续可扩展为多人同步） +- v0.4：云存档 + 排行榜 +- v0.5：全 5 纪元叙事扩展 +- 持续关注 Gitea 工单 diff --git a/docs/08-星图天文台系统-v0.3.1.md b/docs/08-星图天文台系统-v0.3.1.md new file mode 100644 index 000000000..5e4501aaa --- /dev/null +++ b/docs/08-星图天文台系统-v0.3.1.md @@ -0,0 +1,171 @@ +# v0.3.1 · 星图天文台（Constellation Observatory）元进程天赋系统 + +> 第二次回应 Issue #1「就一直连连看？」——为飞升循环加入 Slay the Spire 式 3 选 1 天赋 draft， +> 跨周目永久生效，配合 Canvas 动态星图可视化，提供长期成长目标与策略选择。 + +## 一、设计动机 + +v0.3 星潮事件已为放置循环注入动态变化，但玩家仍缺长期 meta-progression 目标。本系统在飞升后触发： + +- **策略选择**：3 选 1 的 draft 让每次飞升都有差异化构建方向 +- **永久成长**：天赋跨周目保留，配合蓝图/成就形成三层加成 +- **视觉反馈**：Canvas 动态星图，每解锁一个天赋就在对应星座点亮一颗星 +- **目标驱动**：18 个天赋 + 2 个专属成就，给玩家清晰的中长期目标 + +## 二、系统架构 + +### 2.1 数据层（`src/lib/game/constellation.ts`） + +```typescript +// 6 大星座 × 3 颗星 = 18 个天赋 +type ConstellationCategory = + | "mining" | "decoding" | "expedition" + | "contact" | "economy" | "cosmic"; + +interface ConstellationPerk { + id: string; // c_min_1, c_dec_2, ... + category: ConstellationCategory; + name: string; + desc: string; + order: 1 | 2 | 3; // 星座内位置 +} +``` + +### 2.2 18 个天赋一览 + +| 类别 | #1 | #2 | #3 | +|------|-----|-----|-----| +| 翠·永动矿脉 | 永动钻头（产能+20%） | 深井网络（上限+50%） | 谐振熔炉（脉冲+50%） | +| 玫·光谱矩阵 | 光谱记忆（洞见+15%） | 步幅延展（步数+1） | 自动校准（自解-3s） | +| 琥·远征星图 | 维生护盾（生命+25%） | 信标矩阵（探险力+20%） | 能量共振（能量上限+1） | +| 紫·接触回响 | 接触共鸣（接触率+20%） | 飞升加速（门槛-10） | 蓝图回响（每蓝图+2%全属性） | +| 灰·虚空市场 | 离线缓存（离线+15%） | 晶体富集（T2/T3+8%） | 星潮引导（间隙-10s） | +| 金·宇宙回响 | 飞升礼包（+30晶体/+5洞见） | 二周目经验（解码+10%） | 全息共振（全产能+8%） | + +### 2.3 修饰器聚合 + +`constellationBonuses(perks: string[]): ConstellationModifiers` 返回 **19 项修饰器**， +在 `recomputeStats()` / `tickTide()` / `tick()` / `clickNode()` / `autoDecodeTick()` / `computeExpeditionPower()` / `computeExpeditionHp()` 等所有相关用点处应用。 + +### 2.4 状态扩展 + +```typescript +// types.ts +interface GameState { + // ... 既有字段 + constellation: string[]; // 已解锁天赋 ID + pendingPerkChoices: string[] | null; // 飞升后待选 3 个 +} + +// config.ts INITIAL_STATE +constellation: [], +pendingPerkChoices: null, +``` + +### 2.5 飞升流程 + +``` +performPrestige(state) + ├─ 计算 newBp（蓝图数） + ├─ rollPerkChoices(constellation) → 3 个不同类别的可选天赋 + ├─ 应用「飞升礼包」补偿（+30 晶体 / +5 洞见，若已解锁） + ├─ 重置资源/技术/接触进度 + └─ 保留：fragments / totalDecoded / blueprints / achievements / constellation +``` + +飞升后 `pendingPerkChoices` 不为空 → `ConstellationDialog` 自动弹出 → 玩家选 1 → `chooseConstellationPerk(perkId)` 写入 constellation 并清空 pending。 + +## 三、UI 组件 + +### 3.1 ConstellationPanel（星图标签内容） + +**Canvas 动态渲染**（requestAnimationFrame 60fps）： +- 六边形布局 6 个星座中心点 +- 每星座内 3 颗星（三角形排布：order 1 顶部，2/3 底部） +- **未解锁星**：暗灰小点 + 弱光晕 +- **已解锁星**：类别色填充 + 强光晕 + 4 道十字光线 + 闪烁动画 +- **同星座已解锁星之间**：连接线（类别色 60% 透明度） +- **星座 → 中心星核**：虚线（已解锁 ≥1 时显示，呼吸效果） +- **中心星核**：紫红色径向渐变，半径随时间正弦呼吸 +- **Hover**：星点 14px 范围内显示 tooltip（天赋名/描述/类别/序号） + +**底部信息区**： +- 6 类别图例条（彩色圆点 + 名称 + 已解锁/总数） +- 已解锁天赋列表（彩色边框 + 名称 + 描述 + 类别标签） +- 空状态：虚线边框卡片 + 引导文案 + +### 3.2 ConstellationDialog（飞升后 draft 模态） + +- 自动 open：`pendingPerkChoices` 非空时 +- 3 张卡片：左侧类别色条 + 圆形首字图标 + 天赋名 + 类别徽章 + 描述 +- 选中动画：8 个粒子 ping + 卡片缩放 + 类别色发光 +- 「重新抽取」按钮：rerollPerkChoices（依然保证 3 不同类别） +- 底部说明：「选择后永久保留，跨周目生效」 + +### 3.3 顶部「觉醒」按钮 + +当 `pendingPerkChoices` 存在时显示，fuchsia 边框 + animate-pulse，点击打开 ConstellationDialog。 + +## 四、平衡设计 + +### 4.1 单天赋强度 +- 每个天赋加成约 +15%~+25% 单项，避免数值膨胀 +- 「飞升礼包」给前期起飞资源（30 晶体 + 5 洞见） +- 「全息共振」给全局 +8%，作为终极通用天赋 + +### 4.2 跨周目叠加 +- 18 个天赋全解锁 ≈ 总加成 200%~300%（与 6 蓝图、14 成就叠加后约 5x~8x） +- 配合飞升次数加成（每次 +15% 探险力、+10 生命），后期探险胜率显著提升 + +### 4.3 类别多样性 +- `rollPerkChoices` 第一轮强制不同类别，避免 3 选全是同类 +- 玩家可在 6 类别间自由构建：采矿流/解码流/探险流/速飞升流/经济流/全能流 + +## 五、QA 验证记录 + +| 测试项 | 结果 | +|--------|------| +| 星图标签页渲染 | ✅ 6 类别图例 + Canvas + 空状态 | +| 对话框自动弹出 | ✅ pendingPerkChoices 设置后立即开 | +| 3 卡片显示 | ✅ 来自 3 不同类别 | +| 点击天赋 | ✅ constellation 添加，crystalsPerSec 提升，pending 清空 | +| 重新抽取 | ✅ 3 张新卡片（依然不同类别） | +| 多天赋叠加 | ✅ c_min_1+c_con_1 → 产能 1.416 / 接触率 1.2 | +| 6 类别成就触发 | ✅ 六分星辉 Toast 弹出 | +| VLM 视觉确认 | ✅ 单星点亮（绿色永动矿脉） | +| lint | ✅ 零错误 | +| 编译 | ✅ < 200ms | + +## 六、与既有系统的协同 + +``` + 飞升(Prestige) + │ + ┌─────────┼─────────┐ + ▼ ▼ ▼ + 蓝图+ 星图天赋+ 成就+ + (5%/3%/4%) (各天赋) (各成就) + │ │ │ + └─────────┴─────────┘ + │ + ▼ + recomputeStats() + │ + ┌─────────┼─────────┐ + ▼ ▼ ▼ + 产能 解码奖励 探险力/生命 + │ + ▼ + 星潮修饰（即时乘） + │ + ▼ + 实际游戏体验 +``` + +## 七、后续扩展方向 + +- **天赋觉醒动画**：选择天赋时全屏闪光 + 星图缩放 +- **天赋重置**：消耗稀有资源重置 constellation，重新选择 +- **隐藏天赋**：达成特殊条件解锁（如「飞升 10 次自选 1 天赋」） +- **天赋树依赖**：order 2 需要 order 1 解锁（增加构建深度） +- **socket 同步**：多人共享同一星图，协作解锁