我的世界Java版1.21.4的Fabric模组开发教程(二)创建物品

这是适用于Minecraft Java版1.21.4的Fabric模组开发系列教程专栏第二章——创建物品。想要阅读其他内容请查看或订阅上面的专栏。物品(Items)指的是可以被玩家和其他实体拾起并使用的元素。想要在Minecraft中添加自己的物品通常需要完成下面的步骤创建物品类在游戏注册表中注册物品为物品创建模型文件为物品创建模型描述文件在翻译文件中添加物品翻译字段在本章我们会以狗粑粑(dog_poo)为例详细讲解创建这个物品的过程。除此之外还可以对物品进行其他设置在下文也会提到。写在前面从本章开始将正式开始学习Fabric模组开发相关知识。本节将展示部分需要使用到的链接和一些需要提前告知的信息。链接开发者指南 | Fabric文档最新版的Fabric开发文档。Fabric 模组教程 [Fabric Wiki]适用于旧版游戏的Fabric开发文档。fabric-docs/reference/latest/ at main · FabricMC/fabric-docsFabric官方模组代码示例。说明本系列教程按照最新版Fabric开发文档的节奏编写部分内容相同但是要比官方文档的讲解更加详细同时规避了官方文档中的错误即使是最新版的Fabric开发文档部分文章的中文版本依然缺乏更新部分代码无法显示。代码写法仍需参考github上的示例代码请勿直接在网页上保存游戏纹理文件因为网页上的图片并不符合纹理文件的大小要求下载纹理文件请参考最新版的Fabric开发文档或联系作者使用AI解决问题时不能完全相信AI提供的代码。Fabric和Minecraft API更新速度很快AI给出的部分写法可能已经过时在网络上搜索问题的解决方案时要注意模组加载器和游戏版本是否与本文相一致同一功能不同版本的代码写法有很大出入旧版本代码写法和旧版本的项目结构在新版本环境中不生效。创建物品类想要创建自定义物品最好的解决方案是先创建一个属于这个物品的物品类。不过不使用物品类也可以创建自定义物品。1.首先在main模块的com.example.test包中创建item目录用于存放所有物品类。右键点击com.example.test目录选择“新建→软件包”输入“item”然后按下回车创建目录2.右键item目录选择“新建→Java类”输入“DogPoo”然后按下回车创建Java类publicclassDogPoo{}在本章和接下来的章节中所有代码中的package和import声明都将省略。物品类ItemItem是Minecraft原生API中的核心类之一其对象指的是所有玩家和其他实体可以使用的物品。通常对于没有自定义行为的物品继承Item类后可以直接调用其构造方法对于需要有自定义行为的物品此时要继承Item的子类如ArmorItem等这可以给对应的物品类提供更多的功能。3.使DogPoo继承Item类并在其中调用Item类的构造方法publicclassDogPooextendsItem{publicDogPoo(Settingssettings){super(settings);//调用父类的构造方法}}这样一个物品类就创建完成了。在游戏注册表中注册物品现在我们可以在游戏物品注册表中注册自己的物品。不过在开始前需要了解一些概念。注册表接口RegistryRegistry接口用于注册各种游戏内组件。游戏内几乎所有内容——方块、物品和实体——都会在注册表中注册。注册表会分配一个唯一的标识符给每一个注册表项。因此注册表在游戏中起着非常重要的作用某些应该注册的对象但并没有在注册表中注册通常会导致错误甚至崩溃。使用接口中的register()方法将物品注册到注册表staticV,TextendsVTregister(RegistryVregistry,RegistryKeyVkey,Tentry){((MutableRegistry)registry).add(key,(V)entry,RegistryEntryInfo.DEFAULT);returnentry;}其中的参数为RegistryV registry目标注册表类型。一般传递Registries.ITEM物品或Registries.Block方块等RegistryKeyV key唯一标识符。此处传递一个由Identifier类中静态方法生成的注册键T entry任意类型对象一般指的是要注册物品的实例。按照官方相关文档所述在创建普通物品时不会直接调用这个方法。因此这个方法即将被封装。标识符类IdentifierIdentifier类用来为物品添加标识符也被称为命名空间ID。标识符使用命名空间和路径的组合来标识物品。标识符的格式为namespace:path如果省略命名空间和冒号则命名空间默认为“minecraft”。标识符有着非常严格的格式规范除了创建的标识符不能和已经存在的标识符重复以外其中的字符只能包含ASCII小写字母([a-z])只能包含ASCII数字([0-9])仅接受的几个特殊字符_(下划线).(点)-(连字符)不能使用大写字母通常可以使用Identifier类中的静态方法of()来创建一个标识符publicstaticIdentifierof(Stringnamespace,Stringpath){returnofValidated(namespace,path);}其中的两个参数分别代表物品的命名空间和路径类型均为字符串。当传入无效值时将抛出InvalidIdentifierException。4.在开始封装Registry.register()方法前需要创建一个用于存放静态常量的类方便后续开发。首先在com.example.test目录中创建一个名为utils软件包作为工具类的存放位置。在utils包中创建FabricDocsReference类(可以使用其他自己喜欢的名字)publicclassFabricDocsReference{publicfinalstaticStringMOD_IDtest;}在其中声明当前模组Id为静态常量在将来会有更多静态内容添加到这个类中。5.按照官方文档的写法需要封装Registry.register()方法。在utils包中创建ModItems类在类中创建register()方法封装Registry.register()publicstaticItemregister(Stringname,FunctionItem.Settings,ItemitemFactory,Item.Settingssettings){// Create the item key.RegistryKeyItemitemKeyRegistryKey.of(RegistryKeys.ITEM,Identifier.of(FabricDocsReference.MOD_ID,name));// Create the item instance.ItemitemitemFactory.apply(settings.registryKey(itemKey));// Register the item.Registry.register(Registries.ITEM,itemKey,item);returnitem;}代码摘自官方文档。其中的参数如下String name物品名即标识符中的路径FunctionItem.Settings, Item itemFactory物品对象与物品默认配置对象的函数式Item.Settings settings配置对象。首先使用模组Id和name(物品路径)创建物品注册键RegistyKey然后创建默认配置对象Item.settings接着确定注册物品的类型是物品Registries.ITEM或其他类型最后使用注册键RegistyKey和默认配置对象Item.settings在游戏注册表中注册物品在这个项目中所有Item对象的命名空间都是FabricDocReference.MOD_ID即模组Id。物品配置内部类Item.SettingsItem.Settings类在Item类内部它可以为需要注册的物品配置诸多属性和行为例如物品堆叠的最大计数、物品是否可以食用和物品的最大伤害等是创建物品过程中必不可少的参数之一。6.在入口点类Test中注册物品dog_poo入口点通常一个模组通常包含至少一个入口点类类名与模组Id一致。在main模块中这个类实现了ModInitializer接口。此外入口点类中必须实现onInitialize()方法。当游戏启动时onInitialize()方法将被执行同时在类中的静态常量也将被初始化。打开Test类在onInitialize()方法前使用封装后的register()方法声明并初始化物品dog_poo为静态常量publicstaticfinalItemDOG_POOModItems.register(dog_poo,DogPoo::new,newItem.Settings().maxCount(63));Item.Settings类对象提供了maxCount()方法以设置物品的最大堆叠数量默认值为64现在将物品在游戏注册表中注册的代码逻辑已经完成。为自定义物品创建纹理、模型文件和模型描述文件现在可以开始准备物品的纹理与其对应的模型JSON文件了。创建纹理纹理指的就是物品在物品栏中显示的图像。我们使用这个图片作为dog_poo的纹理纹理图片也有一定的格式要求包括大小必须为16x16或32x32文件格式必须为.png文件名必须与物品路径一致。7.在项目中的assets.test目录中创建textures目录用于存放项目中的所有纹理文件然后在其中创建item目录用于存放物品的纹理文件最后将纹理图片移动到items目录中。文件名与物品路径一致。创建模型描述文件模型描述文件也称之为模型映射文件用于指向物品模型文件位置与类型类型为JSON。自1.21.4版本后创建自定义物品的过程中需要创建模型描述文件8.在assets.test目录中创建items目录用于存放项目中所有的模型描述文件然后在items目录中创建dog_poo.json以dog_poo为例模型描述文件的写法如下{model:{type:minecraft:model,model:test:item/dog_poo}}其中model代表对模型的引用属性其中包含type模型的类型。 对于大多数物品应该为minecraft:modelmodel模型的标识符。其中test为模组Iditem/dog_poo指向模型文件的位置。创建模型文件模型文件用于指向物品纹理图的所在位置与模型映射文件类似类型同样为JSON。9.在assets.test目录中创建models目录用于存放项目中所有的模型文件然后再创建item目录用于存放物品的模型文件最后在item目录中创建dog_poo.json以dog_poo为例模型文件的写法如下{parent:minecraft:item/generated,textures:{layer0:test:item/dog_poo}}其中parent模型要继承的父模型。 在这个例子中是item/generated模型textures指定模型对应物品的纹理文件位置。layer0键是模型使用的纹理。现在物品的纹理、模型文件和模型描述文件已经创建完毕。创建语言文件为了防止自定义物品在游戏中直接显示标识符如test:dog_poo可以创建语言文件根据不同的语言为标识符提供对应的文本这就是对应一般程序开发项目中的i18n(internationalization)功能即国际化。当游戏的语言为中文时游戏中的物品、界面、生物等元素的文本将按照zh-cn.json文件中设置的字段显示中文通常这个文件存放在lang目录中如果游戏的语言为英文则文件名为en-us.json。因此当玩家在游戏中修改语言时对应的语言文件中的字段就会在游戏中生效当然语言文件可以有多个以适配不同的语言设置来实现模组项目的国际化需求10.在assets.test目录中创建lang目录用于存放语言文件。在lang目录中创建zh-cn.json文件在语言文件中添加一对键值{item.test.dog_poo:狗粑粑}将test:dog_poo翻译为“狗粑粑”。其中item是物品类型test.dog_poo是物品的标识符(此时使用.而不是:隔开)物品类型与标识符两者之间使用.分割至此一个基本的自定义物品已经创建完成。在游戏中可以使用/give命令获得该物品。将自定义物品添加到物品组在创造模式下为了避免始终使用命令获取物品我们可以将自定义物品加入到指定物品组中。物品组事件类ItemGroupEventsItemGroupEvents一个事件系统专门用于为即将修改的物品组创建修改事件。一般使用ItemGroupEvents.modifyEntiesEvent()方法来确定物品组publicstaticEventModifyEntriesmodifyEntriesEvent(RegistryKeyItemGroupregistryKey){returnItemGroupEventsImpl.getOrCreateModifyEntriesEvent(registryKey);}方法需要传递一个物品组注册键。需要传递ItemGroups类中已经预定义的注册键对象例如ItemGroups.INGREDIENTS指的是创造模式中“原材料”物品组ItemGroupEvents.modifyEntiesEvent()方法返回一个Event对象即物品组修改事件对象。还需要调用Event对象的register()方法为该事件注册监听器publicabstractvoidregister(Tlistener);方法传递一个事件监听器。此处传递的监听器类型为ItemGroupEvents.ModifyEntries接口。物品修改内部函数式接口ItemGroupEvents.ModifyEntries这个接口在ItemGroupEvents类内部声明是注册物品组修改事件监听器时所使用的事件回调接口。用于修改特定物品组中的物品其中只有一个modifyEntries()方法。接口外部由FunctionalInterface注解修饰这代表调用此接口时可以简写为Lambda表达式publicfinalclassItemGroupEvents{//...FunctionalInterfacepublicinterfaceModifyEntries{voidmodifyEntries(FabricItemGroupEntriesentries);}}modifyEntries()方法中提供了当前物品组的物品对象FabricItemGroupEntries。Fabric物品组内容类FabricItemGroupEntriesFabricItemGroupEntries是 Fabric API 提供的一个关键类它作为物品组内容修改的接口允许物品组事件对象修改物品组中的物品FabricItemGroupEntries类实现了ItemGroup.Entries接口并重写了其内部方法add()defaultvoidadd(ItemConvertibleitem){this.add(newItemStack(item),ItemGroup.StackVisibility.PARENT_AND_SEARCH_TABS);}其中传递的参数是ItemConvertible对象。此处可以直接理解为传递的是自定义物品的实例。11.在入口点类中的onInitialize()方法中将dog_poo添加到“原材料”物品组中ItemGroupEvents.modifyEntriesEvent(ItemGroups.INGREDIENTS).register((itemGroup)-itemGroup.add(DOG_POO));调用modifyEntriesEvent方法确定要把物品添加到的物品组方法传递一个物品组注册键对象ItemGroups.INGREDIENTS然后调用register()方法方法中传递FabricItemGroupEntries对象的表达式其中再调用add()方法将“狗粑粑”添加到指定物品组中。12.打开游戏创建一个新世界模式为创造模式。进入世界后按E打开物品栏在“原材料”物品组最后的位置可以看到新加入的物品。到此为止一个基本的物品就创建完成了。对于一个没有复杂的自定义行为和属性的物品可以采用以上的步骤来创建对于其他带有复杂行为的物品还请参考下文与后面的数据组件等章节中的相关内容来完成创建。为物品添加合成配方在此小节我们会为“狗粑粑”添加一套合成配方。默认使用工作台制作定义合成配方为如上图三个“橡木栅栏”居中排列。一般合成配方的定义需要创建一个JSON文件。而根据官方文档所述可以使用“配方 JSON 生成器”网站来生成这个JSON文件请访问Crafting1.首先在右侧找到“橡木栅栏”然后拖动到左侧工作台九宫格中2.完成后找到左侧的“options”部分其中Minecraft VersionMinecraft版本选择“Java 1.21.4”shapeless?是否不使用形状限制大概的意思是是否完全按照摆放的形状来生成对应的物品。如果勾选则代表不需要对配方添加形状限制换言之三个“橡木栅栏”以任意形状在工作台中摆放都可以合成“狗粑粑”即使是2x2的玩家工作台。此处不勾选2x2 Grid确定配方是否为2x2网格的配方。此处不勾选Exactly where placed?是否限制物品摆放的位置如果勾选则必须将三个“橡木栅栏”放在中间的一列才能制作出“狗粑粑”反之如果不勾选则代表在任意一列摆放三个“橡木栅栏”都能制作出“狗粑粑”。此处不勾选Output Recipe输出文件的文件名填写“dog_poo”Group物品在工作台中所属物品组暂时可以为空。3.此时下方已经生成JSON点击“Download JSON file”下载JSON文件4.在main模块下创建data/test/recipe目录将下载好的JSON文件复制进去5.打开dog_poo.json在配置对象result中添加一条数据键为id值为物品的标识符。代表配方可以制作出的物品...result:{id:test:dog_poo}值得注意的是Crafting官方文档(https://github.com/skylinerw/guides/blob/master/java/recipes.md)的result配置对象中键写成了item。这是旧版本的写法在1.21.4版本中必须改为id。6.由于配方JSON属于数据生成式文件需要启用项目的数据生成设置。找到build.gradle配置文件在文件结尾添加数据生成配置fabricApi{configureDataGeneration(){clienttrue}}7.打开“构建”窗格点击“执行Gradle任务”。执行/gradlew runDatagen命令可以看到main模块中生成了generated目录;8.将data目录移动到generated目录中;9.打开游戏测试配方已经生效。自定义物品提示创建完物品后可以给物品添加物品提示。当鼠标移动到物品上时会显示物品的名称和物品提示如下图。通常我们在继承了Item类的物品类中重写appendTooltip()方法来为物品添加工具提示publicvoidappendTooltip(ItemStackstack,TooltipContextcontext,ListTexttooltip,TooltipTypetype){}这个方法默认为空。添加物品提示要使用ListText tooltip参数的add()方法将文字加入到工具提示列表中。add()方法传递一个Text对象。可变文本类MutableTextMutableText类是Text的子类用于处理游戏内的文本渲染与本地化。使用其静态方法literal()可以直接将普通字符串字面量转换为可变文本并添加到游戏当中staticMutableTextliteral(Stringstring){returnMutableText.of(PlainTextContent.of(string));}方法传递一个字符串即需要转换的字符串。此外还可以使用formatted()方法设置文字颜色publicMutableTextformatted(Formattingformatting){this.setStyle(this.getStyle().withFormatting(formatting));returnthis;}方法传递一个Formatting枚举类中的枚举常量例如Formatting.GOLD指的是金色Formatting.BLUE指的是蓝色。在DogPoo类中重写appendTooltip()方法publicvoidappendTooltip(ItemStackstack,TooltipContextcontext,ListTexttooltip,TooltipTypetype){tooltip.add(Text.literal(这可是狗粑粑啊).formatted(Formatting.GOLD));}使用literal()方法将字符串字面量转换为可变文本然后使用formatted()方法设置文字颜色为金色。打开游戏可以在物品下面看到金色的工具提示文本。配置物品可堆肥或作燃料还可以将“狗粑粑”作为堆肥物品或燃料这与“狗粑粑”在现实世界对应的功能相符合。物品堆肥列表及其概率注册接口CompostingChanceRegistryCompostingChanceRegistry是Fabric API提供的工具类用于注册可堆肥物品及其堆肥成功率可以将自定义物品添加到堆肥桶的可堆肥物品列表中使物品能够像原版材料一样被转化为骨粉。需要使用接口CompostingChanceRegistry的实例CompostingChanceRegistry.INSTANCE的add()方法将物品添加到可堆肥列表中并设置其成功概率。publicvoidadd(ItemConvertibleitem,Floatvalue){ComposterBlock.ITEM_TO_LEVEL_INCREASE_CHANCE.put(item.asItem(),value);}CompostingChanceRegistry.INSTANCE由接口CompostingChanceRegistry的实现类CompostingChanceRegistryImpl中的构造方法实例化。其中的add()方法参数有ItemConvertible item要加入可堆肥列表的物品实例Float value堆肥成功的概率取值范围在0.0-1.0之间。例如0.3代表堆肥成功率为30%。在入口点类中的onInitialize方法中为物品添加可堆肥功能OverridepublicvoidonInitialize(){//...CompostingChanceRegistry.INSTANCE.add(DOG_POO,0.5f);//...}设置其成功概率为50%。完成后启动游戏测试功能已经实现。燃料注册事件接口FuelRegistryEventsFuelRegistryEvents是一个事件系统用于创建一个修改或扩展燃料注册表的事件。通常使用接口中的BUILD属性创建一个事件。按照源代码Javadoc所述该事件在游戏燃料注册表创建之后和EXCLUSION事件执行之前调用。EXCLUSION事件用于排除燃料注册表中的特定物品。事件BUILD的类型为FuelRegistryEvents.BuildCallback。燃料注册事件BUILD回调的内部函数式接口FuelRegistryEvents.BuildCallback这个接口在FuelRegistryEvents内部声明用于处理BUILD事件。接口外部带有FunctionalInterface注解这代表调用此接口时可以简写为Lambda表达式接口内部中只有一个方法build()publicinterfaceFuelRegistryEvents{//...FunctionalInterfaceinterfaceBuildCallback{voidbuild(FuelRegistry.Builderbuilder,Contextcontext);}}其中提供了两个参数FuelRegistry.Builder builder燃料注册表项构造器用于在燃料注册表中创建新的注册项Context contextBUILD事件上下文。燃料注册表构造器内部类FuelRegistry.BuilderFuelRegistry.Builder在FuelRegistry类内部声明用于构造自定义燃料物品的注册项并将其在燃料注册表中注册。通常调用其中的add()方法来完成燃料物品的注册publicBuilderadd(TagKeyItemtag,intvalue){...}方法体已省略其中的两个参数为TagKeyItem tag自定义物品的实例对象int value燃烧时长单位游戏刻1秒20游戏刻。例如30秒为600(30 * 20)游戏刻。在入口点类的onInitialize方法中将物品dog_poo添加到燃料注册表中配置燃烧时长为30秒OverridepublicvoidonInitialize(){//...FuelRegistryEvents.BUILD.register((builder,context)-builder.add(DOG_POO,30*20));//...}使用FuelRegistryEvents类中BUILD事件对象的register()方法其中传递一个FuelRegistryEvents.BuildCallback的函数表达式调用FuelRegistry.Builder对象的add()方法设置可燃烧的物品对象为DOG_POO以及燃烧时长为600秒启动游戏在熔炉中已经可以使用“狗粑粑”作为燃料。本章小结本章阐述了创建物品的基本步骤与其他相关功能的写法。若想添加更多类型的物品如食物、武器和盔甲等请参考后续章节。感谢各位的阅读有兴趣可以订阅此专栏