缺失的第一课

“工欲善其事，必先利其器；器欲善其用，必先明其法。”

欢迎来到模组开发的“第零课”。

在开始模组制作之前，我们不着急教 mod.json，也不急着写方块。我们要先解决一件更重要的事：怎样阅读教程、怎样正确地使用AI、怎么进行正确的模组实践？

这个想法参考了 MIT 的 Missing Semester（计算机教育中缺失的一课）：很多教程都从“第一行代码”开始，却很少教“如何高效地学习与使用工具”。我们希望把这块缺失的拼图补上。

---

学习的心态

无论你是抱着消遣的心态还是怀有远大的理想，笔者希望您保有一颗不断学习的心，包括但不限于以下部分：

• 相互尊重：本教程不会因为教了什么东西就摆出一幅架子，也希望您能在学习和交流的过程中友善，更不应该“端起碗吃饭，放下碗骂娘”，也不应该倚仗自己有些技术就恃才傲物，盛气凌人；
• 持续学习：学习本教程到何种地步靠的是您的个人意志，无需因为进度产生焦虑感，也要充分发挥自己的主观能动性；
• 认真仔细：这一点在没有集成开发环境可以帮助提前发现错误时特别重要，特别是编写JSON模组或无类型注释时书写JavaScript代码时。有时括号、引号不配对往往是最让人后悔的错误，复制代码时多一行少一行，甚至是字母的差距都是致命的；
• 勇于认错：人非圣贤，孰能无过？技术细节或者是游戏机制记忆不清都很正常，年少轻狂喜欢打肿脸充胖子也很正常，但更重要的是事后的反思与不二过；
• 独立思考：纵使有教程与指导者，自己思考不深入不彻底终究是无用之功，人人独立思考的能力不同，自力更生的时间或早或晚，但最终还是要依赖自己的力量，甚至反哺社区的。

精读与略读

无论您之前有什么样的阅读习惯，我们都建议您从阅读到这一句话开始，就开始

首先，在现阶段，本教程意在以最小的篇幅承载最多的信息含量，因此本教程的信息密度会非常之高；其次，本教程中无宜于实际功能实现的句子占比较低，几乎每句话都承载着一个重要功能的实现方法或者一个极容易踩的坑；最后，人脑的信息处理规律会决定了在快速阅读的过程中难免会忘记中间信息，导致您收到的信息会与本教程本来表达的信息产生偏差，解决这一问题的关键在于您吸收信息的方式，通过仔细地研读或者通过AI辅助阅读来降低信息密度是两种笔者赞成的加强学习效果的阅读方法。

任何知识的建立不是空中楼阁，背后必然有其底层逻辑；但学习的逻辑并不一定是自底而顶的，恰恰相反，为了提高学习热情和提供即时反馈，我们必然要从最表象的制作内容层面出发，在随后的进阶内容中再探究其底层原理。在基础内容的行文过程中，出于书写代码的客观需要，我们不可避免地会提及底层原理，此时我们通常会特别标出，在这些文字中常会出现大量的 新概念（New Concept） ，一般是加粗且注有英文的。此时你只需要略读其中与代码相关的部分，暂时无需要深究内容的含义。

本教程通常不会说什么样的行为是错的，因此当实际情况与预期不符时，最好从头自尾地排查是否某一步理解或执行错误，这时寻求帮助就是有价值的。

如何正确地使用AI

在继续之前，先识别你的设备，以下标准都是当前时代的情况，未考虑边缘情况：

• 手机端（Mobile）：
  • 安卓端（Android）：你使用的是非苹果品牌的手机或平板，此时你的手机运行的是底层由谷歌公司开发的安卓系统（Android）或其魔改版，或者鸿蒙系统（Harmony）；
  • iOS端（苹果手机端）：你使用的是苹果品牌的iPhone或iPad，运行的是苹果公司的iOS手机系统，在iPad上又称iPadOS；
• 桌面端（Desktop）：
  • Windows端：你使用的电脑在左下角或屏幕下方正中间有窗户样图标，运行的是微软公司的Windows操作系统，根据发行年代又可分为Windows 7/8/10/11；
  • macOS端（苹果电脑端）：你使用的是苹果公司出产的电脑且使用原厂的系统，在屏幕左上角有苹果标志，一般无需考虑发行年代；
  • Linux端：你使用的是各个Linux发行版，如Ubuntu、Debian、Arch；

AI 是助教，不是代写

AI 的能力边界

AI的能力边界取决于你能为AI提供怎样的资料。根据提供资料的多少可粗分成两类：

通用聊天机器人：如网页端或APP内的豆包、DeepSeek等。这些AI的特点是其通用性，未针对Mindustry模组编写情境特别获取资源，而是依赖于不准确的联网搜索或支离破碎的训练记忆。这就会导致其编写出的代码出现大量事实上存在的内容，这种现象叫做幻觉（Illusion）。幻觉率高难以修复，人类对其缺少耐受性。

Agent助理：包括Codex、Claude Code、DeepSeek Harness等。通过其电脑使用能力（Computer Use），其可以查阅存储在本地的源代码，降低其幻觉率。

