查看“JSON模组教程-如何找到自己需要的类和字段”的源代码

= 如何找到自己需要的类和字段 =

写 JSON 模组的尽头就是“查源码”。这是因为 JSON 的字段并不是凭空存在的，它们都来自 Java 类中的字段定义。只要你能准确找到“原版是怎么写的”，就能知道某个字段是否存在、应该怎么写、具体起到什么作用。更重要的是，源码能帮你避免“教程过时”的坑：很多老教程基于旧版本，字段早已改名或被废弃，只有源码才是当前版本的最终答案。

== 从显示名反推内部名 ==

第一步永远是找到内部名。原版的显示名在 <code>core/assets/bundles/bundle_zh_CN.properties</code> 里，例如“幻型”对应 <code>unit.poly</code>，“机械钻头”对应 <code>block.mechanical-drill</code>，“石墨压缩机”对应 <code>block.graphite-press</code>。内部名就是 JSON 文件名，或者 Java 里 <code>new Xxx(&quot;name&quot;)</code> 的 <code>name</code>。拿到内部名，你就能精准搜索源码。

更实际的做法是“先搜中文名，再看键名”。例如你知道“机械钻头”，就直接在 <code>bundle_zh_CN.properties</code> 里搜索它，会得到 <code>block.mechanical-drill.name = 机械钻头</code>。这个键名里的 <code>block.mechanical-drill</code> 就是你要找的内部名。如果你看到多个匹配项，就看前缀：<code>block.</code>、<code>unit.</code>、<code>item.</code>、<code>liquid.</code> 会告诉你内容类型。

<pre>rg -n "机械钻头" core/assets/bundles/bundle_zh_CN.properties</pre>
如果你要核对英文名或其他语言包，同目录下还有 <code>bundle.properties</code> 与其他语言文件。模组也可以提供自己的 <code>bundle_zh_CN.properties</code> 来添加翻译。记住：翻译文件只影响“显示名”，真正的内部名还是由内容文件或 Java 里 <code>new Xxx(&quot;name&quot;)</code> 决定。

如果你不知道该内容属于哪一类，先看内部名前缀：<code>unit.*</code>、<code>block.*</code>、<code>item.*</code>、<code>liquid.*</code>。然后去对应的内容定义文件查它的“原版配置”。原版内容大多在 <code>core/src/mindustry/content/</code> 目录下，比如 <code>Blocks.java</code>、<code>UnitTypes.java</code>、<code>Items.java</code>、<code>Liquids.java</code>。这些文件的作用是“把内容从类变成具体实例”，所以它们是学习字段组合的最好入口。

如果连中文名都找不到，直接看内容文件名也是办法。JSON 文件名通常就是内部名，例如 <code>content/blocks/xxx.json</code> 的 <code>xxx</code> 就是内部名。对模组而言，<code>content/</code> 目录比语言包更直观，因为它不受翻译影响。

<span id="先看原版配置再看类定义"></span>
== 先看原版配置，再看类定义 ==

拿到内部名后，先在 <code>core/src/mindustry/content/</code> 里搜索它是怎么被配置的。这样你能看到最典型的字段组合。例如你搜索 <code>graphite-press</code>，就能看到“石墨压缩机”是 <code>GenericCrafter</code>，并且它设置了 <code>craftTime</code>、<code>outputItem</code> 与消耗项。原版配置告诉你“最常见的写法是什么”。

再比如你搜索 <code>mechanical-drill</code>，会看到它是 <code>Drill</code> 类型，并且只改了 <code>tier</code>、<code>drillTime</code> 等少量字段。这种“只改关键字段”的写法其实最值得学习，因为它能让你理解“哪些字段是必须写的，哪些可以沿用默认值”。如果你一开始就把所有字段都写满，反而很难判断哪些值真正生效。

涉及研究树时，可以顺便看看 <code>core/src/mindustry/content/TechTree.java</code> 和 <code>Objectives</code> 相关类。很多 <code>research</code> 的 <code>objectives</code> 类型都在这里定义，理解它们能让你更准确地写解锁条件，避免“研究树显示了但无法解锁”的问题。

接下来再去类定义文件中查看字段与逻辑。方块类通常在 <code>core/src/mindustry/world/blocks/'''</code>，单位与物品类在 <code>core/src/mindustry/type/'''</code>。阅读类定义可以回答两个关键问题：这个字段是什么类型？这个字段在什么时候被使用？你会发现很多字段只影响 UI 或统计面板，而真正影响逻辑的字段往往集中在 <code>updateTile()</code> 与 <code>init()</code>。

别忽略内部类。很多方块会有 <code>Build</code> 子类（比如 <code>DrillBuild</code>、<code>GenericCrafterBuild</code>），里面保存的是“运行时状态”，例如当前进度、缓冲物品、液体等。这些字段不应该写在 JSON 里，但它们决定了“字段为什么这样生效”。当你理解了 <code>Build</code> 的逻辑，就能更准确判断哪些字段是真正影响产量或行为的。

