配置模组开发环境

要开发模组，需要 Java Development Kit（JDK），安装器可参考 https://adoptium.net/releases.html。专业用户可以从 http://jdk.java.net/ 获取JDK，注意需要手动解压并设置系统变量。

• 自 1.20.5 开始，需要 Java 21 以上版本。
• 自 1.18 开始，需要 Java 17 以上版本。
• 自 1.17 以上开始。需要 Java 16 以上版本。
• 对于旧的 Minecraft 版本，需要 Java 8 以上版本。

关于安装 Java 的更多信息：

• Fabric Wiki 的安装 Java 的玩家教程，分别用于 Windows、MacOS、Linux
• Fabric Documentation 的安装 Java 的玩家教程，分别用于 Windows、MasOS、Linux

写代码前，需要先安装了 Java 的 IDE，例如 IntelliJ IDEA 和 Eclipse，也可使用任何可编辑代码的文本编辑器，如 Visual Studio Code。

如果对这些不熟悉，推荐使用 Intellij IDEA，绝大多数开发者都用这个编写模组。

更详细的教程请见：Fabric Documentation

创建项目有几种方法：

• 从 fabric-example-mod 复制模板项目，排除 LICENSE 和 README.md 文件
• 使用模板生成器
• 使用 Intellij IDEA 的生成器，需要安装 Intellij IDEA 的 Minecraft Development 插件。

部分地区的用户可能会发现，由于网速原因，构建 Gradle 速度可能比较慢。对于中国内地用户，可参考加快 Fabric 模组构建速度的教程和加速 Fabric 模组依赖拉取以及环境搭建教程（链接已失效）。 如果你已经打开代理，但是下载速度仍然比较慢，可以检查一下 IDE 的网络代理设置是否处于关闭状态。对于 IntelliJ IDEA ，你可以在 File → Settings → Appearance & Behavior → System Settings → HTTP Proxy 找到该设置选项卡，如果勾选的是 “No proxy” ，要切换至 “Auto-detect proxy settings” 。

创建项目之后，请根据自己的需要编辑以下文件：

• 编辑 gradle.properties：
  • 确保将 archives_base_name 和 maven_group 设为你喜欢的值。
  • 确保更新 Minecraft、映射、加载器和 loom 的版本——可以在https://fabricmc.net/develop/查询。
  • 添加你需要在 build.gradle 中使用的其他依赖。
• 编辑 fabric.mod.json:
  • 更改你的模组兼容的版本，以及你的模组依赖的模组，还有诸如模组 id 之类的其他信息，更多信息请见此文件的用法。

从 1.19.2 开始，Fabric API 的模组ID由 fabric 变为 fabric-api。如果需要将 1.19.2 的项目向后移植到旧的版本，需要在 fabric.mod.json 的 depends 部分进行相应变更。

如有需要，可以在 gradle.properties 中设置镜像源。镜像源可能有时不可用，或者内容更新滞后，如需使用官方源，可暂时将相关内容注释掉即可。

# loom_libraries_base=https://bmclapi2.bangbang93.com/maven/
loom_resources_base=https://bmclapi2.bangbang93.com/assets/
loom_version_manifests=https://bmclapi2.bangbang93.com/mc/game/version_manifest.json
loom_experimental_versions=https://maven.fabricmc.net/net/minecraft/experimental_versions.json
# loom_fabric_repository=https://repository.hanbings.io/proxy/

如果你使用的是 JetBrains 的 IntelliJ IDEA，请遵循以下步骤（注：中文文本可能会因为 IDEA 或中文插件的版本不同而不同）：

1. 在 IDEA 的主菜单里选择“打开或导入…（Import Project）”（如果已经打开了一个项目，选择位于顶端的“文件→打开…”）。
2. 选择项目的 build.gradle 文件以导入项目。
3. 在 Gradle 配置完成后，关闭并重新加载项目，否则有些运行配置可能无法正常显示。
4. （如果运行配置还没有出现，试试在 Gradle 页面里重新导入项目。）

可选，但推荐做的一件事： IDEA 默认使用 Gradle 来构建你的项目，而这在 Fabric 是不必要的，而且会导致构建时间变长以及热交换（hotswapping）相关的种种问题。以下是让 IDEA 使用默认编译器的步骤：

1. 在 Gradle 页面里打开“Gradle 设置（Gradle Settings）”
2. 将“使用此工具构建和运行（Build and run using）”和“使用此工具运行测试（Run tests using）”选项改成“IntelliJ IDEA”。

不幸的是，目前还不能给“使用此工具构建和运行”和“使用此工具运行测试”设置一个全 IDE 内的默认值，所以这些每创建一个新项目都得重复上述步骤。

注：不要运行 idea 的 gradle 任务，已知它会破坏开发环境。

如果你使用 IntelliJ IDEA，你可以使用 MinecraftDev 插件。该插件支持自动生成 Fabric 项目以及一些与 Mixin 有关的功能，如检查、生成访问器（accessor）和影子（shadow）字段、复制 Mixin 目标参考（JVM 描述符）。

你可以在文件（File） → 设置（Settings） → 插件（Plugins）中打开内部插件浏览器，找到并安装这个插件，只需要在搜索框里搜索“Minecraft”，选择第一个结果安装即可。

对于启动 Minecraft 的开始调试，请看 Fabric Documentations。

如果你使用的是 Eclipse，并且想要生成 IDE 的运行设置，请运行 gradlew eclipse。然后，项目就可以作为普通的（非 gradle）的 Eclipse 项目导入你的工作区内，方法就是“文件” — “导入…”菜单，然后“通用” → “已存在的项目导入工作区”。

