0x01 工具配置、模组结构与基本语法

“工欲善其事，必先利其器。”

欢迎来到 JSON 模组开发的第一步！在这一章中，我们将从零开始，为你打造一个舒适的开发环境，并带你解剖一个模组的内部结构。最终，我们将亲手写下模组的“身份证”——mod.json。

学习本章需要具备的基础：

知道如何对文件和文件夹进行压缩与解压。
能够进行基本的文件扩展名修改。

工具配置：告别记事本

JSON（JavaScript Object Notation）是一种标记语言，它只负责存储数据，不包含复杂的业务逻辑代码。因此，开发 JSON 模组不需要复杂的集成开发环境（IDE），仅需一个文本编辑器即可。

注意

绝对不要使用 Windows 系统自带的记事本（notepad.exe）！它容易引发意想不到的编码问题（如自动添加 BOM 头），导致游戏无法读取你的文件而频频报错。

我们需要的是具备代码高亮、自动补全括号和代码格式化功能的编辑器。

桌面端（Windows/macOS/Linux）：首推 Visual Studio Code (VSCode)。它免费、轻量且拥有强大的插件生态。对于解压打包，Windows 推荐使用 Bandizip 或 7-Zip。
安卓端：推荐 MT 管理器 或 Squircle CE。它们自带代码高亮，且能够让你在手机上直接方便地修改 .zip 格式的模组包。
iOS端：推荐 Spec Editor，它衍生自 VSCode，支持自动查错与格式化。

模组文件结构：以《饱和火力》为例

一个 JSON 模组本质上就是一个包含了特定文件夹和文件的目录（通常会被打包成 .zip 压缩包发布）。游戏通过按照约定好的目录结构去读取这些文件夹，从而加载你的内容。

如果你解压过大型的优秀模组（例如**《饱和火力 3.3.2.1》**），你会发现它的内部包含了诸如 SFcontent/、sprites/、bundles/、mod.json 以及 classes.dex 等文件。

进阶拓展：《饱和火力》的特殊结构

细心的你可能会注意到，《饱和火力》将它的方块（如各种炮塔、工厂）和物品的 JSON 数据放在了 SFcontent/ 文件夹下，并且根目录带有一个 classes.dex 文件。这是因为它其实是一个 Java 模组（我们在后续的 0x0A 章节会提到）。Java 模组可以通过编写底层代码，自定义任何自己喜欢的数据读取路径。

但对于我们目前的 纯 JSON 模组 而言，必须严格遵守官方原版的约定结构，也就是将数据全部放在 content/ 文件夹下。

以下是标准 JSON 模组的目录结构。在实际开发中，你不需要一次性建好所有文件夹，按需创建即可：

mod.json 或 mod.hjson (必需)：模组的配置文件。
content/：存放所有 JSON 数据的核心文件夹。
- /blocks/：存放方块数据（如工厂、炮塔、钻头）。
- /items/：存放物品数据（如铜、铅）。
- /liquids/：存放流体数据（如水、石油）。
- /units/：存放单位数据（如各种机甲、飞船）。
- /planets/：存放自定义星球数据。
sprites/：模组专属的贴图文件夹（存放你画的 png 图片）。
sprites-override/：用于覆盖原版贴图的文件夹。
bundles/：存放多语言翻译文件（如中文、英文的独立显示文本）。
scripts/：存放 JavaScript 脚本文件（用于实现更复杂的特殊逻辑）。

JSON 与 Hjson 语法：Mindustry 的方言

我们经常说“写 JSON 模组”，但实际上，Mindustry 支持的是一种更宽松、更人性化的方言——Hjson（Human JSON）。Hjson 旨在减少繁琐的标点符号，让人类阅读和编写起来更加舒适。

让我们来看一个实际的对比。以下是定义一个基础工厂方块的数据示例：

标准 JSONHjson (Mindustry 推荐)

json

