MCBBS Wiki - 最近更改 [zh-cn]

用户:MashKJo/1.12.2模组开发教程/4.Forge事件系统

MashKJo — Thu, 23 Apr 2026 08:27:43 GMT

事件的优先级

←上一版本		2026年4月23日 (四) 16:27的版本
（未显示同一用户的3个中间版本）
第62行：		第62行：
	}		}

	这里我们新建了一个EventHandler类来存放事件监听器。这里我们监听了EntityJoinWorldEvent——顾名思义，实体在世界上生成时，这个事件会被发布。这个事件有着若干getter，我们通过getEntity这一getter获取了生成在世界中的实体对象，并通过instanceof运算符判断其是否为玩家——没错，玩家加入世界的实质是生成了EntityPlayer对象（注意这里笔者的用词，笔者并没有说“生成了一个EntityPlayer对象”，想想看这是为什么）。然后有鉴于这个方法是static的，我们用了自动注册的注解。		这里我们新建了一个EventHandler类来存放事件监听器。这里我们监听了EntityJoinWorldEvent——顾名思义，实体在世界上生成时，这个事件会被发布。这个事件有着若干getter，我们通过getEntity这一getter获取了生成在世界中的实体对象，并通过instanceof运算符判断其是否为玩家——没错，玩家加入世界的实质是生成了EntityPlayer对象（注意这里作者的用词，作者并没有说“生成了一个EntityPlayer对象”，想想看这是为什么）。然后有鉴于这个方法是static的，我们用了自动注册的注解。

	现在运行游戏客户端，随便进入一个存档，你应该能在命令行中看到输出的字符串了。但是注意：这个字符串输出了两次，这实际上是因为两个逻辑端各调用了一次这个监听方法。那么，我们有什么办法能判断当前所处的逻辑端呢？这个会在后面讲到，读者现在留个心眼就行。		现在运行游戏客户端，随便进入一个存档，你应该能在命令行中看到输出的字符串了。但是注意：这个字符串输出了两次，这实际上是因为两个逻辑端各调用了一次这个监听方法。那么，我们有什么办法能判断当前所处的逻辑端呢？这个会在后面讲到，读者现在留个心眼就行。
第72行：		第72行：

	=== 事件的优先级 ===		=== 事件的优先级 ===
	我们可以为事件监听方法指定被调用的优先级，因为@SubscribeEvent注解中有一个参数priority，类型为EventPriority，是个枚举类，有五个实例：HIGHEST、HIGH、NORMAL、LOW、LOWEST。各自的含义应该不需要笔者多说。priority这一参数默认为NORMAL。		我们可以为事件监听方法指定被调用的优先级，因为@SubscribeEvent注解中有一个参数priority，类型为EventPriority，是个枚举类，有五个实例：HIGHEST、HIGH、NORMAL、LOW、LOWEST。各自的含义应该不需要作者多说。priority这一参数默认为NORMAL。

	=== @Cancelable ===		=== @Cancelable ===
