110 lines
3.6 KiB
Markdown
Executable File
110 lines
3.6 KiB
Markdown
Executable File
# 技术架构设计
|
||
|
||
## 一、技术栈
|
||
|
||
| 层 | 技术 | 说明 |
|
||
|---|---|---|
|
||
| 框架 | 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<FragmentId, boolean>; // 已获碎片
|
||
contact: number; // 接触进度 0-100
|
||
|
||
// 产能
|
||
crystalsPerSec: number; // 由技术树计算
|
||
pulsePower: number; // 主动脉冲产出
|
||
|
||
// 技术
|
||
tech: Record<TechId, number>; // 各技术等级
|
||
|
||
// 飞升
|
||
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`，新增碎片只需追加数据。
|
||
- 技术树/解码规则/探险地图均数据驱动，支持后续模块化扩展。
|