oes-web/docs/adr/003-json-mod-system.md

ADR-003: 使用 JSON 数据的 Mod 系统

Status

Accepted

Date

2026-05-10

Context

需要实现 Mod 生态系统，要求:

• 玩家可以制作和分享 Mod
• Mod 可以添加新内容和修改现有内容
• 加载顺序可控制
• 冲突可以检测和解决

Decision

使用 JSON 数据文件作为 Mod 格式。

• Mod 格式: JSON 数据 + manifest.json 清单
• 加载方式: 深度合并，后加载覆盖先加载
• 优先级: 数字越小越先加载
• 事件钩子: GameEvents.on() 让 Mod 响应游戏事件
• 验证: JSON Schema 确保数据结构合规

选择此方案而非:

• 二进制格式 (不可读，难以调试)
• 脚本语言 (安全风险，性能问题)
• 文件系统覆盖 (浏览器限制)

Consequences

• Mod 格式简单易懂，玩家容易上手
• JSON 可以被任何文本编辑器修改
• 深度合并可能产生意外覆盖，需要冲突检测
• 运行时加载性能良好