第84行：		第84行：
	== 应用：注册注册项 ==		== 应用：注册注册项 ==
	前面说过，将游戏元素注册进注册表的操作，是基于Forge的事件系统的。实际上，我们该监听这么一个事件：<code>RegistryEvent.Register<T extends IForgeRegistryEntry<T>></code>，然后通过<code>event.getRegistry().register</code>或<code>event.getRegistry().registerAll</code>进行注册。		前面说过，将游戏元素注册进注册表的操作，是基于Forge的事件系统的。实际上，我们该监听这么一个事件：<code>RegistryEvent.Register<T extends IForgeRegistryEntry<T>></code>，然后通过<code>event.getRegistry().register</code>或<code>event.getRegistry().registerAll</code>进行注册。

	~~== 自定义Minecraft事件 ==~~
	说实话，这个在几乎所有情况下都没必要。既然你要自定义Minecraft事件了，那显然是给你自己的游戏元素用的——但是你直接去对应的类中写相应的实现代码不就行了？何必多此一举搞个事件？就算你想让你的模组和其他模组的联动更容易，你也大可暴露一些公开方法即可。

	~~然而，还是说说如何操作吧。~~

	首先你需要根据你的事件发挥的具体作用来判断你的事件类到底该继承什么已有的事件类——直接继承Event类是非常非常罕见的。然后再思考：你的事件都需要有哪些getter和setter？你的事件类的父类又有哪些getter和setter？理清楚你的事件类的构造方法所需要的形参列表。

	然后就要到你想发布事件的方法里去new一个你的事件类型了，然后再发布事件：<code>EventBus#post</code>这个方法用于发布某个事件。这个方法是有boolean返回值的，返回true代表事件被取消。所以你一般该这么写：<code>if(!MinecraftForge.EVENT_BUS.post(new MyCustomEvent(...)))</code>。这个if语句后的代码块中，写你期望的默认实现。它的意思即：事件若未被取消，则按照默认实现处理游戏逻辑，同时执行事件监听方法中的追加逻辑。很明显，如果取消了该事件，则可以彻底接管这里的游戏逻辑。

	实际上，Forge发布事件的原理就是这样的。但Forge还把发布事件的过程进行了一些包装：对于可取消的事件，if语句中调用的并非post方法，而是位于ForgeHooks和ForgeHooksClient这两个类中的静态方法。这些静态方法先对传入的参数进行了一定的处理，再return post方法的返回值。对于不可取消的事件，post方法一定返回false，那就不会用if了，直接post，相关的静态工具方法的返回值类型也是void而非boolean了。另外有时候ForgeHooks和ForgeHooksClient中的静态方法，还会再把post方法的调用代理给ForgeEventFactory中的静态方法。

	另外，很多事件都有子类型：Pre和Post（一般是以静态内部类的形式出现在其父类中）。它们的发布时机通常是这样：Pre发布在默认的游戏逻辑执行前，而Post发布在这之后。一般的规律是：Pre可取消，而Post不可取消——毕竟Post发布的时候，默认的游戏逻辑都执行完了，取消了也没用了，因此就干脆设定为不可取消。所以一般来说，如果我们监听事件只是为了给原版的某些机制附加额外行为，那么监听Pre或Post都没区别；但如果想彻底覆盖原版的游戏逻辑，那么监听Pre并取消是最好的：<code>Event#setCanceled</code>。

用户:MashKJo/1.12.2模组开发教程/3.Mod主类与代理详解

MashKJo — Thu, 23 Apr 2026 08:24:29 GMT

←上一版本		2026年4月23日 (四) 16:24的版本
（未显示同一用户的1个中间版本）
第3行：		第3行：
	你可能会注意到，在路径<code>src/main/java</code>路径下有<code>com.example.examplemod</code>这个包，在这个包里有个文件ExampleMod.java。这是Forge给你做的示例，删掉即可。		你可能会注意到，在路径<code>src/main/java</code>路径下有<code>com.example.examplemod</code>这个包，在这个包里有个文件ExampleMod.java。这是Forge给你做的示例，删掉即可。

	~~然后你再根据你的项目具体情况创建一个新的包，由于笔者要写的是Mod开发教程的示例代码，因此笔者把包名定为~~<code>net.tutorial_mod</code>，并在该包下创建Mod主类源文件：		然后你再根据你的项目具体情况创建一个新的包，由于作者要写的是Mod开发教程的示例代码，因此作者把包名定为<code>net.tutorial_mod</code>，并在该包下创建Mod主类源文件：

	<code>src/main/java/net/tutorial_mod/TutorialMod.java:</code>		<code>src/main/java/net/tutorial_mod/TutorialMod.java:</code>
