NeoForge 入门

本节介绍如何搭建 NeoForge 开发工作区，以及如何运行和测试你的 Mod。

前置条件

• 熟悉 Java 编程语言，尤其是面向对象、多态、泛型和函数式编程特性。
• 安装 Java 21 开发工具包（JDK）和 64 位 Java 虚拟机（JVM）。NeoForge 推荐并正式支持 Microsoft 构建的 OpenJDK，其他 JDK 通常也能使用。

注意 请确认你使用的是 64 位 JVM。可以在终端运行 java -version 检查。Minecraft 不支持 32 位 JVM。

• 熟悉你所选择的集成开发环境（IDE）。
  • NeoForge 正式支持 IntelliJ IDEA 和 Eclipse，两者均集成了 Gradle 支持。你也可以使用其他 IDE，例如 Netbeans、Visual Studio Code、Vim 或 Emacs。
• 熟悉 Git 和 GitHub。这并非技术上的硬性要求，但会让开发方便许多。

搭建工作区

• 打开 Mod 开发工具包（MDK）的 GitHub 仓库（可选 ModDevGradle 或 NeoGradle），点击“Use this template”，然后将新建的仓库克隆到本地。
  • 如果不想使用 GitHub，或者需要某个较早提交对应的模板，也可以从 Code → Download ZIP 下载仓库压缩包并解压。
• 打开 IDE，导入 Gradle 项目。IntelliJ IDEA 和 Eclipse 会自动处理。如果 IDE 不会自动导入，也可以使用终端中的 gradlew 命令完成。
  • 首次执行时，Gradle 会下载 NeoForge 的全部依赖（包括 Minecraft 本体）并反编译。这个过程可能比较耗时，最长可能需要一小时，具体取决于硬件和网络情况。
  • 每次修改 Gradle 文件后，都需要重新加载 Gradle 配置。可以使用 IDE 中的“Reload Gradle”按钮，也可以再次运行 gradlew 命令。

Minecraft 源代码

Gradle 成功加载后，工作区中除了示例 Mod 项目，还会包含经过补丁处理的 Minecraft 和 NeoForge 源代码及资源文件，供你查阅。在 IntelliJ IDEA 中可从 External Libraries 找到这些内容，在 Eclipse 中则位于 Referenced Libraries。名称取决于所使用的 Gradle 插件（其中 <version> 是使用的 NeoForge 版本）：

你还可以使用 IDE 的搜索功能查找特定的 Minecraft 类或文件。IntelliJ IDEA 的默认快捷键是连续按两次 Shift，Eclipse 中是 Ctrl+H。

警告 其他 IDE 可能没有这项集成。查看源代码对实现许多功能至关重要；在这方面，NeoForge 仅为 IntelliJ IDEA 和 Eclipse 提供支持。

自定义 Mod 信息

Mod 的许多基础属性都可以在 gradle.properties 文件中修改，例如 Mod 名称和版本。更多信息请查看该文件中的注释，或参阅 gradle.properties 文件文档。

如果还需要进一步修改构建过程，可以编辑 build.gradle。NeoForge 的 Gradle 插件 NeoGradle 提供了多种配置选项，其中一部分在 build.gradle 文件的注释中有所说明。完整内容请参阅 NeoGradle 文档。

注意 只有在清楚所作修改的含义时，才应编辑 build.gradle 和 settings.gradle。基础属性均可通过 gradle.properties 配置。

构建和测试 Mod

运行 gradlew build 构建 Mod。构建结果会输出到 build/libs，文件名为 <archivesBaseName>-<version>.jar。<archivesBaseName> 和 <version> 是 build.gradle 中定义的属性，默认分别取自 gradle.properties 中的 mod_id 和 mod_version；需要时可以在 build.gradle 中修改。生成的 JAR 文件可以放入已安装 NeoForge 的 Minecraft 的 mods 文件夹，也可以上传到 Mod 分发平台。

在测试环境中运行 Mod 时，可以使用生成的运行配置，也可以执行对应任务，例如 gradlew runClient。Minecraft 会从对应的运行目录（例如 runs/client 或 runs/server）启动，并加载指定的源集。默认 MDK 包含 main 源集，因此 src/main/java 下的代码都会生效。

服务端测试

无论通过运行配置还是 gradlew runServer 启动专用服务端，首次运行都会立即关闭。你需要编辑运行目录中的 eula.txt，接受 Minecraft EULA。

接受后，服务端会加载，并可通过 localhost（默认也可使用 127.0.0.1）访问。不过，此时通常仍无法加入，因为服务端默认处于在线模式，需要身份验证，而开发环境中的 Dev 玩家没有相应身份。要解决这一问题，请先停止服务端，再把 server.properties 中的 online-mode 改为 false。重新启动后即可连接。

建议 始终应在专用服务端环境中测试 Mod。仅限客户端的 Mod 也不例外：它们被服务端加载时，应当不执行任何操作。

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