{
  "type": "GenericCrafter",
  "description": "Hello world!",
  "health": 100,
  "hasItems": true,
  "requirements": [
    { "item": "copper", "amount": 10 },
    { "item": "lead", "amount": 10 }
  ],
  "research": {
    "parent": "copper-wall"
  }
}

hjson

{
  // 这里是单行注释：定义方块类型
  type: GenericCrafter
  description: Hello world!
  health: 100
  hasItems: true
  
  /* 
   这里是多行注释示例
   定义了方块的建造资源需求
  */
  requirements: [
    copper/10
    lead/10
  ]
  
  research: {
    parent: copper-wall
  }
}

我们能从对比中发现什么不同？

省略引号与逗号：Hjson 允许你省略大多数情况下的双引号以及每一行结尾的逗号。
支持注释：标准的 JSON 是绝对不允许写注释的，但 Hjson 可以使用 // 进行单行注释，或使用 /* ... */ 进行多行注释。这对我们在代码中留下备忘非常有帮助。
Mindustry 的独特缩写糖：注意到 copper/10 了吗？这是游戏框架底层提供的特殊解析方式，它完美等价于 {"item":"copper", "amount":10}，这极大地简化了列表的书写！

最佳实践：排版与标点

虽然 Hjson 给了我们极大的自由，但请务必牢记：所有用到的标点符号（冒号 :、大括号 {}、方括号 []）必须是英文半角符号！根据无数前人的血泪教训，游戏中 50% 以上的代码解析报错，都来自于误用了中文冒号 ： 或者少打了一个结尾的 }。

编写 `mod.json`：模组的身份证

千般理论不如一次上手。现在，让我们进行第一次实战：亲手写一份配置文件。在你电脑中喜欢的地方创建一个空文件夹（例如命名为 my-first-mod），在里面新建一个名为 mod.json 的纯文本文件。

回想一下我们参考的《饱和火力》的配置（它定义了 "java": true 和 "main" 入口），由于我们现在只做纯 JSON 模组，我们只需要最基础的信息。请用文本编辑器打开它，输入以下内容：

json

{
  "name": "my-first-mod",
  "displayName": "我的第一个模组",
  "author": "你的名字",
  "description": "这是我跟着教程制作的第一个 Mindustry 模组。",
  "version": "1.0",
  "minGameVersion": "136"
}

name：内部名称。这是模组的唯一标识符，极为重要！强烈建议只使用小写英文字母和连字符（-）。游戏在读取时，会自动将空格转为连字符、大写转为小写。在后续代码中引用你自己的贴图或物品时，我们经常会用到这个内部名称。
displayName：显示名称。玩家在游戏模组列表里看到的实际名字，这里可以随便使用中文或特殊符号。
author 与 description：顾名思义，你的大名与模组的详细介绍。
minGameVersion：最低游戏版本号。这决定了玩家至少需要什么版本的游戏本体才能运行你的模组。目前 v7 时代推荐填写 "136" 或 "146"。

效果验证

完成上述文件的编写并保存后，选中 mod.json 文件（如果未来有 content/ 等文件夹，请一并全选），将它们压缩为 .zip 格式。

::: fatal 常见错误：多套了一层文件夹在压缩时，请直接全选文件进行压缩，确保打开压缩包后，第一眼看到的就是 mod.json。如果打开压缩包看到的是一个文件夹（例如 my-first-mod/），点进这个文件夹后才能看到 mod.json，游戏将会报 No mod.json found 错误！ :::

将压缩好的 .zip 包导入游戏（在主界面选择 设置 -> 模组 -> 导入模组 -> 从文件导入）。重启游戏后，如果你能在模组列表中看到“我的第一个模组”，那么恭喜你！你已经迈出了坚实的第一步。

接下来，我们将进入 0x02，开始运用这些知识，创造属于你的第一件物品与流体。

0x01 工具配置、模组结构与基本语法 ​

工具配置：告别记事本 ​

模组文件结构：以《饱和火力》为例 ​

JSON 与 Hjson 语法：Mindustry 的方言 ​

编写 mod.json：模组的身份证 ​