Skip to main content
Version: 1.20.x

模组文件

模组文件负责确定哪些文件会被打包到你模组的JAR文件中，在“Mods”菜单中显示哪些信息，以及你的模组如何被加载到游戏中。

mods.toml​

mods.toml定义你的一个或多个模组的元数据。它也包含一些附加信息，这些信息将在Mods菜单中被展示，并决定你的模组如何被加载进游戏。

该文件采用Tom's Obvious Minimal Language（简称TOML）格式。这个文件必须保存在你所使用的源码集的resource目录中的META-INF文件夹下（例如对于main源码集，其路径为src/main/resources/META-INF/mods.toml）。mods.toml文件看起来长这样：

modLoader="javafml"
loaderVersion="[46,)"

license="All Rights Reserved"
issueTrackerURL="https://github.com/MinecraftForge/MinecraftForge/issues"
showAsResourcePack=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="[46,)"
  ordering="NONE"
  side="BOTH"

[[dependencies.examplemod]]
  modId="minecraft"
  mandatory=true
  versionRange="[1.20]"
  ordering="NONE"
  side="BOTH"

mods.toml被分为三个部分：非模组特定属性，与模组文件相关联；模组特定属性，对每个模组都有单独的小节；以及依赖配置，对每个模组依赖都有单独的小节。下面将解释与mods.toml文件相关的各个属性，其中required表示必须指定一个值，否则将引发异常。

非模组特定属性​

非模组特定属性是与JAR文件本身相关的属性，指明如何加载模组和任何附加的全局元数据。

属性类型缺省值描述样例
modLoaderstring必需模组所使用的语言加载器。可用于支持额外的语言结构，如为主文件定义的Kotlin对象，或确定入口点的不同方法，如接口或方法。Forge提供Java加载器"javafml"和低/无代码加载器"lowcodefml"。"javafml"
loaderVersionstring必需可接受的语言加载器版本范围，以Maven版本范围表示。对于javafml和lowcodefml，其版本是Forge版本的主版本号。"[46,)"
licensestring必需该JAR文件中的模组所遵循的许可证。建议将其设置为你正在使用的SPDX标识符和/或许可证的链接。你可以访问 https://choosealicense.com/ 以帮助选取你想使用的许可证。"MIT"
showAsResourcePackbooleanfalse当为true时，模组的资源会以一个单独的资源包的形式在“资源包”菜单中展示，而不是与“模组资源”包融为一体。true
servicesarray[]表示你的模组所使用的一系列服务的数组。这是从Forge的Java平台模块系统实现中为模组创建的模块的一部分。["net.minecraftforge.forgespi.language.IModLanguageProvider"]
propertiestable{}替换属性表。StringSubstitutor使用它将${file.<key>}替换为相应的值。该功能目前仅用于替换模组特定属性中的version。由${file.example}引用的{ "example" = "1.2.3" }
issueTrackerURLstring无指向报告与追踪模组问题的地点的URL。"https://forums.minecraftforge.net/"

!!! 重要 services属性在功能上等效于在指定在模块中的uses指令，该指令允许加载给定类型的服务。

模组特定属性​

模组特定属性通过[[mods]]头与指定的模组绑定。其本质是一个表格数组（Array of Tables）；直到下一个头之前的所有键/值对都会被关联到那个模组。

# examplemod1的属性
[[mods]]
modId = "examplemod1"

