Mod 文件

Mod 文件决定 JAR 中包含哪些 Mod、在“Mod”菜单中显示哪些信息，以及游戏如何加载 Mod。

gradle.properties

gradle.properties 保存 Mod ID、版本等常用属性。构建时，Gradle 读取这些值并替换到 neoforge.mods.toml 等位置。这样只需修改一处，就能在所有相关位置应用。

MDK 的 gradle.properties 也通过注释解释了多数值。

Mod ID

Mod ID 是区分不同 Mod 的主要标识，广泛用于注册表命名空间，以及资源包和数据包命名空间。两个 Mod 使用相同 ID 会阻止游戏加载。

应选择独特、易记的 ID，通常为显示名称的小写形式或某种变体。ID 只能包含小写字母、数字和下划线，长度为 2 至 64 个字符，包含端点。

说明 在 gradle.properties 中修改 ID 会自动应用到其他位置，但主 Mod 类中的 @Mod 注解除外。该处必须手动修改，与属性文件保持一致。

Group ID

build.gradle 的 group 属性仅在计划将 Mod 发布到 Maven 仓库时必需，但始终正确设置它是良好习惯。MDK 通过 gradle.properties 的 mod_group_id 设置。

Group ID 应为顶层包名，更多信息见包结构。

# In your gradle.properties file
mod_group_id=com.example

Java 源代码（src/main/java）的包也应遵循此结构，并以内部包表示 Mod ID：

com
- example (top-level package specified in group property)
    - mymod (the mod id)
        - MyMod.java (renamed ExampleMod.java)

neoforge.mods.toml

此文件位于 src/main/resources/META-INF/neoforge.mods.toml，采用 TOML 格式，定义一个或多个 Mod 的元数据、加载方式及“Mod”菜单中的显示信息。MDK 提供的文件通过注释解释每个条目，下文作进一步说明。

文件可分三部分：关联整个 Mod 文件的非 Mod 专属属性、每个 Mod 各自一节的属性，以及各 Mod 依赖项的配置。某些属性必填，缺失值会抛出异常。

提示 默认 MDK 中，Gradle 会用 gradle.properties 的值替换多个属性。例如，license="${mod_license}" 表示用属性文件中的 mod_license 替换 license。这类值应在 gradle.properties 修改，而不是直接在此修改。

非 Mod 专属属性

这些属性关联 JAR 本身，表示加载方式和额外的全局元数据。

提示 services 的功能等同于模块的 uses 指令，允许加载指定类型的服务。

也可以在 src/main/resources/META-INF/services 中创建服务文件：文件名为服务的完全限定名称，内容为待加载的服务名称。参见 AtlasViewer 示例。

Mod 专属属性

通过 [[mods]] 将属性关联到指定 Mod。这是表数组，下一个表头之前的所有键值属性都属于该 Mod。

# Properties for examplemod1
[[mods]]
modId = "examplemod1"

# Properties for examplemod2
[[mods]]
modId = "examplemod2"

功能要求

功能系统让 Mod 可以要求加载时具备特定设置、软件或硬件。条件不满足时，加载失败，并向用户说明要求。使用表 [features.<modid>] 创建配置，其中 modid 为使用这些要求的 Mod ID。NeoForge 当前提供：

Mod 属性

Mod 属性系统将任意键值与特定 Mod 关联。当多个 Mod 文件定义相同键、但提供不同元数据时，这很有用。可通过 IModInfo#getModProperties 获取映射，再取得指定键的对象值。使用表 [modproperties.<modid>] 创建配置，其中 modid 为使用这些属性的 Mod ID。

// Assume we have two mods `mod1` and `mod2` with the following property configuration in separate files
// [modproperties.mod1]
// key="value1"
// [modproperties.mod2]
// key="value2"

@Mod("mod1")
public class ModOne {

    private final String key;

    public ModOne(ModContainer container) {
        // Will store 'value1' in key
        this.key = (String) container.getModInfo().getModProperties().get("key");
    }
}

@Mod("mod2")
public class ModTwo {

    private final String key;

    public ModTwo(ModContainer container) {
        // Will store 'value2' in key
        this.key = (String) container.getModInfo().getModProperties().get("key");
    }
}

访问转换器专属属性

通过 [[accessTransformers]] 将访问转换器专属属性关联到指定访问转换器。这是表数组，下个表头之前的键值均属于该转换器。表头可省略，但一旦指定，所有元素均必填。

Mixin 配置属性

通过 [[mixins]] 将 Mixin 配置属性关联到指定配置。这是表数组，下个表头之前的键值均属于该 Mixin 区块。表头可省略，但指定后所有元素均必填。

依赖配置

Mod 可以声明依赖，NeoForge 会在加载前检查。使用表数组 [[dependencies.<modid>]] 创建配置，其中 modid 为使用该依赖的 Mod ID。

重要警告 两个 Mod 的 ordering 可能形成循环依赖而崩溃，例如 A 必须在 B 之前加载，同时 B 又必须在 A 之前加载。

Mod 入口点

填写 neoforge.mods.toml 后，还需要提供执行 Mod 的起点，即入口点。具体形式取决于文件中指定的语言加载器。

javafml 与 @Mod

javafml 是 NeoForge 为 Java 提供的语言加载器。入口点为带 @Mod 注解的 public 类，注解值必须是 neoforge.mods.toml 中声明的某个 Mod ID。之后可在构造函数中实现全部初始化逻辑，例如注册事件或添加 DeferredRegister。

主 Mod 类只能有一个 public 构造函数，否则会抛出 RuntimeException。构造函数可以按任意顺序接收以下任意参数，没有必填参数，但不允许重复。

@Mod("examplemod") // Must match a mod id in the neoforge.mods.toml
public class ExampleMod {
    // Valid constructor, only uses two of the available argument types
    public ExampleMod(IEventBus modBus, ModContainer container) {
        // Initialize logic here
    }
}

默认情况下，@Mod 注解在两端都加载。可通过 dist 参数改变：

// Must match a mod id in the neoforge.mods.toml
// This mod class will only be loaded on the physical client
@Mod(value = "examplemod", dist = Dist.CLIENT) 
public class ExampleModClient {
    // Valid constructor
    public ExampleModClient(FMLModContainer container, IEventBus modBus, Dist dist) {
        // Initialize client-only logic here
    }
}

提示 neoforge.mods.toml 条目不一定需要对应 @Mod 注解。反过来，一个条目也可以有多个 @Mod 注解，例如分别组织通用逻辑和仅客户端逻辑。

来源： NeoForged/Documentation（26.1）。中文翻译依据提交 4a680cdd4d15。