Minecraft Forge Mod 开发环境搭建

本文参考了 Boson 1.16 Modding Tutorial 的 环境配置^[1] 部分。

准备工具

• IDE：IntelliJ IDEA
• Java开发环境：JDK 8u311
• 安装示例插件：Forge MDK

导入项目

解压下载的压缩文件，使用 IDEA 打开文件夹，等待项目导入完成。

打开 Settings -> Build, Execution, Deployment -> Build Tools -> Gradle，将 Build and run using 设置为 IntelliJ IDEA 以加快运行速度

建议将 build.gradle 中的所有 property 'forge.logging.console.level', 'debug' 改为 property 'forge.logging.console.level', 'info' 以减少日志输出。

打开右侧的 Gradle 面板，运行 genIntellijRuns。

在右上角选择 runClient，使用 run 或 debug 启动 Minecraft。

项目文件结构简介

文件或文件夹	简介
build.gradle	Gradle 配置文件，大部分项目配置都在这里。
build 和 out	编译目录，打包的 jar 文件在 build/libs 中。
run	MC 根目录，可以在此处查看日志等信息。
src	资源文件和源码目录。

配置模组信息

build.gradle

打开 build.gradle，找到 version、group 和 archiveBaseName。

• version 是版本号，一般遵循 Forge的 语义化版本，改为 1.16.5-0.0.1.0。
• group 是包名，一般为域名，这里配置为 com.example。
• archiveBaseName 是打包的文件的基础名，打包的文件名格式为 <archivesBaseName>-<version>.jar。修改完成后点击右上角的 Load Gradle Changes。

mods.toml

这部分内容可以在游戏内的模组列表看到效果。打开 src/main/resources/META-INF/mods.toml，注释说明得很全面，也可以参考下表^[2]：

属性	类型	描述
license	string	许可证名称。
modid	string	modid。
version	string	模组版本，必须是点分隔的数字，最好符合 Forge 的 语义化版本 结构。
displayName	string	模组显示的名称。
updateJSONURL	string	版本 JSON 文件 的 URL。
displayURL	string	模组主页的URL。
logoFile	string	logo 文件名，必须位于 resources 文件夹内。
credits	string	鸣谢。
authors	string	模组作者。
description	string	模组描述，可以是多行。
dependencies	[list]	模组依赖列表。

模组主类

删除 src/main/java 内的全部文件，按 group 和 modid，自己新建一个包和类，这个类就是模组的入口，内容如下：

package com.example.examplemod;

import net.minecraftforge.fml.common.Mod;

@Mod("examplemod")
    public class ExampleMod {
}

pack.mcmeta

数据包描述，可以修改 description。

其它模组

依赖项

如果想将某个模组设置为依赖项，需要在 mods.toml 中配置，每一个依赖项的格式必须为 [[dependencies.modid]]，参考下表^[3]：

属性	类型	描述
modId	string	依赖项的模组 ID。
mandatory	boolean	依赖项未满足时是否崩溃。
versionRange	string	可接受的依赖项版本，以 Maven version spec 表示。空字符串为无边界版本范围，即匹配任意版本。
ordering	string	定义模组是否必须在此依赖项之前或之后加载。有效值为 BEFORE（必须在之前加载）、AFTER（必须在之后加载）和 NONE（不关心顺序）。
side	string	有效值为 CLIENT（存在于客户端）、SERVER（存在于专用服务器）和 BOTH（存在于两侧）。

尽管空字符串的 versionRange 可以匹配任意版本，但是建议使用 [0,) 匹配。

加载模组

如果想加载其它模组，不可以直接放在 /run/mods 中加载，需要配置 build.gradle。^[4]

大部分模组都会提供配置信息，比如 JEI^[5]，配置 build.gradle 即可正确加载：

也有部分模组不提供，可以使用以下两种方式。

本地文件

在项目根目录创建一个 lib 文件夹，将下载的模组文件放入该文件夹。

在 build.gradle 中添加以下配置：

repositories {
    flatDir {
        dirs 'lib'
    }
}

depdependencies 的格式如下：

runtimeOnly fg.deobf("<group>:<artifact>:<version>")

以 JEI 为例，下载 jei-1.16.5-7.7.1.152.jar，放入 lib 文件夹，配置如下：

runtimeOnly fg.deobf("mezz.jei:jei:1.16.5-7.7.1.152")

注：group 不影响本地文件加载，可以随意填写。

Curse Maven