如果你使用的是 Visual Studio Code，请参照这篇教程。

阅读 Minecraft 源代码是编写模组时的重要一部分。但是，我们不能发布 Minecraft 的源代码，因为这违反了 Minecraft 的最终用户许可协议（EULA）。你需要自己生成 Minecraft 源代码。

要生成 Minecrat 源代码，运行 gradle 任务 genSources。如果你的 IDE 没有嵌入 gradle，在终端内运行以下命令：./gradlew genSources。反编译可能需要一段时间，取决于计算机的能力。你可能需要在运行任务之后刷新 gradle。

如何阅读源代码，可参考阅读 Minecraft 源代码。

入门可以先尝试添加一些物品和方块。另外，建议了解一下如何在不重启 Minecraft 的情况下应用更改，以便调试。

• 虽然 Fabric API 并不是必需的，但其最首要的目标是提供游戏引擎所不提供的跨模组兼容性和接口，所以我们强烈推荐多使用 Fabric API。本 wiki 上的许多教程也会默认使用 Fabric API。
• 随着 fabric-loom（我们的Gradle构建插件）的开发和改动，有些时候你可能会遇上一些通过重置 Gradle 缓存才能解决的问题。使用 gradlew cleanloom 便能清理缓存，而 gradlew --stop 则能帮助你解决一些其他疑难杂症。
• 保持跟进到最新的 Loom 版本（Loom 版本是在 build.gradle 中定义的），以及 Fabric Loader 和 Fabric API 的版本（这是在 build.gradle 或者 gradle.properties 中定义的）。最新的版本可以在 https://fabricmc.net/develop/ 中找到。即使是旧的 Minecraft 版本，最新的 Loom 和 Fabric Loader 也会支持。
• 保持跟进到最新的 Gradle 版本，这是在 gradle/wrapper/gradle-wrapper.properties 中定义的。最新的 Gradle 也可以用于开发旧的 Minecraft 版本。
  • 不同的 Gradle 版本依赖不同的 Java 版本。
• 如果你在为旧版本开发 Minecraft，除了修改 gradle.properties 外，你还需要修改 build.gradle 和 mixin 配置中更改 Java 兼容性版本。
• 问问题不要犹豫，有问题就问，总有人会帮你解决的。（笑

在运行 Intellij IDEA 的 genSources gradle 任务后，检查源代码是否被正确添加。打开一个 Minecraft .class 文件，点击屏幕右上方的“选择源……”按钮。选择在结尾有“-sources”的jar。

有时当 IDE 在导入 Gradle 项目的时候有些游戏素材不会正常下载。如果遇到这种情况则要手动运行 downloadAssets 任务——既可以使用 IDE 的自带菜单也可以直接执行 gradlew downloadAssets。

有时运行配置可能无效，报告诸如此类的错误：

• Could not find or load class net.fabricmc.devlaunchinjector.Main: java.lang.ClassNotFoundException（找不到或无法加载主类）
• “no JDK module specified” in the run config（运行配置中没有指定 JDK 模块）

有几种可能的修复方法，其中的一个可能会有效：

• 如果使用的是 Intellij IDEA，前往“项目结构”并选择“模块”标签页，清除所有模块。然后重新加载 gradle 项目。
• 这可能是 Intellij IDEA 自近期更新 2023.2 后的一个 bug。要修复，删除整个 `.idea` 文件夹然后重启 Intellij IDEA 即可。模块会重新构建。你可能需要再次指定 Java 版本。如果重启之后没有运行配置，你可以运行 `gradle ideaSyncTask` 然后再检查一下。
• 如果有子项目，确保你的子项目也被正确配置。如果子项目的 build.gradle 存在，检查子项目中是否已启用或应用了 maven-publish gradle 插件。尝试在 build.gradle 文件中加入 apply plugin: maven-publush，如果还完全没有声明的话。
• 如果问题还发生，编辑运行配置，尝试指定模块（参数 -cp 的值）为其他值。

有时你可能会遇到下面这样的错误：

• java.lang.ClassNotFoundException: net.fabricmc.loader.impl.launch.knot.KnotClient
• java.lang.TypeNotPresentException: Type net/minecraft/util/Identifier not present
• java.lang.RuntimeException: Minecraft game provider couldn't locate the game! The game may be absent from the class path, lacks some expected files, suffers from jar corruption or is of an unsupported variety/version.

这可能是因为项目路径有中文字符或其他非 ASCII 字符造成的。可以尝试将项目移到不含中文的路径中，或者在启动参数中（编辑配置），将“Minecraft Client”和“Minecraft Server”启动配置的“缩短命令行”（Shorten command line）由“@argfile (Java 9+)”设为“无”。

另一个可能的解决办法，是在 Windows 的设置或控制面板中找到“区域设置”，并勾选“Beta 版：使用 Unicode UTF-8 提供全球语言支持”，然后重启。

这可能是因为你使用 Intellij IDEA 构建和运行。如果这个问题发生，尝试打开“Gradle Settings”对话框，将“使用此工具构建和运行”和“使用此工具测试”由“IntelliJ IDEA”设置为“Gradle（default）”。

部分地区的用户在下载 Gradle 时，可能遇到 Connection Reset 的问题。这种情况下可以使用镜像源下载 Gradle。例如，在 gradle/wrapper/gradle-wrapper.properties 文件中，将 distributionUrl 的值设置为镜像地址，例如：

# 修改前
distributionUrl=https://services.gradle.org/distributions/gradle-8.7-bin.zip
 
# 修改后
distributionUrl=https://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip

注：Gradle 的镜像不止腾讯。

创建你的第一个物品。