Проверено на версиях: Java Edition 1.20–26.3.
Что изменилось на самом деле
Теперь предмет — это его ID плюс список компонентов. У каждого компонента фиксированная форма, и игра проверяет её при чтении команды, поэтому опечатка, которую NBT раньше проглатывал, теперь останавливает команду. Другое большое отличие: свободных ключей больше нет. Тег, который вы раньше придумывали, например role:"guard", должен жить внутри custom_data.
Один и тот же предмет до 1.20.5 и в 1.21.5 – 26.x:
/give @p minecraft:paper{display:{Name:'{"text":"Guild Pass","italic":false}'},CustomModelData:12,role:"guard"} 1
/give @p minecraft:paper[minecraft:custom_name={text:"Guild Pass",italic:false},minecraft:custom_model_data={floats:[12f]},minecraft:custom_data={role:"guard"}] 1
Старый тег → компонент
| До 1.20.5 | С 1.20.5 | Позднее изменение |
|---|---|---|
display.Name | custom_name или item_name | 1.21.5: записывается как текст SNBT, {text:"…"} |
display.Lore | lore | 1.21.5: каждая строка — текст SNBT |
CustomModelData:12 | custom_model_data | 1.21.4: {floats:[12f]}, плюс списки flags, strings и colors |
Enchantments | enchantments | 1.21.5: {"minecraft:sharpness":3} без обёртки levels |
AttributeModifiers | attribute_modifiers | 1.21: id с пространством имён; 1.21.2: без generic.; 1.21.5: обычный список |
Unbreakable:1b | unbreakable={} | |
HideFlags | поля show_in_tooltip, hide_additional_tooltip | 1.21.5: tooltip_display={hidden_components:[…]} |
Свои теги, например role:"guard" | custom_data={role:"guard"} | Единственное место для своих ключей |
display.color | dyed_color | 1.21.5: dyed_color=12345 вместо {rgb:12345} |
Potion, CustomPotionEffects | potion_contents | |
SkullOwner | profile | |
BlockEntityTag, EntityTag | block_entity_data, entity_data |
Когда мир открывают в новой версии, игра конвертирует хранящиеся в нём предметы. Команды не конвертируются: командные блоки, файлы функций и сохранённые заметки остаются в старом синтаксисе, пока их не перепишешь.
Два более поздних изменения
1.21.4 изменил выбор моделей. custom_model_data стал четырьмя типизированными списками (floats, flags, strings, colors), а ресурс-пак выбирает модель через item definition в assets/<namespace>/items/, на который предмет указывает компонентом item_model. Старые overrides в моделях предметов перестали работать.
1.21.5 изменил запись компонентов. Текстовые компоненты пишутся в SNBT, а не строками JSON, несколько компонентов потеряли обёртку (enchantments, attribute_modifiers, dyed_color), а все поля show_in_tooltip переехали в один компонент tooltip_display.
Почему custom_data важен для серверов
Видимое имя легко подделать на наковальне. Если магазин, дверь или квест проверяют скрытое значение в custom_data, переименованный ванильный предмет не пройдёт. Торги жителей с 1.20.5 сравнивают компоненты, указанные в цене, поэтому сделка, которая просит custom_data={currency:"guild_voucher"}, примет только настоящую расписку.
Как перевести сервер и ничего не сломать
- Составьте список всех мест, где создаются предметы: командные блоки, функции, таблицы лута, сделки жителей, конфиги плагинов.
- Сначала переведите имена, лор и придуманные теги (
custom_data) — их читают магазины и квесты. - Если вы переходите на 1.21.4 или новее, переписывайте хуки моделей вместе с ресурс-паком: команда заполняет ячейку, item definition её читает.
- Проверьте каждый предмет в игре, прежде чем он попадёт к игрокам, и держите список там, где его видит вся команда.
Частые вопросы
custom_name или item_name?
custom_name работает как переименование на наковальне и пишется курсивом, если не указать italic:false. item_name — собственное имя предмета, без курсива, и наковальня его не снимет.
Можно ли добавить предмету свои данные?
Да, внутри custom_data. Он принимает любой compound, и его могут проверять команды, предикаты и торги жителей.
Есть ли официальный список компонентов?
Игра показывает их в автодополнении /give, а страница «Data component format» на Minecraft Wiki описывает каждый вместе с историей изменений.