fabric.mod.json 26.2

fabric.mod.json 规范指南。

fabric.mod.json 文件是 Fabric Loader 加载模组时使用的元数据文件。 它必须放置在 JAR 包的根目录下，模组才能被正常加载。

模组模板中包含了一个预定义的 fabric.mod.json 文件，你也可以通过 Fabric Loom 生成它。

你可以查阅 fabric.mod.json v1 规范的源代码。 你还可以在下方找到本站示例模组所使用的 fabric.mod.json 文件。

示例模组的 fabric.mod.json

{
  "schemaVersion": 1,
  "id": "example-mod",
  "version": "1.0.0",
  "name": "Example Mod",
  "icon": "assets/example-mod/icon.png",
  "environment": "*",
  "entrypoints": {
    "main": [
      "com.example.docs.ExampleMod",
      "com.example.docs.event.ExampleModEvents",
      "com.example.docs.command.ExampleModCommands",
      "com.example.docs.effect.ExampleModEffects",
      "com.example.docs.potion.ExampleModPotions",
      "com.example.docs.sound.ExampleModSounds",
      "com.example.docs.damage.ExampleModDamageTypes",
      "com.example.docs.item.ExampleModItems",
      "com.example.docs.enchantment.ExampleModEnchantments",
      "com.example.docs.block.ExampleModBlocks",
      "com.example.docs.block.entity.ExampleModBlockEntities",
      "com.example.docs.menu.ExampleModMenuType",
      "com.example.docs.component.ExampleModComponents",
      "com.example.docs.advancement.ExampleModDatagenAdvancement",
      "com.example.docs.networking.ExampleModNetworking",
      "com.example.docs.networking.basic.ExampleModNetworkingBasic",
      "com.example.docs.debug.ExampleModDebug",
      "com.example.docs.saveddata.ExampleModSavedData",
      "com.example.docs.entity.attribute.ExampleModAttributes",
      "com.example.docs.recipe.ExampleModRecipes",
      "com.example.docs.entity.ExampleModEntity",
      "com.example.docs.gamerule.ExampleModGameRules",
      "com.example.docs.conditions.ExampleModResourceConditions",
      "com.example.docs.stats.ExampleModStats"
    ],
    "client": [
      "com.example.docs.client.command.ExampleModClientCommands",
      "com.example.docs.ExampleModBlockEntityRenderer",
      "com.example.docs.ExampleModDynamicSound",
      "com.example.docs.ExampleModClient",
      "com.example.docs.ExampleModScreens",
      "com.example.docs.rendering.CustomRenderPipeline",
      "com.example.docs.rendering.HudRenderingEntrypoint",
      "com.example.docs.rendering.RenderingConceptsEntrypoint",
      "com.example.docs.network.basic.ExampleModNetworkingBasicClient",
      "com.example.docs.appearance.ExampleModAppearanceClient",
      "com.example.docs.keymapping.ExampleModKeyMappingsClient",
      "com.example.docs.ExampleModRecipesClient",
      "com.example.docs.entity.ExampleModCustomEntityClient"
    ],
    "fabric-datagen": ["com.example.docs.datagen.ExampleModDataGenerator"]
  },
  "mixins": [
    "example-mod.mixins.json",
    {
      "config": "example-mod.client.mixins.json",
      "environment": "client"
    }
  ],
  "depends": {
    "fabricloader": ">=0.19.0",
    "minecraft": "~26.2",
    "java": ">=25",
    "fabric-api": "*"
  },
  "accessWidener": "example-mod.classtweaker"
}

必填字段

Fabric 加载模组时必须包含以下字段。

• schemaVersion 必须是第一个条目，且值必须始终为 1。 这是 Fabric Loader 正确解析文件所必需的。
• id 定义模组标识符的字符串。 必须以字母开头。 仅能包含 ASCII 字母、数字、下划线或连字符。 长度为 2 到 64 个字符。
• version 一个定义模组版本的字符串值；它最好符合语义化版本控制 2.0.0规范的超集，支持任意数量的组件和任意的 build 元数据。 如果与其不匹配，则将其视为纯字符串，不支持版本范围。

"schemaVersion": 1,
"id": "example-mod",
"version": "1.0.0"

元数据

• name：定义易于阅读的模组名称的字符串。 如果不存在，则默认使用 id。
• description：定义模组描述的字符串。 如果不存在，则默认为空字符串。

"name": "Example Mod",
"description": "This is an example description! Tell everyone what your mod is about!",

联系方式

contact：一个定义项目联系信息的字典。 一些常见字段包括：

• email：与模组相关的联系电子邮件。 必须是有效的电子邮件地址。
• homepage：项目或用户的首页。 必须是有效的 HTTP/HTTPS 地址。
• irc：与模组相关的 IRC 频道。 必须符合有效的 URL 格式，例如：EsperNet 上 #charset 频道的 irc://irc.esper.net:6667/charset，端口号可选，未指定默认为 6667。
• issues：项目的问题追踪器。 必须是有效的 HTTP/HTTPS 地址。
• sources：项目源代码仓库。 必须是有效的 URL，它可以是针对特定版本控制系统（如 Git 或 Mercurial）的特殊 URL。

