1. 目标与决策边界#
新总原则
本作以 Godot 4.8 dev6 为客户端与工具宿主，运行时数据和玩法计算按照“定义数据、运行时状态、命令、事件、查询”五类对象组织。首版承载系统使用 1m 整数网格、批处理结构检查和查询窗口，不为每个楼格创建 Node。旧的固定层数、固定实体数、固定帧预算、纯 GDScript 仿真、预设仿真域数量和任何未经压测证明的硬数字均不再是设计前提。
真实规模以内容包和运行时压测为准。当前资料库约有 493 部资料片和 555 份内容文档，这决定了系统必须按内容包、依赖图和分块加载设计，而不能把所有资料片写成核心代码分支。
| 目标 | 新口径 | 验收方式 |
|---|---|---|
| 引擎 | Godot 4.8 dev6；GDScript 负责 UI 与编排，C++ GDExtension 负责经过基准确认的热点 | 空工程可加载扩展并运行无头测试 |
| 数据 | 源数据与运行时数据分离；Markdown 仅作策划资料，不直接进游戏循环 | 内容编译器可重复生成同一内容哈希 |
| 性能 | 先建立基准，再按硬件、内容规模、P95 和峰值内存订预算；不把未经压测的固定规模或毫秒数写成性能承诺 | 每次性能报告记录硬件、内容规模、P50/P95/P99 |
| 平台 | 所有 Steam、成就、Cloud、Workshop 调用经 PlatformService | 无 Steam 替身和 Steam 实现通过同一接口测试 |
| 画面范围 | 本册只规定数据访问和刷新边界，不规定贴图、风格或美术流程 | 表现层只能消费查询结果 |
2. 五层运行时结构#
Content Source
-> Content Compiler
-> Compiled Content Pack
-> Runtime Data Store
-> Simulation / Command / Event
-> Godot Query + UI
-> Platform Services| 层 | 职责 | 禁止事项 |
|---|---|---|
| 内容源 | JSON/CSV/PO/Markdown 制作资料 | 不直接被运行时逐文件扫描 |
| 编译层 | Schema、引用、依赖、数值、本地化、许可证校验 | 不偷偷修正错误数据 |
| 运行时数据层 | 连续数组、稀疏索引、定义缓存、分块状态 | 不让 UI 持有可变权威引用 |
| 仿真层 | 按命令推进状态，按时间片批量结算 | 不创建 Node，不调用 UI |
| Godot/平台层 | 输入、查询、显示、Steam 和 Workshop 适配 | 不直接写仿真数组 |
3. 模块边界与通信#
所有写操作都变成 Command，在固定提交边界执行；所有状态变化发出事实 Event；界面通过 Query 读取不可变快照。高频连续值使用批量快照，低频变化使用事件通知，避免每个实体独立信号。
UI -> CommandQueue -> Simulation
Simulation -> EventLog + SnapshotBuilder
UI <- QueryService <- ReadOnlySnapshot
Simulation <-> PlatformService (仅通过成就/云/工坊适配器)跨模块规则
模块之间不持有对方可变实体引用。跨域读取使用查询接口；跨域写入使用命令；长链路结果使用带 revision 的结果包。过期结果不能覆盖新状态。
4. 规模化原则#
资料片、建筑、房间、设备、材料、配方、产业、事件、任务和成就都使用稳定字符串 ID，编译后映射为整数 ID。定义对象只加载一次；玩家世界中的实体只保存 DefinitionId 和必要状态。大世界按 Chunk 管理，远处区域使用聚合状态，只有活跃区域进入细粒度结算。
| 机制 | 作用 |
|---|---|
| 稳定 ID + 代数句柄 | 删除实体后旧引用自动失效，ID 不复用 |
| Chunk 分块 | 按区域装载、保存、结算，避免全世界扫描 |
| Dirty 标记 | 只有发生变化的生产、物流、能源和市场重新计算 |
| 快照交换 | 工作线程只读快照，主线程在边界合并结果 |
| 内容包 | 未激活资料片不进入常驻仿真 |
5. 实施顺序与门禁#
| 阶段 | 交付物 | 进入下一阶段的条件 |
|---|---|---|
| P0 数据基线 | Godot 4.8 dev6 工程、GDExtension、Schema、编译器骨架 | 可编译、可无头运行、能报告错误 |
| P1 运行时核心 | Entity Store、Command、Event、Chunk、时间推进 | 确定性测试通过 |
| P2 性能和存档 | 批量结算、后台保存、迁移和压力套件 | 达到当前基准报告的目标 |
| P3 平台和内容 | Steam、成就、Workshop、资料片加载 | 本地替身与 Steam 测试均通过 |
| P4 内容生产 | 批量导入全部资料片和功能卡片 | 无重复、无断链、无缺失本地化 key |
6. 明确不采用的旧路线#
已废止
废止未经压测验证的固定实体、层数、设备数量和毫秒承诺；废止纯脚本承担全部热点仿真；废止按预先冻结的仿真模块数量组织工程；废止把 Godot 节点数量当作数据模型；废止把 Steam API 直接散落在玩法代码；废止任意脚本权限 MOD 作为首发要求。所有性能数字必须由基准测试产生并附带硬件、内容规模和分位数证据。
7. 风险与复核#
| 风险 | 控制方式 |
|---|---|
| 内容规模导致启动慢 | 只读 manifest，按激活资料片加载，建立索引和缓存 |
| 线程结果覆盖新状态 | world_revision + input_hash 校验 |
| 存档被新内容破坏 | 分块校验、备份、迁移和只读恢复 |
| MOD 破坏成就或存档 | 首发只开放数据型 MOD，存档记录版本和哈希 |
| 性能数字成为新僵化口径 | 每个版本重新记录硬件、数据量和分位数 |