第101行：		第101行：
	可能有读者会疑惑：怎么没有ServerProxy，而是给物理服务端用CommonProxy？之前说过，我们的模组里不该有<code>@SideOnly(Side.SERVER)</code>的代码啊，所以实际上物理服务端该执行的代码，物理客户端一定会执行。因此，直接给物理服务端用CommonProxy就行。		可能有读者会疑惑：怎么没有ServerProxy，而是给物理服务端用CommonProxy？之前说过，我们的模组里不该有<code>@SideOnly(Side.SERVER)</code>的代码啊，所以实际上物理服务端该执行的代码，物理客户端一定会执行。因此，直接给物理服务端用CommonProxy就行。

	另外，读者应该注意到了，ClientProxy.~~java被笔者新建了一个文件夹client来存放。这种只在物理客户端有意义的类，通常就会放在client文件夹中，这是一个好习惯。~~		另外，读者应该注意到了，ClientProxy.java被作者新建了一个文件夹client来存放。这种只在物理客户端有意义的类，通常就会放在client文件夹中，这是一个好习惯。

用户:MashKJo/1.12.2模组开发教程/2.基础概念

MashKJo — Thu, 23 Apr 2026 08:22:42 GMT

注册表

←上一版本		2026年4月23日 (四) 16:22的版本
（未显示同一用户的2个中间版本）
第12行：		第12行：
	Minecraft.getMinecraft().getTextureManager().bindTexture(location);		Minecraft.getMinecraft().getTextureManager().bindTexture(location);

	Minecraft就会尝试去原版和各个模组的.jar包中找路径为<code>assets/minecraft/textures/items/apple.png</code>的文件，代码中的<code>TextureManager#bindTexture</code>的作用是把图片绑定到当前渲染器，那么，苹果的材质文件就会被绑定。当然，这段代码看不懂没关系。笔者只是想说明ResourceLocation对象的使用机制：一般情况下，它实际上能指代一个位于某个.jar包中路径为<code>"assets/" + resourceDomain + "/" + resourcePath</code>的文件。		Minecraft就会尝试去原版和各个模组的.jar包中找路径为<code>assets/minecraft/textures/items/apple.png</code>的文件，代码中的<code>TextureManager#bindTexture</code>的作用是把图片绑定到当前渲染器，那么，苹果的材质文件就会被绑定。当然，这段代码看不懂没关系。作者只是想说明ResourceLocation对象的使用机制：一般情况下，它实际上能指代一个位于某个.jar包中路径为<code>"assets/" + resourceDomain + "/" + resourcePath</code>的文件。

	但是也不是所有时候都是如此，比如在设定物品的模型文件的时候，resourcePath就不需要打那么多了，只需要<code>new ResourceLocation(modid, itemid)</code>就可以了，比如<code>new ResourceLocation("minecraft", "apple")</code>~~。所以，笔者的建议是，如果是你自定义的渲染操作，你按照“路径为~~<code>"assets/" + resourceDomain + "/" + resourcePath</code>”的规则，是没问题的；但是如果你要用Minecraft或Forge内置的某些方法，其中要传入一个ResourceLocation对象，那你就要小心了，还是点进去看看Minecraft或Forge的代码到底是怎么处理这个ResourceLocation的吧。		但是也不是所有时候都是如此，比如在设定物品的模型文件的时候，resourcePath就不需要打那么多了，只需要<code>new ResourceLocation(modid, itemid)</code>就可以了，比如<code>new ResourceLocation("minecraft", "apple")</code>。所以，作者的建议是，如果是你自定义的渲染操作，你按照“路径为<code>"assets/" + resourceDomain + "/" + resourcePath</code>”的规则，是没问题的；但是如果你要用Minecraft或Forge内置的某些方法，其中要传入一个ResourceLocation对象，那你就要小心了，还是点进去看看Minecraft或Forge的代码到底是怎么处理这个ResourceLocation的吧。

	那么，那个只有一个resourceName的构造方法是怎么回事呢？再举个例子，我可以这样：		那么，那个只有一个resourceName的构造方法是怎么回事呢？再举个例子，我可以这样：
