Skip to main content
Version: 1.21.4

NeoForge 入门指南（Getting Started with NeoForge）

本节将介绍如何搭建 NeoForge 开发环境，以及如何运行和测试你的模组（mod）。

前置条件（Prerequisites）​

  • 需要熟悉 Java 编程语言，尤其是它的面向对象（object-oriented）、多态（polymorphic）、泛型（generic）和函数式（functional）特性。
  • 已安装 Java 21 开发工具包（JDK）和 64 位 Java 虚拟机（JVM）。NeoForge 推荐并官方支持 Microsoft builds of OpenJDK，但其他 JDK 也可以正常使用。
caution

请确保你使用的是 64 位 JVM。你可以在终端中运行 java -version 来检查。如果使用 32 位 JVM 可能会出现问题，因为许多功能已经不再支持 32 位 JVM。

  • 熟悉你喜欢的集成开发环境（Integrated Development Environment，IDE）。
    • NeoForge 官方支持 IntelliJ IDEA 和 Eclipse，这两款 IDE 都内置了 Gradle 支持。不过，你也可以选择其他任何 IDE，从 Netbeans、Visual Studio Code 到 Vim 或 Emacs 都可以。
  • 熟悉 Git 和 GitHub。虽然这不是强制要求，但会大大简化你的开发流程。

搭建开发环境（Setting Up the Workspace）​

  • 打开 Mod Developer Kit（MDK）（可以选择 ModDevGradle 或 NeoGradle）的 GitHub 仓库，点击 “Use this template”，然后将新创建的仓库克隆到本地。
    • 如果你不想使用 GitHub，或者想获取某个旧版本的模板，也可以通过 “Code -> Download ZIP” 下载仓库的 ZIP 文件并解压。
  • 打开你的 IDE 并导入 Gradle 项目。Eclipse 和 IntelliJ IDEA 会自动完成此操作。如果你使用的 IDE 不支持自动导入，也可以通过终端命令 gradlew 来导入。
    • 第一次导入时，Gradle 会下载 NeoForge 的所有依赖项，包括 Minecraft 本体，并进行反编译。这个过程可能需要较长时间（根据你的硬件和网络状况，最长可达一小时）。
    • 每当你修改 Gradle 文件时，需要重新加载 Gradle 配置，可以通过 IDE 的 “Reload Gradle” 按钮，或再次使用 gradlew 终端命令来完成。

自定义你的模组信息（Customizing Your Mod Information）​

你可以在 gradle.properties 文件中修改你的模组的许多基本属性，包括模组名称、版本等。更多详细信息请参考 gradle.properties 文件中的注释，或查阅 有关 gradle.properties 文件的文档。

如果你需要进一步自定义构建流程，可以编辑 build.gradle 文件。NeoGradle 是 NeoForge 的 Gradle 插件，提供了多种配置选项，部分内容可在 build.gradle 文件的注释中找到说明。完整文档请参阅 NeoGradle 文档。

caution

只有在你清楚自己在做什么的情况下才应编辑 build.gradle 和 settings.gradle 文件。所有基础属性都可以通过 gradle.properties 文件进行设置。

构建与测试你的模组（Mod）​

要构建你的模组，只需运行 gradlew build。这将在 build/libs 目录下生成一个名为 <archivesBaseName>-<version>.jar 的文件。这里的 <archivesBaseName> 和 <version> 是由 build.gradle 文件设置的属性，默认取自 gradle.properties 文件中的 mod_id 和 mod_version；当然，你也可以在 build.gradle 中进行修改。最终生成的 JAR 文件可以放到启用了 NeoForge 的 Minecraft 的 mods 文件夹下，或者上传到模组分发平台。

如果你想在测试环境中运行你的模组，可以使用自动生成的运行配置，或者直接使用相关任务（如 gradlew runClient）。这会从对应的运行目录（例如 runs/client 或 runs/server）启动 Minecraft，并包含所有指定的源集。默认的 MDK 包含了 main 源集，因此你在 src/main/java 目录下编写的所有代码都会被应用。

服务器测试（Server Testing）​

如果你正在运行一个专用服务器（dedicated server），无论是通过运行配置还是 gradlew runServer，服务器会立即关闭。你需要通过编辑运行目录下的 eula.txt 文件，接受 Minecraft 的最终用户许可协议（EULA）。

一旦接受许可协议，服务器会启动并默认在 localhost（或 127.0.0.1）下可用。然而，此时你仍然无法加入服务器，因为服务器默认处于在线模式（online mode），这需要进行身份验证（而开发者玩家并没有该验证）。为了解决这个问题，再次关闭服务器，并在 server.properties 文件中将 online-mode 属性设置为 false。现在，重新启动服务器，你就可以连接了。

tip

你应始终在专用服务器环境下测试你的模组。这同样适用于 仅客户端模组，因为这些模组在服务器端被加载时不应有任何行为。