1. 数据分类#
所有数据先标记所属类别：制作源数据、编译数据、运行时定义、运行时状态、存档数据、本地化数据、平台缓存或日志。每类数据有唯一写入者和可重建规则。
| 类别 | 格式 | 是否进入存档 |
|---|---|---|
| 制作源 | JSON/CSV/Markdown/PO | 否 |
| 编译产物 | 二进制包/索引/manifest | 记录版本和哈希 |
| 运行时定义 | 只读紧凑表 | 由内容包重建 |
| 运行时状态 | 分块数组和稀疏表 | 是 |
| 缓存/日志 | 本地文件 | 否，可删除 |
| 平台状态 | Steam 成就确认等 | 存档只记录同步状态 |
2. 内容 Schema#
定义 Schema 采用显式字段、类型、默认值、范围和引用目标。运行时不接受任意字段。每个对象至少有 id、version、display_key、source_pack、requires 和 capabilities。
definition:
id: stable string
version: semver
display_key: localization key
source_pack: content pack id
requires: [content pack id]
capabilities: [string]
payload: typed fields3. 编译流程#
read sources
-> normalize UTF-8
-> parse
-> schema validate
-> unique ID check
-> reference check
-> dependency graph check
-> numeric and balance check
-> localization check
-> mod capability check
-> emit content.pack/index/manifest
-> write report错误策略
一轮收集全部错误后再失败；不接受“警告后继续”进入正式内容包。编译报告记录文件、对象 ID、字段、错误类型和建议修复位置。
4. 内容包和依赖#
资料片不是代码分支，而是可安装、可激活、可禁用的内容包。依赖图必须无环。激活顺序由拓扑排序决定；冲突由 manifest 声明并在加载前解决。未激活资料片不建立运行时实体。
| 状态 | 允许行为 |
|---|---|
| 目录 | 搜索和阅读，不能参与世界 |
| 已安装 | 可检查依赖，不能自动改变世界 |
| 已激活 | 可解锁、建造、生产、触发事件 |
| 已停用 | 新世界不可用；已有存档进入兼容检查 |
5. MOD 数据合同#
首发 MOD 只允许数据型内容：蓝图、配方、建筑定义、资源、事件、任务和本地化。禁止任意脚本、禁止修改存档格式、禁止替换核心结算器。能力白名单写入 manifest，编译器拒绝越权字段。
6. 版本、哈希和回滚#
每个内容包产生 content_hash、schema_version、minimum_game_version 和 compatibility_range。编译器保留上一版 manifest；新包验证失败时不替换旧包。存档加载时同时检查游戏版本、内容版本、MOD 清单和哈希。
7. 待办与验收#
| 验收项 | 证据 |
|---|---|
| 493 部资料片样本可导入 | 编译报告和 manifest |
| 重复 ID 全部拦截 | 负面测试报告 |
| 断链引用全部列出 | 引用校验报告 |
| 缺失本地化 key 阻断 | 语言完整性报告 |
| 同一输入可重复生成同一 hash | 两次编译哈希对比 |