原文：MinecraftForge/Documentation · 目标版本：Forge 1.20.1
模组文件¶
模组文件（Mod Files）负责确定哪些模组被打包到你的 JAR 中、在「模组」菜单中显示哪些信息，以及你的模组应如何被加载到游戏中。
mods.toml¶
mods.toml 文件定义了模组的元数据。它还包含在「模组」菜单中显示的附加信息，以及模组应如何被加载到游戏中的配置。
该文件使用 TOML（Tom's Obvious Minimal Language） 格式。文件必须存放在你所用源集的资源目录下的 META-INF 文件夹中（对于 main 源集，路径为 src/main/resources/META-INF/mods.toml）。一个 mods.toml 文件大致如下：
modLoader="javafml"
loaderVersion="[47,)"
license="All Rights Reserved"
issueTrackerURL="https://github.com/MinecraftForge/MinecraftForge/issues"
showAsResourcePack=false
clientSideOnly=false
[[mods]]
modId="examplemod"
version="1.0.0.0"
displayName="Example Mod"
updateJSONURL="https://files.minecraftforge.net/net/minecraftforge/forge/promotions_slim.json"
displayURL="https://minecraftforge.net"
logoFile="logo.png"
credits="I'd like to thank my mother and father."
authors="Author"
description='''
Lets you craft dirt into diamonds. This is a traditional mod that has existed for eons. It is ancient. The holy Notch created it. Jeb rainbowfied it. Dinnerbone made it upside down. Etc.
'''
displayTest="MATCH_VERSION"
[[dependencies.examplemod]]
modId="forge"
mandatory=true
versionRange="[47,)"
ordering="NONE"
side="BOTH"
[[dependencies.examplemod]]
modId="minecraft"
mandatory=true
versionRange="[1.20.1,)"
ordering="NONE"
side="BOTH"
mods.toml 由三部分组成：与模组文件本身关联的非模组专属属性、每个模组各有一段配置的模组专属属性，以及每个模组（或多个模组）的依赖配置。下面将逐一说明 mods.toml 中各属性的含义，其中标注为「必填」的属性必须指定值，否则会抛出异常。
非模组专属属性¶
非模组专属属性（Non-Mod-Specific Properties）与 JAR 本身关联，用于指示如何加载其中的模组以及任何额外的全局元数据。
| 属性 | 类型 | 默认值 | 说明 | 示例 |
|---|---|---|---|---|
modLoader |
string | 必填 | 模组使用的语言加载器。可用于支持替代的语言结构，例如以 Kotlin 对象作为主文件，或以接口、方法等方式确定入口点。Forge 提供了 Java 加载器 "javafml" 和低代码/无代码加载器 "lowcodefml"。 |
"javafml" |
loaderVersion |
string | 必填 | 语言加载器的可接受版本范围，使用 Maven 版本范围表示法。对于 javafml 和 lowcodefml，版本号对应 Forge 版本的主版本号。 |
"[47,)" |
license |
string | 必填 | JAR 中模组所采用的许可证。建议设置为所使用的 SPDX 标识符 和/或许可证链接。你可以访问 https://choosealicense.com/ 来帮助选择合适的许可证。 | "MIT" |
showAsResourcePack |
boolean | false |
设为 true 时，模组的资源将在「资源包」菜单中显示为独立的资源包，而非合并到「模组资源」包中。 |
true |
clientSideOnly |
boolean | false |
设为 true 时，Forge 在专用服务器上运行时会跳过加载 mods.toml 中声明的所有模组，并在客户端运行时为它们设置正确的 displayTest。 |
true |
services |
array | [] |
你的模组使用的服务数组。这是 Forge 的 Java 平台模块系统（Java Platform Module System）实现中，为模组创建的模块所消费的配置。该属性已弃用，推荐使用标准的 Java 服务声明方式，即单独的服务文件或 module-info.java 中的 uses 指令。 |
["net.minecraftforge.forgespi.language.IModLanguageProvider"] |
properties |
table | {} |
替换属性的键值表。由 StringSubstitutor 用于将 ${file.<key>} 替换为对应的值。目前仅用于替换模组专属属性中的 version。 |
{ "example" = "1.2.3" }，通过 ${file.example} 引用 |
issueTrackerURL |
string | 无 | 用于报告和追踪模组问题的 URL。 | "https://forums.minecraftforge.net/" |
模组专属属性¶
模组专属属性（Mod-Specific Properties）通过 [[mods]] 头绑定到指定的模组。这是一个表格数组（array of tables）：从该头开始直到下一个头之前的所有键/值属性都将归属于该模组。
| 属性 | 类型 | 默认值 | 说明 | 示例 |
|---|---|---|---|---|
modId |
string | 必填 | 代表该模组的唯一标识符。必须匹配 ^[a-z][a-z0-9_]{1,63}$（2–64 个字符的字符串；以小写字母开头；由小写字母、数字或下划线组成）。 |
"examplemod" |
namespace |
string | 同 modId |
模组的备用命名空间。必须匹配 ^[a-z][a-z0-9_.-]{1,63}$（2–64 个字符的字符串；以小写字母开头；由小写字母、数字、下划线、点或短横线组成）。目前未使用。 |
"example" |
version |
string | "1" |
模组的版本号，建议使用 Maven 版本控制的变体格式。设为 ${file.jarVersion} 时，将被替换为 JAR 清单中 Implementation-Version 属性的值（在开发环境中显示为 0.0NONE）。 |
"1.20.1-1.0.0.0" |
displayName |
string | 同 modId |
模组的显示名称。用于在界面上展示模组（如模组列表、模组版本不匹配界面）。 | "Example Mod" |
description |
string | "MISSING DESCRIPTION" |
在模组列表界面中显示的模组描述。建议使用 多行字面量字符串。 | "This is an example." |
logoFile |
string | 无 | 在模组列表界面中使用的图片文件名（含扩展名）。Logo 必须位于 JAR 根目录或源集根目录下（例如 main 源集的 src/main/resources）。 |
"example_logo.png" |
logoBlur |
boolean | true |
渲染 logoFile 时使用 GL_LINEAR*（true）还是 GL_NEAREST*（false）。 |
false |
updateJSONURL |
string | 无 | 更新检查器使用的 JSON URL，用于确认你正在运行的模组是否为最新版本。 | "https://files.minecraftforge.net/net/minecraftforge/forge/promotions_slim.json" |
features |
table | {} |
见「特性」一节。 | { java_version = "17" } |
modproperties |
table | {} |
与该模组关联的键/值属性表。Forge 本身目前未使用，主要供模组自行使用。 | { example = "value" } |
modUrl |
string | 无 | 模组下载页面的 URL。目前未使用。 | "https://files.minecraftforge.net/" |
credits |
string | 无 | 在模组列表界面中显示的致谢和鸣谢信息。 | "The person over here and there." |
authors |
string | 无 | 在模组列表界面中显示的模组作者。 | "Example Person" |
displayURL |
string | 无 | 在模组列表界面中显示的模组展示页面 URL。 | "https://minecraftforge.net/" |
displayTest |
string | "MATCH_VERSION" |
见「逻辑端」一节。 | "NONE" |
特性¶
特性（Features）系统允许模组在加载时要求某些设置、软件或硬件必须可用。当某个特性要求未被满足时，模组加载将失败，并告知用户相关要求。目前 Forge 提供以下特性：
| 特性 | 说明 | 示例 |
|---|---|---|
java_version |
Java 版本的可接受版本范围，使用 Maven 版本范围表示法。应设置为 Minecraft 所使用的受支持版本。 | "[17,)" |
依赖配置¶
模组可以声明其依赖项，Forge 会在加载模组之前检查这些依赖。依赖配置通过表格数组 [[dependencies.<modid>]] 创建，其中 modid 是需要声明依赖的模组的标识符。
| 属性 | 类型 | 默认值 | 说明 | 示例 |
|---|---|---|---|---|
modId |
string | 必填 | 作为依赖项的模组的标识符。 | "example_library" |
mandatory |
boolean | 必填 | 当该依赖未满足时，游戏是否应崩溃。 | true |
versionRange |
string | "" |
依赖的可接受版本范围，使用 Maven 版本范围表示法。空字符串匹配任意版本。 | "[1, 2)" |
ordering |
string | "NONE" |
定义该模组必须在此依赖之前（"BEFORE"）还是之后（"AFTER"）加载。如果加载顺序无关紧要，设为 "NONE"。 |
"AFTER" |
side |
string | "BOTH" |
依赖项必须存在的[物理端][dist]："CLIENT"、"SERVER" 或 "BOTH"。 |
"CLIENT" |
referralUrl |
string | 无 | 依赖项下载页面的 URL。目前未使用。 | "https://library.example.com/" |
Warning
两个模组的 ordering 可能导致循环依赖而崩溃：例如模组 A 必须在模组 B 之前加载（"BEFORE"），而模组 B 又必须在模组 A 之前加载（"BEFORE"）。
模组入口点¶
mods.toml 填写完毕后，我们需要提供一个入口点（Entrypoint）来开始编写模组代码。入口点本质上是模组执行的起点。入口点本身由 mods.toml 中使用的语言加载器决定。
javafml 与 @Mod¶
javafml 是 Forge 为 Java 编程语言提供的语言加载器。入口点通过带有 @Mod 注解的 public 类来定义。@Mod 的值必须包含 mods.toml 中指定的某个模组 ID。在类的构造函数中，可以编写所有初始化逻辑（例如[注册事件][events]、[添加 DeferredRegister][registration] 等）。模组总线（Mod Bus）可以通过构造函数参数传入的 FMLJavaModLoadingContext 获取。
@Mod("examplemod") // 必须与 mods.toml 中的 modId 匹配
public class Example {
public Example(FMLJavaModLoadingContext context) {
// 在此处编写初始化逻辑
var modBus = context.getModEventBus();
// ...
}
}
lowcodefml¶
lowcodefml 是一种语言加载器，用于将数据包和资源包以模组形式分发，而无需编写代码入口点。之所以命名为 lowcodefml 而非 nocodefml，是因为未来可能会添加需要少量编码的辅助功能。