🔢 Item Data

What is Item Data?

Item Data refers to the NBT (Named Binary Tag) of an item in older versions, or the item Components in version 1.20.5 and above. Through this data, we can customize various aspects of an item such as its name, description, attributes, and other functionalities.

Hard-coded Data

Hardcoded data, in this context, means that the configuration formats are provided and maintained by plugin, which ensures compatibility across different versions. These formats are defined by the plugin, so they may differ from the standard NBT (Named Binary Tag) or Components formats used by the game itself. The advantage of this approach is that the plugin handles all the maintenance, including version compatibility, so users do not need to worry about changes or updates between game versions.

items:
  default:topaz_rod:
    data:
      display-name: "<!i><#FF8C00>Topaz Rod"

display-name

Determines the displayed name of the item.

items:
  default:topaz_rod:
    data:
      display-name: "<!i><#FF8C00>Topaz Rod"

lore

Determines the displayed description of the item.

items:
  default:topaz_rod:
    data:
      lore: 
        - "What a shiny rod!"

unbreakable

Determines whether the item is unbreakable

items:
  default:topaz_rod:
    data:
      unbreakable: true

Customizable Data

Customizable Data is not maintained by plugins, and its format can change with updates to Minecraft, particularly with the frequent recent changes to Components. If you want to avoid extensive configuration overhauls due to version updates, you might consider using templates to establish a standardized configuration file format. When a new version is released, you can simply update the template to accommodate any changes. If you are unfamiliar with how to use templates, please make sure to read the guide provided at 📄 Templates [MUST READ]. This approach can help streamline the update process and reduce the effort required to keep your configurations compatible with the latest game versions.

NBT (1.20-1.20.4)

Since NBT (Named Binary Tag) has become outdated, it will not be discussed in detail here.

items:
  default:topaz_rod:
    data:
      nbt:
        CustomModelData: 1000

Components (1.20.5+)

The format for custom Components strictly adheres to the Minecraft Wiki guidelines. Below, I will guide you through a few examples to help you become familiar with how to configure custom Components.

From the image, we can see that max_damage accepts an I (which stands for an integer type parameter). Therefore, in our configuration, we simply need to use a numerical value directly.

items:
  guide:test:
    data:
      components:
        minecraft:max_damage: 128

From the image, we can see that food requires three parameters: nutrition of type int, saturation of type float, and can_always_eat of type boolean.

items:
  guide:test:
    data:
      components:
        minecraft:food:
          nutrition: 4
          saturation: 2.0
          can_always_eat: false

Now, let's try working with a compound tag. The {} signifies that you need to open a new section in your YAML configuration.

items:
  guide:test:
    data:
      components:
        minecraft:enchantments:
          levels:
            minecraft:sharpness: 1
          show_in_tooltip: false

However, upon closer inspection of the wiki, you'll notice that this method becomes obsolete in version 1.21.5. When 1.21.5 is released, you will need to update your configuration file as follows:

items:
  guide:test:
    data:
      components:
        minecraft:enchantments:
          minecraft:sharpness: 1

In the following example, the issue arises due to changes in Minecraft versions causing Components to become obsolete.

items:
  default:topaz_rod:
    data:
      components:
        # 1.20.5-1.21.3
        minecraft:custom_model_data: 1000
        # 1.20.5-1.21.4
        minecraft:enchantments:
          levels:
            minecraft:sharpness: 1
          show_in_tooltip: false
          
        # 1.21.4+
        minecraft:custom_model_data:
          floats:
            - 1000.0
        # 1.21.5+
        minecraft:enchantments:
          minecraft:sharpness: 1

To avoid such frustrations, you might create a template as outlined below:

templates:
  # 1.20.5-1.21.3
  components:custom_model_data:
    minecraft:custom_model_data: "{cmd}"
  # 1.20.5-1.21.4
  components:enchantments:
    minecraft:enchantments:
      levels: "{enchantments}"
      show_in_tooltip: false

# when you update to 1.21.4+
templates:
  components:custom_model_data:
    minecraft:custom_model_data:
      floats:
        - "{cmd}"

# when you update to 1.21.5+
templates:
  components:enchantments:
    minecraft:enchantments: "{enchantments}"
    minecraft:tooltip_display:
      hidden_components:
        - minecraft:enchantments

# So you don't have to edit the item configs
items:
  test:item:
    data:
      components:
        template: 
          - components:custom_model_data
          - components:enchantments
        arguments:
          cmd: 1000
          enchantments:
            minecraft:sharpness: 1