Getting started with structured items

Starting with 1.20.5, Mojang redesigned the data format for item stacks. Items are no longer storing their attributes inside a NBT compound tag. From now on their is a completely new designed format called structured components. Each structured component has a fixed design and it's own numerical id. Its function can be compared to packets. You can find more information about structured components here.

Supported structured components

Protocolize only supports a few of all available structured components. Here is a list of all currently supported components:

Component Name	Protocolize Class
minecraft:custom_data	dev.simplix.protocolize.api.item.component.CustomDataComponent
minecraft:max_stack_size	dev.simplix.protocolize.api.item.component.MaxStackSizeComponent
minecraft:max_damage	dev.simplix.protocolize.api.item.component.MaxDamageComponent
minecraft:damage	dev.simplix.protocolize.api.item.component.DamageComponent
minecraft:custom_name	dev.simplix.protocolize.api.item.component.CustomNameComponent
minecraft:item_name	dev.simplix.protocolize.api.item.component.ItemNameComponent
minecraft:lore	dev.simplix.protocolize.api.item.component.LoreComponent
minecraft:custom_model_data	dev.simplix.protocolize.api.item.component.CustomModelDataComponent
minecraft:hide_tooltip	dev.simplix.protocolize.api.item.component.HideTooltipComponent

Everything not listed here is not supported by default (e.g. enchantments, banners). As always you can implement missing StructuredComponents yourself using the Protocolize API.

Using structured components

Display name and lore

The ItemStack class still contains the attributes for the display name of the item and it's lore. When they are not null, then Protocolize will use the values from the ItemStack class and will write components based on them during serialization. Your own applied LoreComponent and/or CustomNameComponent will get overridden!

Get an existing structured component

Example for getting the damage of an item:

DamageComponent damageComponent = itemStack.getComponent(DamageComponent.class);  
if (damageComponent != null) {  
  int damage = damageComponent.getDamage();  
}

Add a new structured component

Example for setting the damage of an item:

itemStack.addComponent(DamageComponent.create(damage));

Remove an existing structured component

Example of removing the damage attribute from an item:

itemStack.removeComponent(damageComponent.getType());

You have to retrieve an instance of the component to be removed beforehand.

Compatibility

Since the structured item format only works from Minecraft version 1.20.5 up to latest, changes made using this API won't reflect on items sent to older client versions at all. If your network allows older than 1.20.5 clients to join, make sure to apply your wanted item attributes also to the deprecated NBT compound of the item stack in the old way.