thzxx
8f9c3c9a72
AGENTS.md：架构章节重写（0.1.14 大重构路径）+ 引擎红线（时轮/随机/事件闸/特效出口/插件/门面/双金钟罩） + 世界自演进模型 + sqlark陷阱 + 数值基调（0.1.16 修为经济化/0.1.17 市场实体化）+ 修改纪律 README.md：快速开始（1018 用例）+ 0.1.14+ 架构一览 + 守护机制（双金钟罩/事件闸/插件/回放） + 版本沿革 0.1.12-0.1.21 PROJECT_MEMORY.md：版本时间线补齐（0.1.12-0.1.21 每迭代的为什么）+ 关键架构决策 （事件闸定稿/WorldSim 四层递进/引擎表现双通道/normalize即迁移/线程定论） + 踩坑教训（era 无延续档/潮汐符号反向/事件闸竞态/每tick存档/金钟罩盲区） + 诚实技术债清单 + 修改路径
72 lines
5.1 KiB
Markdown
72 lines
5.1 KiB
Markdown
# 仙途家族志 · Chronicle of the Immortal Clan
|
||
|
||
修仙 × 家族 × 经营 × 战斗的家族模拟器（Electron + React + TypeScript + MetonaSqlark）。
|
||
|
||
一座庄园、一家修士、四邻势力，随年月流转：族人修炼突破、建筑产出、探秘寻宝、婚丧嫁娶；
|
||
仇家犯境则结阵应战；百年之际，望气定鼎，春秋原上写下一卷族史。
|
||
**世界也在自演进**：市场有真库存与供需呼吸，NPC 有战略姿态与恩怨网，时代有盛世乱世的大势流转——天下兴衰与家族命运互为因果。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
npm install # 依赖（含 git.metona.cn 私有 registry，token 在用户级 ~/.npmrc）
|
||
npm install-scripts approve electron esbuild # npm12 首装时必须（Electron 二进制）
|
||
npm run dev # 开发模式（热更新）
|
||
npm test # 引擎测试（43 套件 / 1018 用例，纯 Node 无 GUI）
|
||
npm run build # 产物到 out/
|
||
npm run package # 打包（Windows 需在 Windows 侧执行）
|
||
```
|
||
|
||
端到端冒烟（渲染 + OPFS + 开局推进 + 可选截图）：见 `AGENTS.md`「命令」。
|
||
|
||
## 架构一览
|
||
|
||
```
|
||
src/renderer/game/ 纯 TS 引擎（无 React/DOM，vitest 直测；单线程，实测 0.05ms/tick）
|
||
engine/GameEngine.ts 唯一门面：advance / restore / engineFromSnapshot / about / resolvePending
|
||
engine/kernel/ Kernel（Clock+Rng 三合一）+ clock / rng(RngHub) / plugin / guide / urgency...
|
||
engine/runtime/ World（大对象+normalize+bus 转发）· clocks（时轮注册）· ApiFacade（GameFacade）
|
||
Systems/（生产/修炼/任务/事件/外交/婚育/渡劫/大比/寿元/战斗）
|
||
capabilities（12 能力卡）· pluginManager（插件管线）
|
||
engine/sim/ WorldSim（世界自进化）· worldsim-data（数值唯一权威）· Market（行情/买卖）
|
||
engine/narrative/ 族谱/传记/定鼎/年轴/百年报告
|
||
data/ balance 表 + DataPackRegistry（PILL_RECIPES / FORGE_RECIPES / ERA_CONF）
|
||
storage/ db(MetonaSqlark 单例) · slots(槽+快照) · migrate(CURRENT_SCHEMA=2，normalize 即迁移)
|
||
types/domain.ts 全量领域类型（改状态结构先看它）
|
||
src/renderer/ui/ React + zustand（store.ts 主状态；面板按 tab 挂载；LogFeed 精订阅）
|
||
src/main/ Electron 主进程（app:// 协议 + IPC 存档导出/导入）
|
||
```
|
||
|
||
设计文档见 `AGENTS.md`（环境坑 / 架构红线 / 引擎纪律 / 金钟罩双基线 / 修改纪律）。
|
||
|
||
## 守护机制
|
||
|
||
- **双金钟罩**：`tests/clock.test.ts` 的 `GOLDEN`（直调冻结世界）+ `GOLDEN_RESOLVED`（自动 resolve 长跑"现实"世界），各 3 固定 seed × 560/1200/2160 月（47/100/180 年）= 18 指纹；指纹含全世界轴（era/stance/prosperity/关系网/事件闸）；**0.1.21 基线**。有意变更时序需受控更新并注明。
|
||
- **事件闸**：pending 唯一入口 `fire(w,id,priority)`——高优（raid/渡劫/大比）可顶替被占者，被顶替者入队下月兑现；`applyEventChoice` 前置校验防陈旧 Modal 二次结算。
|
||
- **插件化**：万物皆是插件（系统/数据包/事件池），三核心插件 protected 常驻；示例见 tests/helpers/examplePlugin.ts。
|
||
- **可回放**：种子随机（sfc32，引擎域零 Math.random）+ 快照回放保真（restore 重建内核+回置 rng）。
|
||
|
||
## 打包产物
|
||
|
||
- `npm run package` → out/（构建）+ release/（安装包）
|
||
- 图标资源 resources/icon.png|ico —— electron-builder 自动使用
|
||
- 注意：WSL/Linux 交叉打 win 包可行但未签名，正规发布请用 Windows 侧重跑
|
||
|
||
## 版本沿革（0.1.0 → 0.1.21）
|
||
|
||
| 版本 | 主题 |
|
||
|---|---|
|
||
| 0.1.0-0.1.11 | 核心循环 → 插件架构 → 审计三连（详见 docs/PROJECT_MEMORY.md） |
|
||
| 0.1.12 | 金碧山河（SVG 素材 + 动效系统 + 舞美重装） |
|
||
| 0.1.13 | 交付与回档（工艺/界面修复 + UI 存储直连回档） |
|
||
| 0.1.14 | 大重构：GameEngine 门面 + Kernel 三合一 + WorldSim 世界自进化（五大闭环） |
|
||
| 0.1.15 | 深度审计加固（7 P0 + 20+ P1 歼灭；restore 双注册/引擎锁死等） |
|
||
| 0.1.16 | 资源闭环 × 世情入味（修为耗草/炼丹概率化/铸器/灵脉收益/NPC 战力/灾变落效） |
|
||
| 0.1.17 | 天下为市——市场实体化（真库存/供需呼吸/NPC 上桌/玩家回写）+ 战争伤骨 + 关系网 |
|
||
| 0.1.18 | 时代绘卷（世纪弧 era/NPC 景气/蝴蝶效应/十年鉴）+ 特效入引擎（onFx 语义出口） |
|
||
| 0.1.19 | 八方风雨（NPC 战略姿态/超卖潮/盟约连坐/干预天下）+ 孤立系统归并（FxGate/音效/兜底） |
|
||
| 0.1.20 | 万世无谬（第二轮全量审计：事件闸优先级/era 延续/潮汐符号/弱锚定/双金钟罩） |
|
||
| 0.1.21 | 大势流转（线程定论 0.05ms、era↔景气双向闭环、世界史表、渲染管线修复） |
|
||
|
||
详见：`docs/PROJECT_MEMORY.md`（设计哲学与每个迭代的"为什么"）。
|