当你需要理解“运行时逻辑”时，重点看 <code>load()</code>（贴图命名规则）、<code>setStats()</code>（数据库面板如何显示）、<code>updateTile()</code>（方块每帧逻辑）、<code>init()</code>（初始化与额外配置）以及 <code>consumes</code> 相关方法（输入的解析与生效条件）。这些位置往往直接揭示“字段如何生效”。

如果你关心 UI 表现，别忽略 <code>setBars()</code>：很多“效率条”“液体条”就是在这里配置的。你还会看到一些字段只用于 <code>setStats()</code> 或 <code>setBars()</code>，它们不会改变逻辑，但会改变玩家对方块强度的判断。理解这一点很重要，因为你可以通过调整展示字段来引导玩家，而不用改动真正的数值机制。

<span id="用-contentparser-验证-json-支持"></span>
== 用 ContentParser 验证 JSON 支持 ==

即使类里有字段，也不代表 JSON 一定能写。<code>ContentParser</code> 是 JSON 解析器，它决定了哪些写法是合法的。比如 <code>consumes</code> 并不是普通字段，而是被 <code>ContentParser</code> 专门解析的“消耗器语法”；<code>Effect</code>、<code>BulletType</code>、<code>DrawPart</code> 等复杂对象也有专门的解析逻辑。如果你看到字段在类里存在，但写在 JSON 里没效果，就要怀疑解析器是否支持。

当你怀疑“字段写了但没生效”，优先查 <code>core/src/mindustry/mod/ContentParser.java</code>：看看它是否读取了该字段，是否对类型做了特殊处理。很多“JSON 写法不对”的问题，都能在这里找到答案。例如 <code>BulletType</code> 支持字符串（引用原版子弹）、数组（组合为 <code>MultiBulletType</code>）、对象（通过 <code>type</code> 指定子类），这些差异都写在解析器里。

同样的逻辑也适用于 <code>drawer</code>、<code>parts</code>、<code>research</code> 等复杂对象。如果解析器没有对应的分支，你在 JSON 里写再多也不会生效。最典型的例子是 <code>type</code>：当你省略 <code>type</code> 时，解析器会使用默认类；当你写了 <code>type</code>，它才会去实例化对应子类。这一点在 <code>Effect</code>、<code>DrawPart</code>、<code>ShootPattern</code> 等对象上尤其明显。

还要注意“字段类型是否可序列化”。像 <code>Boolf</code>、<code>Func</code> 这种函数类型，或 <code>UnitSorts.closest</code> 这样的静态方法，JSON 是写不进去的，除非解析器提供了特殊语法。你在类里看到这些字段时，要先判断“它是不是一个普通值”；如果不是，就需要 JS/Java 来接管。

解析器通常只会写入 <code>public</code> 字段，<code>private</code>、<code>protected</code> 或标注为运行时状态的字段不会被 JSON 读取。即使字段是 <code>public</code>，如果它被 <code>transient</code> 或特殊逻辑覆盖，也可能“写了看不到效果”。这就是为什么“看类定义 + 看解析器”这两步缺一不可。

<span id="理解字段类型才能写对-json"></span>
== 理解字段类型，才能写对 JSON ==

字段的类型决定写法。<code>int</code>、<code>float</code>、<code>boolean</code> 这类基础类型很好理解，直接写数字或 true/false 即可。复杂类型则需要特别注意：<code>ItemStack</code> 可以写成 <code>&quot;copper/10&quot;</code>，也可以写成 <code>{ &quot;item&quot;: &quot;copper&quot;, &quot;amount&quot;: 10 }</code>；<code>LiquidStack</code> 也支持 <code>&quot;water/0.1&quot;</code> 的简写。<code>Seq</code> 或数组通常写成 JSON 数组。<code>Effect</code> 可以用字符串或对象，<code>BulletType</code> 可以用字符串或对象。

枚举也是常见类型，例如 <code>category</code>、<code>env</code> 或一些开关状态。枚举字段通常用字符串写（大小写要和源码一致），如果字段是“多个标志组合”，解析器可能支持数组或位运算。遇到这类字段时，最稳妥的方式还是去 <code>ContentParser</code> 看具体支持哪种写法。

内容引用字段（<code>Item</code>、<code>Liquid</code>、<code>Block</code>、<code>UnitType</code> 等）一定要写内部名，而不是显示名。你在 JSON 里写“铜”并不会被自动识别成 <code>copper</code>，必须使用内部名 <code>copper</code>。如果你忘了内部名，就回到 <code>bundle_zh_CN.properties</code> 查键名，这是最稳妥的来源。

内部名的拼写也要注意，原版大量使用连字符（例如 <code>mechanical-drill</code>），模组也常用统一前缀。最稳妥的做法是用 <code>rg --files</code> 列出 <code>content/</code> 目录的文件名，再复制粘贴进 JSON，避免拼写错误导致解析失败。

