Fabric Wiki

User Tools

Site Tools

Trace:
tutorial:items

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
tutorial:items [2024/10/27 14:07] – solidblocktutorial:items [2025/04/01 08:57] (current) – [Adding model, texture and model mapping] solidblock
Line 7: Line 7:
 Adding a basic item is one of the first steps in modding. You're going to need to create an ''<yarn class_1792>'' object, register it, and give it a texture. To add additional behavior to the item you will need a custom <yarn class_1792> class. In this tutorial and all future ones, the “''tutorial''” namespace is used as a placeholder. If you have a separate mod id, feel free to use it instead. Adding a basic item is one of the first steps in modding. You're going to need to create an ''<yarn class_1792>'' object, register it, and give it a texture. To add additional behavior to the item you will need a custom <yarn class_1792> class. In this tutorial and all future ones, the “''tutorial''” namespace is used as a placeholder. If you have a separate mod id, feel free to use it instead.
  
-===== Create an Item instance =====+===== Create an Item instance (before 1.21.2) =====
  
 :!: If you're in version 1.21.2 or above, please directly read [[#Creating Items in 1.21.2+]]. :!: If you're in version 1.21.2 or above, please directly read [[#Creating Items in 1.21.2+]].
Line 25: Line 25:
 </yarncode> </yarncode>
  
-===== Register the item =====+===== Register the item (before 1.21.2) =====
  
 We've create a basic item, but it still does not exist in Minecraft, because it has not been registered. In Minecraft, almost everything has an registry, and items are no exceptions. We've create a basic item, but it still does not exist in Minecraft, because it has not been registered. In Minecraft, almost everything has an registry, and items are no exceptions.
  
-You'll use the vanilla registry system for registering new content. The basic syntax is ''<yarn class_2378>.<yarn method_10230>(Registry Type, <yarn class_2960>, Content)''. Registry types are stored as static fields in the ''<yarn class_7923>'' or ''<yarn class_2378>'' class, and the identifier is what labels your content. Content is an instance of whatever you're adding. Specifically for item, the syntax is ''<yarn class_2378>#<yarn method_10230>(<yarn class_7923>.<yarn field_41178>, <yarn class_2960>, <yarn class_1792>)''. This can be called anywhere as long as it occurs during initialization. The method itself also returns the registered content itself.+You'll use the vanilla registry system for registering new content. The basic syntax is ''<yarn class_2378>.//<yarn method_10230>//(Registry Type, <yarn class_2960>, Content)''. Registry types are stored as static fields in the ''<yarn class_7923>'' or ''<yarn class_2378>'' class, and the identifier is what labels your content. Content is an instance of whatever you're adding. Specifically for item, the syntax is ''<yarn class_2378>.//<yarn method_10230>//(<yarn class_7923>.<yarn field_41178>, <yarn class_2960>, <yarn class_1792>)''. This can be called anywhere as long as it occurs during initialization. The method itself also returns the registered content itself.
  
 For versions since 1.21, an ''Identifier'' is created through ''%%Identifier.of("namespace", "path")%%''. For versions below 1.21, it is created through ''%%new Identifier("namespace", "path")%%'' or ''%%new Identifier("namespace:path")%%''. It will fail if the namespace or path contains illegal characters. For versions since 1.21, an ''Identifier'' is created through ''%%Identifier.of("namespace", "path")%%''. For versions below 1.21, it is created through ''%%new Identifier("namespace", "path")%%'' or ''%%new Identifier("namespace:path")%%''. It will fail if the namespace or path contains illegal characters.
Line 64: Line 64:
 </yarncode> </yarncode>
  
-===== Best practice of registering items =====+===== Best practice of registering items (before 1.21.2) =====
 In the code above, you simply created //one// item. However, it is not convenient if you have //many// items in your mod, as you need to register and create an ''Identifier'' instance each time. Therefore, we can create a specific class to store item objects, such as ''ModItems'' or ''TutorialItems'', and write a simple ''register'' method to conveniently register items. This is quite common in actual mod development. You may also check vanilla ''Items'' class to see how Minecraft completes it in a similar way. In the code above, you simply created //one// item. However, it is not convenient if you have //many// items in your mod, as you need to register and create an ''Identifier'' instance each time. Therefore, we can create a specific class to store item objects, such as ''ModItems'' or ''TutorialItems'', and write a simple ''register'' method to conveniently register items. This is quite common in actual mod development. You may also check vanilla ''Items'' class to see how Minecraft completes it in a similar way.
  
Line 128: Line 128:
 In the method ''Items.register'', the registry key will be written in the ''settings'' first, and then use that ''settings'' to create the item. In the method ''Items.register'', the registry key will be written in the ''settings'' first, and then use that ''settings'' to create the item.
  
-===== Adding model and textures =====+===== Adding model, texture and model definition =====
  
 If you registered your item properly in the first step, you can successfully get your item by typing command ''/give @s tutorial:custom_item''. You will find it has missing texture, and Minecraft will complain about a missing texture file in a fashion similar to this: If you registered your item properly in the first step, you can successfully get your item by typing command ''/give @s tutorial:custom_item''. You will find it has missing texture, and Minecraft will complain about a missing texture file in a fashion similar to this:
Line 134: Line 134:
     [Server-Worker-1/WARN]: Unable to load model: 'tutorial:custom_item#inventory' referenced from: tutorial:custom_item#inventory: java.io.FileNotFoundException: tutorial:models/item/custom_item.json     [Server-Worker-1/WARN]: Unable to load model: 'tutorial:custom_item#inventory' referenced from: tutorial:custom_item#inventory: java.io.FileNotFoundException: tutorial:models/item/custom_item.json
  
-That's because we haven't provided the item with textures and models. Therefore, you need to define the item model json and provide a texture image. You're going to need to add these to your resource directory. The direct path of each is:+That's because we haven't provided the item with **textures**, **baked models** (we call them "models" for short) and **model definition** (also called model mapping). Those files are located in the following places respectively:
  
   * Item model: ''.../resources/assets/tutorial/models/item/custom_item.json''   * Item model: ''.../resources/assets/tutorial/models/item/custom_item.json''
   * Item texture: ''.../resources/assets/tutorial/textures/item/custom_item.png''   * Item texture: ''.../resources/assets/tutorial/textures/item/custom_item.png''
 +  * Item model definition (since 1.21.4): ''.../resources/assets/tutorial/items/custom_item.json''
  
 Our example texture can be found [[https://i.imgur.com/CqLSMEQ.png|here]]. Our example texture can be found [[https://i.imgur.com/CqLSMEQ.png|here]].
  
 A basic item model template is: A basic item model template is:
-<code JavaScript>+<code JavaScript /resources/assets/tutorial/models/item/custom_item.json>
 { {
   "parent": "item/generated",   "parent": "item/generated",
Line 151: Line 152:
 </code> </code>
 The ''parent'' of your item model changes how it's rendered in the hand and comes in useful for things like block items in the inventory. ''item/generated'' is used for many simple items. ''item/handheld'' is used for tools that are held from the bottom left of the texture. In the json, ''textures/layer0'' is the location of your image file. The ''parent'' of your item model changes how it's rendered in the hand and comes in useful for things like block items in the inventory. ''item/generated'' is used for many simple items. ''item/handheld'' is used for tools that are held from the bottom left of the texture. In the json, ''textures/layer0'' is the location of your image file.
 +
 +An item model definition is also needed since 1.21.4 (not needed before 1.21.4), of which the content may be:
 +<code javascript /resources/assets/tutorial/items/custom_item.json>
 +{
 +  "model": {
 +    "type": "model",
 +    "model": "tutorial:item/custom_item"
 +  }
 +}
 +</code>
 +
 +The item model definition will define the item model that the item uses.
 +
 +> :!: Creating these files manually for each item can be tiring. You may refer to [[datagen_model]] for data generation.
  
 ===== Creating an Item class ===== ===== Creating an Item class =====
Line 204: Line 219:
  
 ===== Item components ===== ===== Item components =====
-Sometimes you may need to add some default components for the item, such as max stack size or fire durability. This can be done by calling ''component'' method in ''Item.Settings''. Detailed information about item components can be found in [[https://docs.fabricmc.net/zh_cn/develop/items/custom-data-components|the tutorial in Fabric docs]].+Sometimes you may need to add some default components for the item, such as max stack size or fire durability. This can be done by calling ''component'' method in ''Item.Settings''. Detailed information about item components can be found in [[https://docs.fabricmc.net/develop/items/custom-data-components|the tutorial in Fabric docs]].
  
 In this example, the item will be unbreakable by default, while hiding tooltips about it. In this example, the item will be unbreakable by default, while hiding tooltips about it.
 <yarncode java> <yarncode java>
-    public static final CustomItem CUSTOM_ITEM = new CustomItem(new class_1792.class_1793().component(DataComponentTypes.UNBREAKABLE, new UnbreakableComponent(true)));+    // For versions below 1.21.2: 
 +    public static final CustomItem CUSTOM_ITEM = register("custom_item", new CustomItem(new class_1792.class_1793() 
 +        .component(DataComponentTypes.UNBREAKABLE, new UnbreakableComponent(true)))); 
 +         
 +    // For versions since 1.21.2, before 1.21.4: 
 +    public static final Item CUSTOM_ITEM = register("custom_item", CustomItem::new, new Item.Settings() 
 +        .component(DataComponentTypes.UNBREAKABLE, new UnbreakableComponent(true))); 
 +         
 +    // For versions since 1.21.4: 
 +    public static final Item CUSTOM_ITEM = register("custom_item", CustomItem::new, new Item.Settings() 
 +        .component(DataComponentTypes.UNBREAKABLE, Unit.INSTANCE));
 </yarncode> </yarncode>
  
-Specifically, max stack size can be simply set by calling ''maxCount'' method (which is valid also before 1.20.5). Note that if your item is damageable you cannot specify a maximum stack size or the game will throw a RuntimeException.+Specifically, max stack size can be simply set by calling ''maxCount'' method (which is valid also before 1.20.5). Note that if your item is damageable you cannot specify a maximum stack size or the game will throw a ''RuntimeException''. 
 <yarncode java [enable_line_numbers="true"]> <yarncode java [enable_line_numbers="true"]>
 public class ExampleMod implements ModInitializer { public class ExampleMod implements ModInitializer {
- 
     // An instance of our new item, where the maximum stack size is 16     // An instance of our new item, where the maximum stack size is 16
-    public static final CustomItem CUSTOM_ITEM = new CustomItem(new class_1792.class_1793().maxCount(16));+     
 +    // For versions below 1.21.2: 
 +    public static final CustomItem CUSTOM_ITEM = register("custom_item", new CustomItem(new class_1792.class_1793().maxCount(16))); 
 +     
 +    // For versions since 1.21.2: 
 +    public static final Item CUSTOM_ITEM = register("custom_item", CustomItem::new, new Item.Settings().maxCount(16));
     [...]     [...]
 } }
Line 228: Line 258:
     [...]     [...]
          
-    // For versions below 1.21.3+    // For versions below 1.21.2
     @Override     @Override
     public void onInitialize() {     public void onInitialize() {
         [...]         [...]
-        FuelRegistry.INSTANCE.add(TutorialItems.CUSTOM_ITEM, 300)+        FuelRegistry.INSTANCE.add(TutorialItems.CUSTOM_ITEM, 300);
     }     }
 } }
 </code> </code>
  
-In practice, when you have many items to register, as registering quantities of items may be effort-consuming and messy, you can consider placing them in a separate method.+However, in practice, when you have many items to register, as registering quantities of items may be effort-consuming and messy, you can consider placing the codes in a separate method, instead of writing like above.
  
-In versions below 1.21.3, you need to use Fabric API's ''FuelRegistry.INSTANCE''.+In versions below 1.21.2, you need to use Fabric API's ''FuelRegistry.INSTANCE''.
 <code java> <code java>
 public final class TutorialItems { public final class TutorialItems {
     [...]     [...]
          
-    // For versions below 1.21.3+    // For versions below 1.21.2
     public static void registerFuels() {     public static void registerFuels() {
-        FuelRegistry.INSTANCE.add(CUSTOM_ITEM, 300)+        FuelRegistry.INSTANCE.add(CUSTOM_ITEM, 300);
     }     }
 } }
 </code> </code>
  
-In versions since 1.21.3, use Fabric API's ''FuelRegistryEvents'':+In versions since 1.21.2, use Fabric API's ''FuelRegistryEvents'':
 <code java> <code java>
 public final class TutorialItems { public final class TutorialItems {
     [...]     [...]
          
-    // For versions since 1.21.3+    // For versions since 1.21.2
     public static void registerFuels() {     public static void registerFuels() {
         FuelRegistryEvents.BUILD.register((builder, context) -> {         FuelRegistryEvents.BUILD.register((builder, context) -> {
Line 281: Line 311:
 Similarly, you can use a ''CompostingChanceRegistry'' to make it compostable in a composter. Similarly, you can use a ''CompostingChanceRegistry'' to make it compostable in a composter.
 ===== Next Steps ===== ===== Next Steps =====
-[[tutorial:itemgroup|Add your item to your own ItemGroup]].+Try [[itemgroup|adding your item to an item group]]. Your item also does not have a name, so you can also [[lang|learn how to add language files]].
tutorial/items.1730038052.txt.gz · Last modified: 2024/10/27 14:07 by solidblock