第54行：		第54行：

	那么<code>@SideOnly(Side.SERVER)</code>呢？和你想的是一样的，但是——在正常情况下，不要用这个修饰任何东西。前文说了，<code>@SideOnly(Side.CLIENT)</code>用于修饰那些负责渲染、播放音效的类、方法，而又说了，“逻辑客户端（Render Thread）主要用于处理和视觉、听觉有关的效果，还负责处理玩家的键鼠输入等”。因为'''物理服务端没有逻辑客户端线程'''，所以<code>@SideOnly(Side.CLIENT)</code>实际上也起到了“把代码的执行限定在逻辑客户端”的作用。可问题是，物理客户端也会有逻辑服务端，比如有个萌新Modder觉得“逻辑服务端掌管的是游戏逻辑的进行”，给某个负责游戏逻辑进行的方法打了<code>@SideOnly(Side.SERVER)</code>，那糟了，装了你的模组就没法进行单人游戏了——因为两个物理端都有逻辑服务端。		那么<code>@SideOnly(Side.SERVER)</code>呢？和你想的是一样的，但是——在正常情况下，不要用这个修饰任何东西。前文说了，<code>@SideOnly(Side.CLIENT)</code>用于修饰那些负责渲染、播放音效的类、方法，而又说了，“逻辑客户端（Render Thread）主要用于处理和视觉、听觉有关的效果，还负责处理玩家的键鼠输入等”。因为'''物理服务端没有逻辑客户端线程'''，所以<code>@SideOnly(Side.CLIENT)</code>实际上也起到了“把代码的执行限定在逻辑客户端”的作用。可问题是，物理客户端也会有逻辑服务端，比如有个萌新Modder觉得“逻辑服务端掌管的是游戏逻辑的进行”，给某个负责游戏逻辑进行的方法打了<code>@SideOnly(Side.SERVER)</code>，那糟了，装了你的模组就没法进行单人游戏了——因为两个物理端都有逻辑服务端。

	可能会有读者觉得，笔者讲的太抽象了。没事，等读者有了一定的开发经验，就懂了。反正记住：什么情况下，都别用<code>@SideOnly(Side.SERVER)</code>。我们是在写模组，不是在写服务器插件。

	那么这个注解，意义何在呢？答案是减少性能开销，比如，你在物理服务端调用渲染代码也没卵用，毕竟物理服务端是以命令行的形式体现的，你渲染给谁看呢？可能又有人问了：要减少性能开销，那么针对两个物理端分别写不同的代码不就好了？这也太麻烦了。所以，这就是@SideOnly的存在的意义——让同一个模组在不同的物理端上运行时，共享同一套代码。		那么这个注解，意义何在呢？答案是减少性能开销，比如，你在物理服务端调用渲染代码也没卵用，毕竟物理服务端是以命令行的形式体现的，你渲染给谁看呢？可能又有人问了：要减少性能开销，那么针对两个物理端分别写不同的代码不就好了？这也太麻烦了。所以，这就是@SideOnly的存在的意义——让同一个模组在不同的物理端上运行时，共享同一套代码。