如果你看到字段类型是 <code>Seq&lt;ItemStack&gt;</code> 或 <code>ItemStack[]</code>，就应该优先考虑数组写法；如果字段类型是 <code>ObjectMap</code>，通常会在 JSON 里写成“键值映射”。这些规律可以在解析器里得到验证。

除了看原版，还可以从成熟模组里“反推写法”。例如“饱和火力 3.3.0”的“离子钻头”同时使用 <code>consumes.power</code> 与 <code>consumes.liquid</code>，并把液体消耗写成对象形式来支持 <code>optional</code> 与 <code>booster</code>。这种配置方式在 <code>ContentParser</code> 里是明确支持的，因此你完全可以把它当成“真实可用的模板”，再根据自己的平衡做改动。

== 常用检索方式 ==

如果你习惯命令行，可以直接用 <code>rg</code> 搜索内部名或字段。例如：

<pre>rg "graphite-press" core/src/mindustry/content -n
rg "class GenericCrafter" core/src/mindustry/world/blocks -n</pre>
第一条会定位原版内容配置，第二条会定位类定义。这样一来，你就能把“字段长什么样”与“字段怎么运行”串起来看。很多复杂字段其实只是“从原版抄一个，再改数值”的问题。

查字段时别只盯着当前类。很多基础字段其实来自父类，比如 <code>Block</code>、<code>PowerBlock</code>、<code>LiquidBlock</code>，或者 <code>UnitType</code> 的上层接口。你在子类里找不到字段时，可以沿着 <code>extends</code> 往上找，或者直接搜索字段名（如 <code>rg -n &quot;drillTime&quot; core/src/mindustry/world</code>）。这一步很关键，因为 JSON 能写的字段往往分散在继承链上。

同样地，<code>*Build</code> 内部类也很重要。方块的“运行时逻辑”很多写在 <code>updateTile()</code> 的 <code>Build</code> 版本里，字段有时只在 <code>Build</code> 中使用。理解这一点后，你会更容易区分“配置字段”和“运行时状态”。

如果你想追踪某个字段是如何显示在数据库面板上的，可以用 <code>rg -n &quot;setStats&quot; core/src/mindustry/world/blocks</code> 查找统计展示，再配合 <code>Stat.*</code> 字段定位具体显示名。对 UI 相关问题（比如某个数值显示不对）来说，这一步比盲目试数值更有效。

另外，很多“是否生效”取决于开关字段，比如 <code>hasPower</code>、<code>hasLiquids</code>、<code>hasItems</code>、<code>update</code>、<code>sync</code> 等。这些字段往往在 <code>init()</code> 里被检查，如果没开启，对应系统就不会工作。遇到“字段写了但不动”的情况，先确认这些开关是否被设置。

如果你想了解“原版成本与产量的常见比例”，可以在 <code>Blocks.java</code> 里搜索 <code>requirements</code> 和 <code>outputItem</code> 的组合。这样做比凭感觉调整更稳，尤其是当你想让模组与原版难度保持一致时。

很多老问题其实是“字段记不住”。建议你在熟悉后做一份自己的速查表，把常用字段的用途和默认值记下来。这样比反复翻源码更高效，也能避免“同一个坑踩很多次”。

最后提醒一点：数据库面板显示的数值不一定就是运行时的真实值。很多数值是 <code>setStats()</code> 按“理论值”计算出来的，而运行时会受到效率、输入与环境影响。查源码时把 <code>setStats()</code> 与 <code>updateTile()</code> 对照起来看，才能判断“显示值”和“实际值”的差距。

== 内部名与冲突 ==

JSON 引用内容时，会先尝试 <code>modName-内部名</code>，找不到才去找原版内部名。因此，若你的内部名与原版冲突，会出现覆盖或解析失败。最安全的做法是给自定义内容起一个“有前缀”的内部名，或者在 <code>mod.json</code> 中使用独特的 <code>name</code>，避免与其他模组冲突。

这里的 <code>modName</code> 指的是 <code>mod.json</code> 里的 <code>name</code> 字段，而不是 <code>displayName</code>。这意味着两个模组即使显示名不同，只要 <code>name</code> 相同，就会产生前缀冲突。引用其他模组内容时，也要使用对方的 <code>modName-内部名</code>，否则解析器会优先解析为当前模组或原版内容。

如果你要覆盖原版内容，文件名必须与原版内部名一致，并且清楚自己会影响哪些玩法。覆盖往往是“全局生效”的，一旦修改了产量或伤害，所有地图都会受到影响。除非你真的想重写原版，否则更推荐用新内部名创建“并存内容”。

== 小结 ==

找到字段的流程很简单：先找内部名，再看原版配置，然后看类定义，最后用 <code>ContentParser</code> 验证 JSON 写法。熟练之后，你会发现“查源码”其实比找模板更快，也更稳。把源码、解析器与模组配置对照起来，几乎所有字段问题都能被定位。每次查一次，就会积累一套自己的检索习惯，最后形成稳定的排查流程，效率也会越来越高，实践越多越熟，也更稳妥、更安心。