观前提示

本教程适用于Minecraft 1.21 Fabric的模组开发，不是Java教程。在开始之前也请先学习Java，具有一定的Java基础后再来学习。

由于1.21的底层代码改了很多，这里并不建议按照此教程编写较低版本，请结合实际情况。

如果有问题，请加QQ群（也不要来直接找我）。B站私信不回，谢谢。

更多内容请参考以下视频（序言）：

本篇教程的视频：

本篇教程源代码

GitHub地址：TutorialMod-Template-1.21

准备工作

安装JDK21

由于Minecraft从1.20.5开始就采用了Java21来编写，所以说我们开发1.21的模组自然要采用Java21。这里提供的是Oracle JDK21的下载地址，你也可以选择其他JDK21的版本。

安装的路径一般不用改，除非你C盘真的塞不下了，再改到其他地方去。

JDK下载安装地址：JDK21

环境变量配置

安装好JDK21后，我们需要配置环境变量。其实不配置也可以，但是需要你在IDEA中配置。

我们先找到系统变量，Win11的位置在：设置 -> 系统 -> 系统信息 -> 高级系统设置 -> 环境变量。

然后在系统变量中新建一个JAVA_HOME变量，变量值为你的JDK21的安装路径，如C:\Program Files\Java\jdk-21。

然后再新建一个CLASSPATH变量，变量值为.;%JAVA_HOME%\lib\dt.jar;%JAVA_HOME%\lib\tools.jar;。这样就配置好了JDK21的环境变量。

安装IDEA

IDEA是一个非常好用的IDE，分专业版和社区版，这里我们就选择社区版就好，反正是免费的。

IDEA的安装也很简单，直接下载安装包，然后一路下一步就可以了。安装过程中有一步是选择添加"bin"文件夹到PATH，这个选项可以勾选，但需要重启才会生效。

IDEA下载链接：IDEA

Fabric 开发模板文件生成

Fabric提供了一个模板文件生成器，可以帮助我们快速生成一个Fabric模组的模板文件。

链接：Fabric Template Generator

然后我们来看里面的一些设置：

Mod Name

这个是模组的名字，可以按照你的需求填写，比如TutorialMod。这个名字在生成的文件中，会变成我们的我们之后常说的modid。如果你的模组名字中间有空格，那么生成的文件中会自动把空格替换成-。比如说Tutorial Mod会变成tutorial-mod。

注意，modid一旦生成就不要乱改，否则会导致模组无法正常运行。

Package Name

这个是包名，一般是com.你的名字.模组名。比如说com.besson.tutorialmod。一般就是你的域名倒过来，然后加上模组名。

Minecraft Version

显然易见，这个是我们要开发的Minecraft版本，这里我们选择1.21。

Advanced Options

勾选Data Generation，这个是生成数据包的，我们后面会用到。

不勾选Split client and common sources，这个是分离客户端和服务端源码，我们不需要这个，因为我们的模组基本上是在服务端上运行的（假设你开了个服务器加了这个模组），模组内的运算都是在服务器上完成，再发回客户端的。

另外的两个，其中一个是Kotlin Programming Language，如果你会kotlin，可以勾选，但我不能保证此系列教程是否适用。

另一个是Mojang Mappings，这个是Mojang的官方映射，我们不需要这个，因为我们的模组是基于Fabric的，Fabric已经提供了yarn映射。本教程也是基于Fabric的yarn映射，如果你使用Mojang映射，有些方法名、类名可能会不一样，请自行斟酌。

一切准备完成后，我们点击下方的下载按钮即可下载模板文件。并将它解压到你的工作目录。

初始化项目

接下来，我们用IDEA打开我们的项目。然后它将自动进行Gradle建构。此过程强烈建议使用加速器，不然很容易超时导致建构失败。当然，你可以将gradle的下载源改为腾讯的镜像源，至于方法就自行百度了。

一些小设置

在等待Gradle建构的时候，我们可以先进行一些小设置。

IDEA默认是英文的，我们可以安装一个中文插件，这样IDEA的界面就会变成中文的了。方法：File -> Settings -> Plugins -> 搜索Chinese ​(Simplified)​ Language Pack / 中文语言包 -> 安装。

AI辅助编程的插件也可以安装一下，这样可以更快地编写代码。方法：File -> Settings -> Plugins -> 搜索Copilot或者CodeGeeX -> 安装。前者是GitHub的AI插件，后者是清华的，如果你购买了Copilot，那么就安装Copilot。

翻译插件也可以安装一下，这样可以翻译一些英文的文档。方法：File -> Settings -> Plugins -> 搜索Translation -> 安装。

其他的主题、字体等设置可以自行调整。这里就不再赘述。