此列表并未列出所有项——模组可以提供额外的非标准键值，如 discord、slack、twitter…… 如果可能，这些都应该是有效的 URL。

"contact": {
    "homepage": "https://fabricmc.net",
    "sources": "https://github.com/FabricMC/fabric-example-mod"
}

作者与贡献者

• authors 模组作者的数组。 条目可以是字符串，也可以是包含下列字段的对象。
• contributors 模组贡献者的数组。 条目可以是字符串，也可以是包含下列字段的对象。

字段：

• name 必填，代表该人物的真实姓名或用户名。
• contact 可选，代表该人物的联系方式。 结构与上文的 contact 相同。

"authors": [
    "Me!",
    {
        "name": "Tiny Potato",
        "contact": {
          "homepage": "https://fabricmc.net",
          "sources": "https://github.com/FabricMC/fabric-example-mod"
        }
    }
]

许可证

• license 定义许可信息的字符串或数组。 为了便于自动化工具识别，建议对开源许可使用 SPDX 许可标识符。

此处应提供满足整个模组包所需的最小许可集。 换句话说，任何想要使用或分发你模组的人只需遵守此处列出的许可即可。 如果你的部分代码采用双重许可，请选择首选许可。 此列表并不一定限制你针对特定人员视情况授予额外权利或应用不同的许可。

"license": "CC0-1.0"

图标

• icon 定义模组图标的字符串或字典。 图标应为正方形 PNG 文件。 Minecraft 资源包使用 128×128，但这并非硬性要求，不过建议使用 2 的次幂。 可以采用以下两种形式之一提供：
  • 单个 PNG 文件的路径。
  • 一个将图像宽度映射到其文件路径的字典。

"icon": "assets/example-mod/icon.png"

模组加载

环境

• environment：一个字符串，定义了模组应该运行在什么环境上：
  • *：运行在任何环境上。 默认值。
  • client：运行在物理客户端。 如果设置为这个值，你的模组不会在专用服务器上加载。
  • server：运行在物理服务器。 如果设置为这个值，你的模组不会在客户端加载，包括单人游戏和局域网联机。

"environment": "*"

入口点

• entrypoints 定义了你的模组会被加载的主类的对象。
  • main 一个字符串数组，包含实现了 ModInitializer 的类名。
  • client 一个字符串数组，包含实现了 ClientModInitializer 的类名。 这个入口点会在 main 之后，且只在物理客户端执行。
  • server 一个字符串数组，包含实现了 DedicatedServerModInitializer 的类名。 这个入口点会在 main 之后，且只在物理服务器执行。

Fabric Loader 提供了这三个主要入口点，但其他模组也可以提供自定义入口点。 例如，Fabric API 为数据生成入口点提供了 fabric-datagen。

每一种入口点可以加载多个类，甚至是方法和静态字段。 例如：

"main": [
    "net.fabricmc.example.ExampleMod",
    "net.fabricmc.example.ExampleMod::handle"
]

TIP

如果你不在使用 Java 开发，你应该去查询对应语言适配器的文档。 对于 Kotlin，请参阅 Fabric Language Kotlin 的 README。

JAR

• jars：包含需要被嵌入你的模组的 JAR 包信息的数组。 当你对依赖使用 include，Loom 会自动帮你写入。 每一项都是一个对象，包含一个 file 键，值为被嵌入的 JAR 包在你的模组内的路径。 例如：

"jars": [
   {
      "file": "nested/vendor/dependency.jar"
   }
]

语言适配器

• languageAdapters：包含实现了 LanguageAdapter 类的字典。

"languageAdapters": {
   "kotlin": "net.fabricmc.language.kotlin.KotlinAdapter"
}

Mixin

• mixins：包含 mixin 配置文件的列表。 每个条目可以是模组 JAR 内 Mixin 配置文件的路径，也可以是一个包含以下字段的对象：
  • config：模组 JAR 内 Mixin 配置文件的路径。
  • environment：和 上述环境字段 的行为一致。 例如：

"mixins": [
   "example-mod.mixins.json",
   {
      "config": "example-mod.client-mixins.json",
      "environment": "client"
   }
]

访问加宽

• accessWidener：指向访问加宽或者类调整器文件的字符串。

"accessWidener": "example-mod.classtweaker"

提供

• provides：作为该模组别名的模组 ID 数组。 Fabric Loader 将视这些 ID 所对应的模组已经存在。 如果有其他模组使用了其中之一，该模组将不会被加载。

"provides": [
   "example_mod"
]

依赖解析

以下键接受依赖项字典。 有关字典结构的更多细节，请参阅下文：