本地文件的方式并不方便，需要手动下载模组，对多人合作也不友好，Curse Maven 支持所有上传到 Curse Forge 的模组，在 build.gradle 中添加以下配置：

repositories {
    maven {
        url "https://cursemaven.com"
        content {
            includeGroup "curse.maven"
        }
    }
}

depdependencies 的格式如下：

runtimeOnly fg.deobf("curse.maven:<descriptor>-<projectid>:<fileids>")

以 JEI 1.16.5-7.7.1.152 为例，配置如下：

runtimeOnly fg.deobf("curse.maven:jei-238222:3681294")

GitHub Actions 配置（可选）

通过配置 GitHub Actions，可以实现发布 Release 和 PR 自动打包。

首先修改 build.gradle，将 version 部分改为以下内容：

if (project.hasProperty('inputVersion')) {
    version = project.inputVersion
} else {
    version = '1.16.5-0.0.1.0'
}

创建 .github/workflows 文件夹，创建两个 yml 文件，注意修改 <modname>。

name: Release Packer
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Release Version'
        required: true
        type: string
      pre_release:
        description: 'This is a pre-release'
        required: true
        type: boolean
        default: false

env:
  NAME: <modname>-${{ github.event.inputs.version }}

jobs:
  pack:
    runs-on: ubuntu-latest
    name: Pack

    steps:
      - name: Check Out
        uses: actions/checkout@v3

      - name: Setup Java
        uses: actions/setup-java@v3
        with:
          java-version: '8'
          distribution: 'adopt'

      - name: Chmod
        run: chmod +x ./gradlew

      - name: Pack
        run: ./gradlew jar

      - name: Create Release
        id: create_release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.event.inputs.version }}
          release_name: ${{ env.NAME }}
          draft: false
          prerelease: ${{ github.event.inputs.pre_release }}

      - name: Upload Release Asset
        uses: actions/upload-release-asset@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          upload_url: ${{ steps.create_release.outputs.upload_url }}
          asset_path: build/libs/${{ env.NAME }}.jar
          asset_name: ${{ env.NAME }}.jar
          asset_content_type: application/java-archive

name: PR Packer
on: pull_request_target

env:
  NAME: "<modname>-#${{ github.event.number }}"

jobs:
  pack:
    runs-on: ubuntu-latest
    name: Pack

    steps:
      - name: Check Out
        uses: actions/checkout@v3
        with:
          ref: ${{ github.event.pull_request.head.sha }}

      - name: Setup Java
        uses: actions/setup-java@v3
        with:
          java-version: '8'
          distribution: 'adopt'

      - name: Chmod
        run: chmod +x ./gradlew

      - name: Pack
        run: "./gradlew -PinputVersion=#${{ github.event.number }} jar"

      - name: Upload Artifact
        uses: actions/upload-artifact@v3
        with:
          name: ${{ env.NAME }}
          path: build/libs/${{ env.NAME }}.jar

      - name: Find Comment
        id: find_comment
        uses: peter-evans/find-comment@v2
        with:
          issue-number: ${{ github.event.number }}
          comment-author: github-actions[bot]
          direction: first

      - name: Create Comment
        uses: peter-evans/create-or-update-comment@v2
        with:
          issue-number: ${{ github.event.number }}
          body: 在 [这里](../actions/runs/${{ github.run_id }}) 下载此 PR 的最新打包。
        if: steps.find_comment.outputs.comment-id == 0

      - name: Update Comment
        uses: peter-evans/create-or-update-comment@v2
        with:
          comment-id: ${{ steps.find_comment.outputs.comment-id }}
          body: 在 [这里](../actions/runs/${{ github.run_id }}) 下载此 PR 的最新打包。
          edit-mode: replace
        if: steps.find_comment.outputs.comment-id != 0

References

1. 环境配置. Boson 1.16 Modding Tutorial. [2022-06-04]. ↩
2. Structuring Your Mod. Forge Documentation. [2022-06-04]. （原始内容存档于2022-06-05）. ↩
3. Mods.toml. Forge Community Wiki. 2022-03-22 [2022-06-04]. （原始内容存档于2022-06-05）. ↩
4. Dependencies. Forge Community Wiki. 2021-08-02 [2022-06-04]. （原始内容存档于2022-06-05）. ↩
5. Getting Started [1.13 and Up]. mezz/JustEnoughItems Wiki. 2021-11-30 [2022-06-05]. （原始内容存档于2022-06-05）. ↩