检查

当Gradle建构完成后，我们可以检查一下文件是否有问题。看看是否有报错的地方，一般是不会有的。

检查项目结构：文件 -> 项目结构，快捷键Ctrl+Alt+Shift+S，检查项目设置的项目中的SDK，是否为JDK21。

检查Gradle JVM：文件 -> 设置 -> 构建、执行、部署 -> 构建工具 -> Gradle，检查Gradle JVM是否为JDK21。

确保以上两个地方都是JDK21，那一般就不会出问题。

如果运行时出现不支持发行版本21这类问题，基本上是上面两个出问题了，或者JDK21出问题了。

运行genSource

这个是Gradle的一个task，我们可以在IDEA的右侧找到Gradle，然后找到Tasks -> fabric -> genSource，然后双击运行即可。这个用于获取源代码的，方便我们查看源代码。

其他文件

我们来看一下项目中的一些比较重要的文件：

gradle.properties

这个文件是Gradle的配置文件，里面有一些Gradle的配置。

1
2
3
# Done to increase the memory available to gradle.
org.gradle.jvmargs=-Xmx1G
org.gradle.parallel=true

比如说org.gradle.jvmargs=-Xmx1G，这个是Gradle的最大内存，可以根据自己的电脑配置来调整。

而org.gradle.parallel=true是并行编译，这个可以加快编译速度。

1
2
3
4
5
# Fabric Properties
# check these on https://fabricmc.net/develop
minecraft_version=1.21
yarn_mappings=1.21+build.1
loader_version=0.15.11

这个是Fabric的配置，我们可以在这里修改Minecraft版本、yarn映射版本、loader版本。

当版本有更新时，我们可以在这里修改，然后重新建构项目即可。版本信息可以在这里给出的网站上找到。

1
2
3
4
# Mod Properties
mod_version=0.1-1.21
maven_group=com.besson.tutorialmod
archives_base_name=tutorialmod

这个是模组的配置，我们可以在这里修改模组的版本、包名、模组名。

1
2
# Dependencies
fabric_version=0.100.3+1.21

这个是Fabric的API版本，同样我们可以用上面的那个网站来检查更新。

build.gradle

这个是Gradle的构建文件，里面有一些Gradle的配置。

1
2
3
4
plugins {
	id 'fabric-loom' version '1.7-SNAPSHOT'
	id 'maven-publish'
}

这个是Gradle的插件，我们可以在这里添加一些插件。而fabric-loom是Fabric的插件，其版本也可以在上面的网站上找到。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
......
repositories {
	// Add repositories to retrieve artifacts from in here.
	// You should only use this when depending on other mods because
	// Loom adds the essential maven repositories to download Minecraft and libraries from automatically.
	// See https://docs.gradle.org/current/userguide/declaring_repositories.html
	// for more information about repositories.
}

dependencies {
	// To change the versions see the gradle.properties file
	minecraft "com.mojang:minecraft:${project.minecraft_version}"
	mappings "net.fabricmc:yarn:${project.yarn_mappings}:v2"
	modImplementation "net.fabricmc:fabric-loader:${project.loader_version}"

	// Fabric API. This is technically optional, but you probably want it anyway.
	modImplementation "net.fabricmc.fabric-api:fabric-api:${project.fabric_version}"
	
}
......

这个是Gradle的依赖，我们可以在这里添加一些依赖。也是为我们模组添加的依赖，一般的可以被当作lib使用的模组的Wiki中会告诉我们如何添加。后续我们也可以举一些例子。

LICENSE

这是许可证文件，也是开源项目所遵循的开源协议文件。我们可以在这里修改许可证的内容。具体的内容你可以自行百度，把他们复制到这个文件中即可。

fabric.mod.json

路径是src/main/resources/fabric.mod.json，这个是模组的描述文件，里面有一些模组的信息。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
	......
	"id": "tutorialmod",
	"version": "${version}",
	"name": "TutorialMod",
	"description": "这是描述",
	"authors": [
		"北山Besson"
	],
	"contact": {
		"sources": "https://github.com/BeiShanair/tutorialmod-template-1.21"
	},
	"license": "CC0-1.0",
	"icon": "assets/tutorialmod/icon.png",
	"environment": "*"
	......
}

id是模组的ID，就是modid

version是模组的版本，这个是在gradle.properties中配置的

name是模组的名字

description是模组的描述

authors是作者，可以有多个

contact是联系方式，一般是GitHub地址，当然这里还有一个homepage（这里被我删掉了），假设你的模组有一个专门的网站，那可以写上

license是许可证，这个是在LICENSE文件中配置的

icon是模组的图标，这个是在assets/tutorialmod/icon.png中配置的