• depends：运行所需的依赖项。 如果缺少任何一项，Fabric Loader 将触发崩溃。
• recommends：运行非必需的依赖项。 如果缺少任何一项，Fabric Loader 将记录一条警告。
• suggests：运行非必需的依赖项。 可将其视为一种元数据。
• breaks：与你的模组同时存在可能会导致游戏崩溃的模组。 如果存在任何一项，Fabric Loader 将触发崩溃。
• conflicts：与你的模组同时存在会导致某些漏洞等问题的模组。 对于每个存在的冲突模组，Fabric Loader 将记录一条警告。

语义化版本控制

每个条目的键是依赖项的模组 ID。

每个键的值是声明依赖项支持的版本范围的字符串或字符串数组。 如果是数组，则只需匹配其中一个范围即可满足约束。

Fabric 使用语义化版本控制的超集来支持任意数量的组件；例如，支持类似 1.2.3.4 这样的版本号。 当比较组件数量不同的版本时，会在右侧填充 0；例如 26.1 = 26.1.0

要匹配范围内的所有预发布版组件，请在范围后添加“-”后缀；例如，要仅获取 26.2 快照，请使用范围 >26.2- <26.2。

版本比较时会忽略构建元数据，即版本号中 + 后面的所有内容。 例如， 0.154+26.3 和 0.154+26.2 是等效的。

以下是一些版本范围及其含义的示例。 尝试使用 Outlet 的 Fabric Loader 验证 来测试哪些值能够满足约束条件。

语义化版本控制示例

注意： Minecraft 并不遵循语义化版本控制。 如果需要，Fabric 会将 Minecraft 版本翻译为等效的语义化版本。 示例包括 26.1->26.1.0、26.1-snapshot-1->26.1-alpha.1、26w14a->26.1.1-alpha.26.14.a。 随着 1.16-rc1 版本的发布，这种模式发生了改变。 之前，Fabric 将类似 1.16-pre1 的预发布版本规范化为 1.16-rc.1，这现在造成了冲突。 从加载器 0.8.8 开始，1.16-rc1 被规范化为 1.16-rc.9，未来的预发布​​版本被规范化为 -beta.n。

范围	说明	匹配项	冲突项
*	任意版本（不推荐）	26.1.2、24w14potato……	无
26.1.2	仅限确切版本	26.1.2	26.1、26.1.1、26.2……
>26	高于某个版本（不含）	26.1.2、26.2……	26、25.x……
>=26.1	等于或高于某个版本（含）	26.1、26.1.2、26.2……	26.0、25.x……
<=26.1	等于或低于某个版本（含）	26.1、26.0、25.x……	26.1.2、26.2……
>26 <26.2	在两个版本之间（均不含）	26.1、26.1.2、快照版本……	26、26.2……
>=26.1 <26.2	在两个版本之间（含下限）	26.1、26.1.2、快照版本……	26.0、26.2……
~26.1-rc.2	与下一个次要版本相同，不含更早的版本（等同于 >=26.1-rc.2 <26.2-）。 仅检查 main 和 minor 组件。	26.1-rc.2、26.1、26.1.2、快照版本……	26.1-rc.1、26.2、27.x……
^26.2	与下一个主要版本相同，不含更早的版本（等同于 >=26.2 <27-）。 仅检查 major 组件。	26.2、26.3……	26.1、25.x、27.x……
26.1.x	等同于 ~26.1-。	26.1-rc-3、26.1、26.1.2、快照版本……	26.2、27.x……
1.x	等同于 ^1-。	1.0.0-beta.4、1.0.0、快照版本……	26.x
>26.2- <26.2	26.2 的所有快照版本，不含 26.2	26.2-pre-1、26.2-rc-1	26.2

注： 如果包含预发布组件（例如 26.1.x-rc.1），则 .x 运算符不起作用；此时，版本范围将被视为纯字符串（请参阅下文的“其他版本格式”）。 .*、.x 或 .X 可以互换使用。 从 Fabric Loader 0.19.3 版本开始，存在一个错误，即对于组件数量超过 3 个的版本，.x 运算符无法正常工作。 这个问题将在未来的版本中修复。

其他版本格式

如果版本不符合 Fabric 支持的扩展 SemVer，则会将其视为字符串，并按照 Java 的 String#compareTo 进行字典序比较，以进行排序。 例如，在加载模组期间，Fabric 必须决定加载哪个版本。

在此模式下，不允许使用范围运算符 < 和 >。 其他范围运算符的行为与 = 相同，但 * 除外，它将继续匹配任何版本。

请参阅纯字符串版本示例。

注： 建议尽可能使用扩展的 SemVer，以支持版本比较和范围！

"depends": {
    "example-mod": "*",
    "minecraft": [
        "26.1",
        "26.1.1"
    ]
}
"suggests": {
    "another-mod": ">1.0.0"
}

自定义字段

你可以在 custom 字段内添加任何想要的字段。 加载器会忽略它们。 但是，强烈建议为你的字段添加命名空间，以避免与其他模组冲突。