# examplemod2的属性
[[mods]]
modId = "examplemod2"
属性类型缺省值描述样例
modIdstring必需代表这个模组的唯一标识符。该标识符必须匹配^[a-z][a-z0-9_]{1,63}$（一个长度在[2,64]闭区间内的字符串；以小写字母开头；由小写字母、数字或下划线组成）。"examplemod"
namespacestringmodId的值该模组的一个重载命名空间。该命名空间必须匹配^[a-z][a-z0-9_.-]{1,63}$（一个长度在[2,64]闭区间内的字符串；以小写字母开头；由小写字母、数字、下划线、点或短横线组成）。目前无作用。"example"
versionstring"1"该模组的版本，最好符合Maven版本号命名格式。当设置为${file.jarVersion}时，它将被替换为JAR清单文件中Implementation-Version属性的值（在开发环境下默认显示为0.0NONE）。"1.20-1.0.0.0"
displayNamestringmodId的值该模组的更具可读性的名字。用于将模组展示到屏幕上时（如模组列表、模组不匹配）。"Example Mod"
descriptionstring"MISSING DESCRIPTION"在模组列表中展示的该模组的描述。建议使用一个多行文字字符串。"This is an example."
logoFilestring无在模组列表中展示的该模组的logo图像文件的名称和扩展名。该logo必须位于JAR文件的根目录或直接位于源码集的根目录。"example_logo.png"
logoBlurbooleantrue决定使用GL_LINEAR*（true）或GL_NEAREST*（false）渲染logoFile。false
updateJSONURLstring无被更新检查器用来检查你所使用的模组是否为最新版本的指向一个JSON文件的URL。"https://files.minecraftforge.net/net/minecraftforge/forge/promotions_slim.json"
featurestable{}参见 'features'。{ java_version = "17" }
modpropertiestable{}与本模组相关联的一个键/值对表。目前尚未被Forge使用，但主要被模组使用。{ example = "value" }
modUrlstring无指向本模组下载界面的URL。目前无作用。"https://files.minecraftforge.net/"
creditsstring无在模组列表中展示的致谢声明。"The person over here and there."
authorsstring无在模组列表中展示的本模组的作者。"Example Person"
displayURLstring无在模组列表中展示的本模组的展示页面（项目主页）。"https://minecraftforge.net/"
displayTeststring"MATCH_VERSION"参见 'sides'。"NONE"

功能​

功能系统允许模组在加载系统时要求某些设置、软件或硬件可用。当某个功能不满足时，模组加载将失败，并将要求通知给用户。目前，Forge提供以下功能：

功能描述样例
java_version可支持的Java版本范围，以Maven版本范围表示。该范围须能够支持Minecraft所使用的Java版本。"[17,)"

依赖配置​

模组可以指定它们的依赖项，这些依赖项在加载模组之前由Forge检查。这些配置是使用表格数组（Array of Tables）[[dependencies.<modid>]]创建的，其中modid是所依赖的模组的标识符。

属性类型缺省值描述样例
modIdstring必需被添加为依赖的模组的标识符。"example_library"
mandatoryboolean必需当依赖未满足时游戏是否崩溃。true
versionRangestring""可接受的语言加载器版本范围，以Maven版本范围表示。空字符串表示匹配所有版本。"[1, 2)"
orderingstring"NONE"定义本模组是否必须在所依赖的模组之前（"BEFORE"）或之后（"AFTER"）加载。"NONE"表示不规定顺序。"AFTER"
sidestring"BOTH"所依赖模组必须位于的端位："CLIENT"、"SERVER"或"BOTH"。"CLIENT"
referralUrlstring无指向依赖下载界面的URL。目前无作用。"https://library.example.com/"

!!! 警告 两个模组的ordering可能会因循环依赖而造成崩溃：例如模组A必须在模组B之前（"BEFORE"）加载，而模组B也必须在模组A之前（"BEFORE"）加载。

模组入口点​

现在我们已经填写了mods.toml，我们需要提供一个对模组进行编程的入口点。入口点本质上是执行模组的起点。入口点本身由mods.toml中使用的语言加载器决定。

javafml和@Mod​

javafml是Forge为Java编程语言提供的语言加载器。入口点是通过使用带有@Mod注释的公共类来定义的。@Mod的值必须包含mods.toml中指定的一个Mod id。从那里，所有初始化逻辑（例如注册事件、添加DeferredRegister）都可以在类的构造函数中写明。模组总线可以从FMLJavaModLoadingContext获得。

@Mod("examplemod") // 必须匹配mods.toml
public class Example {

  public Example() {
    // 此处初始化逻辑
    var modBus = FMLJavaModLoadingContext.get().getModEventBus();

    // ...
  }
}

lowcodefml​

lowcodefml是一种语言加载器，用于将数据包和资源包作为模组形式分发，而无需代码形式的入口点。它被指定为lowcodefml而不是nocodefml，用于将来可能需要的最少量代码的小添加。