第62行：		第60行：
	注册表是什么？那要先从“注册项”这个概念说起。		注册表是什么？那要先从“注册项”这个概念说起。

	Minecraft原版中有着各种游戏元素，如物品、方块、状态效果、实体等等，这些游戏要素的很多行为（包括方块的“长按左键挖掘”这种通用行为，以及实体的“靠近玩家会尝试爆炸”这种仅在苦力怕这种生物上会体现的特殊行为），显然，是必须要在游戏初始化时完成设置的——不然游戏初始化有什么意义？干脆就在遇到某个游戏要素的时候读取相关逻辑不就好了？——显然，这种设计是很不好的。		Minecraft原版中有着各种游戏元素，如物品、方块、状态效果、实体等等，游戏需要以某种方式知道总共都有什么游戏元素，以方便管理。

	~~所以在这种情况下，显然就需要一种东西来统筹这些游戏元素的逻辑的初始化，被统筹的游戏元素都是'''注册项'''，而统筹者则是'''注册表''~~'。一般而言，注册项会在FMLPreInitialization阶段被注册。想想看：如果没有注册表，就拿物品（Item）这一注册项举例，MC如何能获取到你想要添加到游戏中的所有物品呢？难不成还要用黑科技读取你的项目中的所有继承了Item类的类，再用<code>Class#newInstance</code>手动构造实例？或者自动检索所有Item的实例？这根本不可行。所以注册表应运而生。		所以在这种情况下，注册表应运而生'。一般而言，注册项会在FMLPreInitialization阶段被注册。想想看：如果没有注册表，就拿物品（Item）这一注册项举例，MC如何能获取到你想要添加到游戏中的所有物品呢？难不成还要用黑科技读取你的项目中的所有继承了Item类的类，再用<code>Class#newInstance</code>手动构造实例？或者自动检索所有Item的实例？这根本不可行。所以注册表应运而生。

	Minecraft原版就有一套注册表系统，不过它的实现太过于丑陋，也根本就存在很多问题——如，你会发现使用它注册注册项时，你还需要显式指定每个实例的数字ID。那么请问你如何保证你的模组的注册项的数字ID不会和其他模组的发生冲突呢？实际上Minecraft在1.13也弃用了这种注册模式。		Minecraft原版就有一套注册表系统，不过它的实现太过于丑陋，也根本就存在很多问题——如，你会发现使用它注册注册项时，你还需要显式指定每个实例的数字ID。那么请问你如何保证你的模组的注册项的数字ID不会和其他模组的发生冲突呢？实际上Minecraft在1.13也弃用了这种注册模式。
第72行：		第70行：
	所有注册项的类都实现了IForgeRegistryEntry<V>这一接口，这个接口主要规定了关于注册名的一些规范，实际上这个接口有个静态内部类：Impl<T> implements IForgeRegistryEntry<T>，所以实际上所有注册项的类是继承了这个类，这个类提供了IForgeRegistryEntry<V>的默认实现。也就是说，理论上你可以通过T extends IForgeRegistryEntry.Impl<T>来设定：可以用Forge的注册表系统给你的某个自定义的游戏元素进行注册，不过一般没必要这么做。		所有注册项的类都实现了IForgeRegistryEntry<V>这一接口，这个接口主要规定了关于注册名的一些规范，实际上这个接口有个静态内部类：Impl<T> implements IForgeRegistryEntry<T>，所以实际上所有注册项的类是继承了这个类，这个类提供了IForgeRegistryEntry<V>的默认实现。也就是说，理论上你可以通过T extends IForgeRegistryEntry.Impl<T>来设定：可以用Forge的注册表系统给你的某个自定义的游戏元素进行注册，不过一般没必要这么做。

	使用原版的注册表时，没有“注册名”这一说——但是我们用的是Forge的注册表，所以必须在注册对象前，设定该对象的注册名：通过setRegistryName这个方法设定。这个方法可以接受一个ResourceLocation，但也可以接受这样两种形参列表：<code>(String name)</code>和<code>(String modid, String name)</code>，用法可以类比ResourceLocation的那两个构造方法，笔者这里就不细说了。如果你尝试注册未设定注册名的注册项对象（即注册名为null），则肯定会崩游戏，抛NullPointerException。		使用原版的注册表时，没有“注册名”这一说——但是我们用的是Forge的注册表，所以必须在注册对象前，设定该对象的注册名：通过setRegistryName这个方法设定。这个方法可以接受一个ResourceLocation，但也可以接受这样两种形参列表：<code>(String name)</code>和<code>(String modid, String name)</code>，用法可以类比ResourceLocation的那两个构造方法，作者这里就不细说了。如果你尝试注册未设定注册名的注册项对象（即注册名为null），则肯定会崩游戏，抛NullPointerException。
	=== @ObjectHolder ===		=== @ObjectHolder ===
	利用<code>@GameRegistry.ObjectHolder</code>这个注解，我们可以自动给某个类型为<T extends IForgeRegistryEntry<T>>的变量赋值。		利用<code>@GameRegistry.ObjectHolder</code>这个注解，我们可以自动给某个类型为<T extends IForgeRegistryEntry<T>>的变量赋值。

用户:MashKJo/1.12.2模组开发教程/绪论

MashKJo — Thu, 23 Apr 2026 08:18:27 GMT

@@ 第3行： / 第3行： @@
 === 叠甲 ===
-笔者不保证、也绝对不敢说这篇教程里的所有内容都是准确无误的。
+作者不保证、也绝对不敢说这篇教程里的所有内容都是准确无误的。
 == 对读者的要求 ==
@@ 第10行： / 第10行： @@
 * 对于安装Forge Mod的操作足够了解，且拥有较丰富的模组游玩经验
 * 对面向对象编程思想、Java基本语法、Java的部分基础类库有着足够的了解

用户:MashKJo/1.12.2模组开发教程/1.构建开发环境

MashKJo — Thu, 23 Apr 2026 08:16:34 GMT

←上一版本		2026年4月23日 (四) 16:16的版本
（未显示同一用户的2个中间版本）
第1行：		第1行：
	这一步，可以说是最难的一步。		这一步，可以说是最难的一步。

	~~不要以为笔者在开玩笑，实际上很多潜在的Modder都被这一步拦住了。~~		不要以为作者在开玩笑，实际上很多潜在的Modder都被这一步拦住了。

	== 构建步骤 ==		== 构建步骤 ==
第33行：		第33行：
	所以，现在要构建1.12.2的环境，常见的方法是：使用镜像下载源，或使用构建好的离线包。		所以，现在要构建1.12.2的环境，常见的方法是：使用镜像下载源，或使用构建好的离线包。

	~~使用镜像下载源，需要更改<code>gradle-wrapper.properties</code>和<code>build.gradle</code>中的链接。其中，<code>build.gradle</code>文件中，应该有这样一个部分：~~		作者建议直接下载构建好的离线包，当然下载完之后还是要在命令行中输入一下相关的构建命令。

	~~buildscript {~~
	~~repositories {~~
	~~maven { url = 'https://maven.minecraftforge.net/' }~~
	~~mavenCentral()~~
	}
	~~dependencies {~~
	~~classpath 'net.minecraftforge.gradle:ForgeGradle:3.+'~~
	}
	}

	~~把其中的链接替换成你要用的镜像源链接即可。~~

	~~但笔者建议直接下载构建好的离线包，当然下载完之后还是要在命令行中输入一下相关的构建命令。~~


	== 修改build.gradle和Mod元数据 ==		== 修改build.gradle和Mod元数据 ==
第117行：		第102行：
	然后你就可以在路径<code>build/libs</code>下看到一个.jar文件，这就是构建好的Mod了。		然后你就可以在路径<code>build/libs</code>下看到一个.jar文件，这就是构建好的Mod了。

	== ~~在IDE中执行Gradle Task~~ ==		== runClient报错提示NPE ==
	上述Gradle Task都是ForgeGradle这一Gradle插件提供的。实际上，你不需要非要在命令行中执行这些task，上述的三种IDE：IDEA、Eclipse和VSCode都有Gradle支持插件，因此理论上如果你使用这三种IDE之一，是可以直接在IDE中执行task的。但实际上VSCode似乎还需要经过手动的配置才可以使用此项功能。		如果你不是用的离线包，而是自己构建的话，很大概率会出现这个问题，下载一下源码就行。