改造聊天机器人

在手机端配置Agent通常是比较困难和不易用的，本节可以帮助你通过一些技巧来增加通用聊天机器人的处理能力。

语法排错

本功能无需AI有多么强大，只需要在输出内容时不丢字即可。将你的代码复制到聊天框或以文件形式发送，并给出提示词：

把这个文件格式化为标准JSON格式，同时原样保留注释

这里我们特别强调保留注释，是因为从语言规范的角度来说，JSON文件是不可以出现注释的，但是在Mindustry中的JSON并不会被当成严格的JSON处理，而是按照一个更加宽松的标准解析，这种宽松JSON被叫做HJSON，关于其更多细节参见后文。

日志总结

本功能也十分简单，只需要你将报错日志找出来（见于下文），并且发给AI即可开始分析。

附带源码

本功能要求有文件上传功能。在之后的章节之中你会了解到如何把功能与对应的源代码区域匹配出来，此时如果你已经定位到一个type的话，你可以直接将对应的源代码扔到AI中，并要求其参考此Java文件输出答案。

例如，如果你想生成一个物品，但苦于豆包总是编造不存在的字段，可以同时附加一个Item.java，如果你已经下载源代码的话，其位于core/src/mindustry/type/Item.java。此时再要求其生成一个物品：

按照此源代码中的字段名称，生成一个Mindustry的物品JSON文件，叫做铀，要求其放射性为10。

当然，你的思路也可以打开，在你探索某个type的字段功能时，也可以拿着源代码文件要求AI给出字段的详细解释，有源代码作为参考，一般来说幻觉率会有很大改善。

什么是字段？

写模组中一个很重要的任务就是填数值，而不严谨地说，在源代码中可以填数值的地方就叫做字段。有的人也喜欢叫它为“接口”“API”“变量”，这些都是从不同维度对同一个东西的理解。对这一概念的正统理解会在靠后的位置展开，其底层原理远超本教程范围，涉及JVM底层。

配置一个Agent

配置部分请参考(https://api-docs.deepseek.com/zh-cn/)[https://api-docs.deepseek.com/zh-cn/] 中“接入Agent”一部分。

你需要先下载好一份源代码。在配置好某个Agent后，直接在对应Agent的聊天框中提及源代码在你电脑上的路径名称即可。

认识世界的正确方式

从错误中学习——找到报错日志

模组出错的表现有很多，发作从早到晚分别是游戏崩溃（Crash）、启动时报错或模组丢失、运行时异常（Exception）、功能不符合预期。第一种和第三种会留下崩溃日志，这是一个存储在游戏数据文件夹/crashes下的一个文件，文件名本身就有时间标记，可以明显地看出哪个是刚刚发生的。前三种都会在运行实时日志中表现出来，而这个日志会存放在游戏数据文件夹/last_log.txt。

为了找到游戏数据文件夹，你需要先判断好你的设备平台。然后按照这个去找：

• Linux： ~/.local/share/Mindustry/mods/
• Steam： steam/steamapps/common/Mindustry/saves/mods/
• Windows： %appdata%/Mindustry/mods/
• MacOS： ~/Library/Application Support/Mindustry/mods/
• Android：/Android/data/io.anuke.mindustry/mods
• iOS：你在做梦

这里的Steam指的是你是在Steam上购买的Mindustry并通过Steam启动了Mindustry。Steam数据和通过其他方法下载的Mindustry的数据是独立的。

有关于安卓端的data/文件夹浏览权限问题，你可能需要下载一个“MT管理器”APP并再次尝试打开此文件夹，并按照APP内提示进行操作。

对于按照上面方法仍然无法解决游戏数据文件夹的安卓设备或iOS设备，还有最后一种方法。开启游戏后，转到“设置-数据-导出崩溃日志”，导出的文件也是拼接后的crash与last_log.txt。

从本体中学习——深入阅读源代码

本体论（Ontology）是哲学中最核心、最根本的分支之一，追问“存在”作为整体，其本质是什么。

在模组制作中，本体论的体现就是——一切问题都能在源代码中找到答案。

Mindustry的源代码就托管在GitHub上，项目地址为https://github.com/Anuken/Mindustry。此外，Mindustry是基于Arc游戏框架开发的，因此你还需要用到https://github.com/Anuken/Arc。

访问这两个网站，你可以在线访问源代码（很考验你的网速），或者是下载源代码。找到Code->Download Zip，这样你就将源代码下载到本地了。

如果你的网络不支持你这么做，你可以选择寻找一些GitHub加速的手段。这里我可以给你提供两个网址：Mindustry最新源代码和Arc最新源代码。

在Mindustry源代码目录下方core/src就是原版大部分源代码了，core/sprites-raw则是原版所有未经处理的贴图。

接续上文，如果你发现阅读Java仍然对你比较困难，也可以借助AI辅助理解。

从实验中学习——控制变量法

当你看到有一个字段不清楚其功能时，最稳的方法可能并非读源代码，也可以试试直接对比一下这个字段填不同的值时会发生什么。