environment是环境，一般是*，表示所有环境。

下面，我们要为其中的entrypoints添加一些内容。

1
2
3
4
5
6
7
8
9
10
11
12
13
......
"entrypoints": {
		"main": [
			"com.besson.tutorialmod.TutorialMod"
		],
		"fabric-datagen": [
			"com.besson.tutorialmod.TutorialModDataGenerator"
		],
		"client": [
			"com.besson.tutorialmod.TutorialModClient"
		]
	}
	......

这里多加一个client，也就是客户端，因为模组中有一些特殊的代码需要在客户端运行，比如渲染。

而后我们需要创建TutorialModClient这个类

TutorialModClient.java

路径是src/main/java/com/besson/tutorialmod/TutorialModClient.java

1
2
3
4
5
6
public class TutorialModClient implements ClientModInitializer {
    @Override
    public void onInitializeClient() {

    }
}

这个类要实现ClientModInitializer接口，然后重写onInitializeClient方法。这个方法会在客户端初始化的时候被调用。

TutorialMod.java

路径是src/main/java/com/besson/tutorialmod/TutorialMod.java，这个是我们的主类文件，它会在我们游戏启动的时候被调用。我们可以在这里添加一些初始化代码。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public class TutorialMod implements ModInitializer {
	// This logger is used to write text to the console and the log file.
	// It is considered best practice to use your mod id as the logger's name.
	// That way, it's clear which mod wrote info, warnings, and errors.
	public static final String MOD_ID = "tutorialmod";
    public static final Logger LOGGER = LoggerFactory.getLogger(MOD_ID);

	@Override
	public void onInitialize() {
		// This code runs as soon as Minecraft is in a mod-load-ready state.
		// However, some things (like resources) may still be uninitialized.
		// Proceed with mild caution.

		ModItems.registerModItems();
		LOGGER.info("Hello Fabric world!");
	}
}

那么同样的，我还是习惯性的把MODID给单独提出来，这样在后续的代码中，我们可以直接使用TutorialMod.MOD_ID来获取MODID。而MODID也是我们之后用的比较多的字段。

重新建构

因为我们改了一些文件，所以我们需要重新建构一下项目。我们可以找到一个大象带一个重新加载的图标，点击它即可进行重构。

查看源代码/资源文件

查看源代码，我们可以直接利用IDEA的随处搜索，在IDEA界面的右上角，快捷键double Shift，然后输入我们要查找的类名即可。

一些Minecraft的类我们可以按住Ctrl，然后点击类名，就可以直接跳转到Minecraft的源代码中。注意，也许你打开的时候，这个文件的后缀名是.class，我们可以点击选择源，将我们的源代码文件夹选择为一个带source的，一般就是在蹦出来的窗口中，前提是运行了genSource。

另外就是最简单粗暴的方法，直接翻外部库。我们找到Gradle: net.minecraft:minecraft-merged-4eb0fe4bb6:1.21-net.fabricmc.yarn.1_21.1.21+build.1-v2。在这个里面，我们可以找到Minecraft的源代码。net文件夹下存放的一般是Minecraft的源代码，我们可以直接查看。

resource下的assets和data文件也是我们可以查看的东西。assets是资源文件，data是数据文件。

启动！

折腾完以后，我们就可以启动我们的游戏了。我们可以在IDEA的右上角的运行中，找到Minecraft Client运行，也可以找到gradle任务中的runClient运行。

当游戏可以正常运行的时候，那么恭喜你！你已经完成了第一步！

常见问题F&Q

  1. Gradle下载慢怎么办？
  • 可以使用加速器，或者将gradle的下载源改为腾讯、阿里云、清华的镜像源。
  1. Gradle建构超时
  • 挂加速器，或者改为腾讯、阿里云、清华的镜像源。
  1. Gradle建构失败
  • 删除.gradle文件夹，然后重新建构（IDEA抽风的时候可以试试，一般是索引编制出问题了）。
  • 也可以删除C盘的.gradle文件夹，然后重新建构（不过你得重新下载所有gradle文件）。
  1. 不支持发行版本21
  • 检查JDK21是否配置正确
  • 结合上面的检查，检查项目结构和Gradle JVM
  1. 出现net.minecraft.util.InvalidIdentifierException: Non [a-z0-9_.-] ...
  • 只限定在本篇教程中的话，那么一般就是你改动了某些东西，比如说modid，注意modid和其他文件夹不能有大写字母，更不能有中文！
  1. 能不能用其他的IDE
  • 当然可以，只要你用得习惯，编译器都是一样的。
  1. 能不能用Python写？
  • 不能！不能！不能！
  • 这也是我遇到过的最离谱的问题。能问出这个问题的，我只能说你是个人才。