Mindustry JSON Mod开发指南：快速配置自定义星球与星系
这次我们来看一个Mindustry的JSON Mod开发项目，重点不是概念多复杂，而是如何快速上手JSON格式的星球和星系配置。如果你关心Mindustry模组开发、JSON配置语法、新版本特性支持，这篇文章可以直接收藏。
Mindustry作为一款开源塔防游戏，其模组系统允许玩家通过JSON文件自定义游戏内容。从GitHub上的Slotterleet/example-planet-json项目可以看出，JSON Mod开发已经成为新手模组作者的首选方式。这个示例项目包含了几乎所有的星球和星系配置字段，特别适合想要快速入门Mindustry模组开发的玩家。
本文会详细演示如何基于JSON配置创建自定义星球、配置资源分布、设置科技树，并验证在Mindustry v7/v8中的兼容性。我们将从环境准备开始，逐步讲解JSON配置文件的结构，最后测试模组的实际加载效果。
1. 核心能力速览
| 能力项 | 说明 |
|---|---|
| 项目类型 | Mindustry JSON Mod开发示例 |
| 开源来源 | GitHub - Slotterleet/example-planet-json |
| 主要功能 | 通过JSON配置自定义星球、星系、资源分布 |
| 技术基础 | JSON配置文件 + Mindustry Mod API |
| 支持版本 | Mindustry v7及以上，支持新版本星球特性 |
| 开发门槛 | 低，适合新手模组作者 |
| 文档质量 | 高，每个配置字段都有详细说明 |
| 许可证 | GPL-3.0 |
2. 适用场景与使用边界
这个JSON Mod示例最适合以下几类开发者：
适合场景：
- Mindustry模组开发新手想要快速入门
- 需要参考完整的星球配置示例
- 想要了解新版本Mindustry的模组API特性
- 学习如何通过JSON配置实现复杂游戏逻辑
不适合场景：
- 直接游玩（这是开发示例，不是完整游戏模组）
- 高级模组开发（需要结合Java代码）
- 低版本Mindustry（v6及以下可能不兼容）
使用边界提醒：
- 所有配置基于JSON文件，不涉及代码编译
- 需要基本的JSON语法知识
- 配置错误可能导致游戏加载失败
- 建议在测试环境中验证后再发布
3. 环境准备与前置条件
在开始JSON Mod开发前，需要准备以下环境：
基础环境要求：
- Mindustry游戏本体（v7.0或更新版本）
- 文本编辑器（VS Code、Notepad++等）
- 基本的JSON语法知识
文件结构准备：
mindustry-mods/ ├── my-json-mod/ │ ├── mod.hjson │ ├── icon.png │ └── content/ │ └── planets/ │ └── my-planet.json版本兼容性检查：
- 确认Mindustry版本支持JSON模组
- 备份原有模组文件
- 准备测试用的空存档
4. JSON Mod文件结构详解
4.1 模组描述文件 mod.hjson
每个Mindustry模组都需要一个mod.hjson文件，这是模组的元数据配置：
{ "name": "My JSON Planet Mod", "displayName": "自定义星球示例", "author": "YourName", "description": "通过JSON配置的自定义星球示例", "version": "0.01", "minGameVersion": 136, "hidden": false }关键字段说明：
minGameVersion: 最低支持的Mindustry版本号hidden: 设置为false才能在模组列表中显示version: 模组版本，遵循语义化版本控制
4.2 星球配置文件结构
星球配置是JSON Mod的核心，以下是一个基础示例：
{ "name": "my-custom-planet", "localizedName": "自定义星球", "description": "这是一个通过JSON配置的测试星球", "sectorSize": 10, "alwaysUnlocked": false, "allowLaunchLoadout": true, "allowLaunchSchematics": true, "startSector": 1, "rules": [ { "wave": 10, "unit": "dagger" } ], "techTree": [ { "node": "copper", "parents": [] } ] }4.3 资源分布配置
资源分布决定了星球上各种资源的生成规则：
{ "oreScaling": 1.2, "oreProbabilities": { "copper": 0.8, "lead": 0.7, "coal": 0.4 }, "terrain": [ { "type": "flat", "scale": 0.5 }, { "type": "hills", "scale": 0.3 } ] }5. 高级配置特性
5.1 星系和多重星球系统
对于更复杂的模组，可以配置包含多个星球的星系：
{ "name": "custom-star-system", "planets": [ { "name": "planet-a", "distance": 200, "orbitTime": 360 }, { "name": "planet-b", "distance": 400, "orbitTime": 720 } ], "alwaysUnlocked": false }5.2 科技树配置
科技树配置决定了玩家的解锁进度：
{ "techTree": [ { "node": "basic-turrets", "parents": [], "requirements": [ {"item": "copper", "amount": 100} ] }, { "node": "advanced-turrets", "parents": ["basic-turrets"], "requirements": [ {"item": "graphite", "amount": 50}, {"item": "iron", "amount": 100} ] } ] }5.3 自定义规则和游戏机制
通过rules字段可以自定义游戏规则：
{ "rules": [ { "wave": 5, "spawn": "dagger", "amount": 3 }, { "wave": 10, "spawn": "mace", "amount": 2 }, { "condition": "coreHealth", "action": "gameOver", "threshold": 0 } ] }6. 实际部署与测试流程
6.1 模组安装步骤
- 创建模组目录
# 在Mindustry/mods目录下创建新文件夹 cd Mindustry/mods mkdir my-json-planet-mod配置基本文件将mod.hjson、星球JSON配置文件放入对应目录
图标配置准备一个64x64像素的PNG图标作为模组标识
6.2 游戏内测试流程
- 启动Mindustry，进入主菜单
- 打开模组界面，确保新模组已启用
- 创建新游戏，选择自定义星球
- 验证功能：
- 星球是否正常显示在地图选择界面
- 资源分布是否符合预期
- 科技树解锁是否正常
- 敌人波次生成是否正确
6.3 调试技巧
日志查看：
- 游戏日志通常包含模组加载错误信息
- JSON语法错误会直接显示在日志中
常见测试场景：
// 测试用简化配置 { "name": "test-planet", "localizedName": "测试星球", "description": "简化配置用于快速测试", "sectorSize": 5, "alwaysUnlocked": true, "rules": [] }7. 版本兼容性与迁移指南
7.1 Mindustry v7 vs v8
不同版本间的配置差异：
v7特性：
- 基础星球配置
- 简单的资源分布
- 基础科技树
v8新特性：
- 更详细的地形配置
- 高级游戏规则
- 复杂的星系系统
- 新的单位类型支持
7.2 向后兼容配置
为确保模组在多个版本中正常工作：
{ "name": "compatible-planet", "localizedName": "兼容性星球", "minGameVersion": 135, "maxGameVersion": 140, "features": { "v7": ["basic-planet"], "v8": ["advanced-terrain", "complex-rules"] } }8. 性能优化与最佳实践
8.1 JSON文件优化技巧
减少文件大小：
- 删除不必要的空白字符
- 使用简短的字段名
- 合并相似的配置项
优化加载性能：
// 不好的写法 - 重复结构 { "rule1": {"wave": 1, "unit": "dagger"}, "rule2": {"wave": 2, "unit": "dagger"} } // 好的写法 - 使用数组 { "rules": [ {"wave": 1, "unit": "dagger"}, {"wave": 2, "unit": "dagger"} ] }8.2 内存使用优化
对于大型模组的建议：
- 分拆多个JSON文件
- 使用懒加载配置
- 避免过度复杂的嵌套结构
9. 常见问题与排查方法
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| 模组不显示 | mod.hjson配置错误 | 检查文件格式和路径 | 验证JSON语法，确保文件在正确目录 |
| 游戏崩溃 | JSON语法错误 | 查看游戏日志 | 使用JSON验证工具检查语法 |
| 星球不显示 | 版本不兼容 | 检查minGameVersion | 调整版本号或更新游戏 |
| 资源不生成 | 配置概率过低 | 验证oreProbabilities | 提高资源生成概率 |
| 科技树错误 | 依赖关系循环 | 检查techTree配置 | 确保无循环依赖 |
9.1 详细错误排查流程
步骤1：检查基础配置
# 验证mod.hjson基础结构 { "name": "mod-name", # 必须存在 "displayName": "显示名", # 必须存在 "version": "0.1", # 必须存在 "minGameVersion": 136 # 必须存在 }步骤2：验证JSON语法使用在线JSON验证工具或编辑器的语法检查功能。
步骤3：游戏日志分析查看Mindustry日志文件中的错误信息，通常会有具体的行号提示。
步骤4：逐步测试从最简单的配置开始，逐步添加复杂功能进行测试。
10. 实际项目：余火军工0.01到0.02升级指南
基于"余火军工"模组的实际开发经验，从0.01升级到0.02版本需要注意：
10.1 版本迭代规划
0.01版本基础功能：
- 基础星球配置
- 简单资源分布
- 基础敌人波次
0.02版本新增特性：
- 复杂地形生成
- 高级科技树
- 自定义单位
- 多星球星系系统
10.2 升级步骤
- 备份现有配置
- 逐步添加新特性
- 分阶段测试
- 版本号更新
{ "version": "0.02", "changelog": { "added": ["地形系统", "科技树", "自定义单位"], "changed": ["资源平衡", "敌人强度"], "fixed": ["已知崩溃问题"] } }10.3 兼容性处理
确保0.02版本向下兼容：
- 保留旧的配置字段
- 提供迁移脚本或指南
- 明确版本要求
JSON Mod开发为Mindustry模组制作提供了低门槛的入门方式。通过合理的文件结构和配置语法，可以快速实现复杂的游戏内容定制。重点在于理解JSON配置与游戏机制的对应关系，以及掌握版本兼容性的处理方法。
对于想要深入学习的开发者，建议从简单星球配置开始，逐步尝试更复杂的星系系统和游戏规则。每次修改后都要进行充分测试，确保在不同版本的Mindustry中都能稳定运行。