Hardcoded item properties (Java Edition)

This feature is exclusive to Java Edition.

 

This article is a work in progress.

 

Please help expand and improve it. The talk page may contain suggestions.
Note:

See Projects/Hardcoded item for more information

This page is part of the Hardcoded item project.

 

This article needs cleanup to comply with the style guide.

 ^[discuss]

Please help improve this page. The talk page may contain suggestions.

Hardcoded item properties are aspects of items which are tied to the IDs and cannot be customized fully via the use of commands or data packs.

Many of the properties associated with items in the game have been made controllable with the newly-introduced data component format; this intends to track things that aren't controllable via components or item tags.

Code structure

There are at least three ways in which the game code describes the properties of an item.

Item.Properties

In class Item.Properties, the game defines a series of functions that can be applied to an item and change its properties. However, the vast majority of these properties ultimately only modify the item's data components.

However, even though it's possible to change the components of item stacks, data packs cannot change the default components of the items themselves.

A complete list of default components in 1.21.11 can be seen at misode/mcmeta. The list for 26.1 Snapshot 6 can be found here.

A notable exception is the craftRemainder property, which defines which item will remain in a recipe when using the item as a recipe. See below for a list of all craft reminders:

Item	Craft remainder	Vanilla use
Milk Bucket	Bucket	Cake recipe
Lava Bucket	Bucket	Fuel remainder in smelting
Water Bucket	Bucket	None
Honey Bottle	Glass Bottle	Honey block and sugar recipes.
Dragon's Breath	Glass Bottle	Ingredient remainder in brewing.[note 1]

All craft remainder can also be used in custom recipes via data packs. In code is also used in the craft display item, however it apparently hasn't been implemented in the game.​^{[more information needed]}

Another exception is the item descriptionId, which can be minecraft.item.<id> or minecraft.block.<id>. Although its primary use is for the item name, which is customizable by the item_name component, this description id is also used for other things, such as portion names and disc fragment descreipition.

Most of the Item.Properties applied to items are applied from the item's record in Items.

Item subclasses (code structure)

In the item package, there are many classes that define properties for a certain item or a certain set of items; these classes extend the Item class. A large part of the hardcoded item properties come from here.

These classes have [something]Item as their name, such as DyeItem, HoeItem, and NameTagItem.

In many cases, when an item is registered in Items, it is already created as a new instance of one of these classes.

Some of them are abstract classes, not having any item that is restricted as a new instance of that class; however, these classes are extended by other classes, and so on until reaching a class that is at least one item, which is then restricted as a new instance of the class.

Most of the properties of an item defined as belonging to a specific subclass are defined within the subclass itself. However, sometimes in other classes, instanceof is used to test if a certain item is an item of that class, and thus new properties can be defined for the item.

List

The table below shows the classes that extend Item and the IDs of the items that are restricted as instances of them (in Items).

See § Item subclasses for details.

Items class member access

In many parts of the game's code, within many contexts, direct access to an item's restricted area is used, by Items member access, allowing to determine a property of that item.

In certain cases, this item call only serves to create the vanilla datapack, for example by creating item tags, recipes, loot tables and trades​^{[upcoming 26.1]}. Therefore, this is a property that can be fully controlled by datapacks. However, it's worth noting that many of these properties that we can fully control through data packs (and not through components) can only be controlled by the item's ID, not by its components.

Furthermore, in some cases, it creates a new instance of the item. This could be due to an item origin not controlled by a loot table (such as equipment or wither flowers), a visual effect (such as using items in a GUI), or some other use (such as a mob using an item as a projectile). In these cases, we are not strictly talking about an item property, as we are not discussing how a pre-existing item modifies the game.^{[note 2]}

List

This section describes content that is currently in development for Java Edition.

 

This content has appeared in development versions for Java Edition 26.1, but the full update adding it has not been released yet.

The table below shows all the classes (except client classes) that has a Items memmber access, and the number of uses in each class^{[note 3]}. According to the code of 26.1 Snapshot 5.

Legend：

• red The background indicates that all items within that class are used only for generating the vanilla datapack.
• yellowThe background indicates that all items within them are a new instance, representing an item's origin, visual use, etc., and not a property of a pre-existing item.

See § Items member access, for details of the classes without note.

Item class

This section is a work in progress.

 

Please help expand and improve it. The talk page may contain suggestions.

getId(...)

byId(...)

byBlock(...)

Item(...)

builtInRegistryHolder()

components()

getDefaultMaxStackSize()

onUseTick(...)

Empty, for most items, it doesn't add any properties. However, it can add properties with its implementations, see below.

Uses

Only used in ItemStack by onUseTick(...), after properties relating to consumable and kinetic_waapon components.

• Activated on each tick if the item stack used remains in the same hand of the entity.
• For the crossbow also activated at other times. See § useOnRelease(...).

Implementations

• BrushItem
• BundleItem
• CrossbowItem

onDestroyed(...)

canDestroyBlock(...)

asItem()

useOn(...)

getDestroySpeed(...)

use(...)

finishUsingItem(...)

isBarVisible(...)

getBarWidth(...)

getBarColor(...)

overrideStackedOnOther(...)

overrideOtherStackedOnMe(...)

getAttackDamageBonus(...)

getItemDamageSource(...)

hurtEnemy(...)

postHurtEnemy(...)

mineBlock(...)

isCorrectToolForDrops(...)

interactLivingEntity(...)

toString()

getCraftingRemainder()

inventoryTick(...)

onCraftedBy(...)

onCraftedPostProcess(...)

getUseAnimation(...)

getUseDuration(...)

releaseUsing(...)

appendHoverText(...)

getTooltipImage(...)

getDescriptionId()

getName(...)

isFoil(...)

getPlayerPOVHitResult(...)

useOnRelease(...)

getDefaultInstance()

canFitInsideContainerItems()

requiredFeatures()

shouldPrintOpWarning(...)

Item subclasses

This section is a work in progress.

 

Please help expand and improve it. The talk page may contain suggestions.

Only subsections marked with an asterisk (*) aren't empty.

AirItem

Air is generated from register registerBlock(Blocks.AIR, AirItem::new). Therefore, it shares the same ID with the air block (minecraft:air) and has minecraft.block.air as its description ID.

However, unlike all other items defined by some method registerBlock(...), air is not a instance of BlockItem, because AirItem does not extend BlockItem.

getName(...)

Defined ignoring the item stack components, therefore, it is always a translation of minecraft.block.air regardless of the component item_name.

Note that many other properties of the air item are defined elsewhere in the code. See § Items member access.

ArmorStandItem

useOn(...)

If the interaction involves clicking on the dowm side of a block, it fails.

The target position for placing the armor stand is the bottom center of the block next to the interacted block, in the direction of the interacted face. The game simulates the hitbox of an armor stand in this position; if the hitbox collides with a block or intersects with an (no spectator) entity hitbox, the interaction fails.

The game attempts to obtain the armor stand, based on the item's components custom_name, custom_data, and entity_data. If it cannot be generated, the interaction fails.

In case of the armor stand is generated, apply in the following order:

• the armor stand rotates 202.5° according to the player's rotation, but rounds its rotation down to some multiple of 45°;
• the sound event armor stand place (entity.armor_stand.place) is played;
• produce the game event entity_place;
• shrink one item of the item stack.

The interaction returns success given no aforementioned fails occur.

ArrowItem

This section of the article is empty.

 

You can help by expanding it.

AxeItem

This section of the article is empty.

 

You can help by expanding it.

BannerItem

This section of the article is empty.

 

You can help by expanding it.

BedItem

This section of the article is empty.

 

You can help by expanding it.

BlockItem

This section of the article is empty.

 

You can help by expanding it.

BoatItem

This section of the article is empty.

 

You can help by expanding it.

BoneMealItem

This section of the article is empty.

 

You can help by expanding it.

BottleItem

This section of the article is empty.

 

You can help by expanding it.

BowItem

This section of the article is empty.

 

You can help by expanding it.

BrushItem

This section of the article is empty.

 

You can help by expanding it.

BucketItem

This section of the article is empty.

 

You can help by expanding it.

BundleItem

This section of the article is empty.

 

You can help by expanding it.

CompassItem

This section of the article is empty.

 

You can help by expanding it.

CrossbowItem

This section of the article is empty.

 

You can help by expanding it.

DebugStickItem

This section of the article is empty.

 

You can help by expanding it.

DiscFragmentItem

appendHoverText(...)

Define the first line of the tooltip as the translation of item.minecraft.disc_fragment.desc in gray (
 #AAAAAA).

This line cannot be hidden by the tooltip_display component, except to completely hide the tooltip with hide_tooltip set to true.

DispensibleContainerItem

This section of the article is empty.

 

You can help by expanding it.

DoubleHighBlockItem

This section of the article is empty.

 

You can help by expanding it.

DyeItem

Each item is associated‌^{[until JE 26.1]} with a dyeColor, that is a list with a ID, name, texture diffuse color, map color, firework color and text color. See Dye § Color values and color in text component format. From map color the white color is SNOW, lime is COLOR_LIGHT_GREEN and the other colors are COLOR_<COLOR NAME>.

Each item has​^{[upcoming JE 26.1]} a default dye component, defined in Items.

interactLivingEntity(...)

The interaction is only successful, instead of pass, when the interacting entity is a non-sheared live sheep of a different color than the dye color and the item stack has a dye component​^{[upcoming JE 26.1]}.

In case of success, the sound dye use is played, set the sheep color (using the ID) and shrink the item stack by one.

getDyeColor()‌^{[until JE 26.1]}

Get the dyeColor associated with the item. All usages below:

• Cat and Wolf: In mobInteract, if the animal is tame by the player and the color of the collar is different, set the collar color and remove one item from the item stack. For cats, also set PersistenceRequired to true.
• LoomMenu: In setupResultSlot, to set the banner pattern color in the loom menu
• DyeColor: In getMixedColor. This function receives two dyeColor, transforms them into dyes, and use they in crafting input. If the result is a dye, its DyeColor is returned. Otherwise, it returns a random color between the two received. It is Used to choose the collar color for baby cats and wolfs, and the baby sheep color, based on the parents' colors.
• DyeItem: In tryApplyToSign, see below.
• DyedItemColor: In applyDyes. This function changes the dyed_color component of an item based on a list of dyes. See the dye mixing formula for more details. Used for armor dye recipe and for a randomly armor dye for trading.
• FireworkStarFadeRecipe and FireworkStarRecipe: In assemble. Used for the result of firework star special recipes, append the firework color to colors and fede_colores from firework explosion component. These recipes cannot be customized by datapacks.

byColor(...)‌^{[until JE 26.1]}

A function that receives a dyeColor and returns a dye. Used to create vanilla recipes (fully controlled by datapacks!). There are other uses, but these are only uses that assist with getDyeColor(), all of which are listed above.

tryApplyToSign(...)

If the stack item does not contain the dye component, it returns false​^{[upcoming JE 26.1]}.

Try changing the text color on the sign, on the side being interacted with, to the color of the dye.

In case of success, the dye used sound is played and returns true. Otherwise, returns false.

Usage in instanceof

In other classes, some items are states of being an instance of DyeItem, meaning they are one of the dyes‌^{[until JE 26.1]}. All these uses are listed below:

• Cat and Wolf: In mobInteract(...), for test if the item is a dye before applying the getDyeColor() method to color the collar.
  • In Cat, it is also used to prevent the item from being used as food for the cat tamed by the player, even if the item is in the #cat_food tag and not being used (because it is the same color as the old collar). However, for untamed cats, the dye can be used as food.

• LoomMenu: Used twice:
  • In mayPlace(...): Returns true iff the item is a dye. Used to allow items to be used in the loom dye slot.
  • In quickMoveStack(...): Used to allow dyes to be moved from the inventory to the loom dye slot with a quick click (click + Shift).
    • This also prevents quick clicking from moving dyes to the pattern slot (even when the provides_banner_patterns component is present) or moving them between storage slots and hotbar slots and vice versa, when the loom menu is open. Even if the dye fails to move to the dye slot.

• ArmorDyeRecipe, FireworkStarFadeRecipe, and FireworkStarRecipe: In each of these classes, used twice:
  • In matches(...): To test if the items in the crafting input can be used for one of these special recipes.
  • In assemble(...): Used for the result of the special recipes, to test if the item is a dye before applying applyDyes(...) or getDyeColor().

EggItem

This section of the article is empty.

 

You can help by expanding it.

EmptyMapItem

This section of the article is empty.

 

You can help by expanding it.

EndCrystalItem

This section of the article is empty.

 

You can help by expanding it.

EnderEyeItem

This section of the article is empty.

 

You can help by expanding it.

EnderpearlItem

This section of the article is empty.

 

You can help by expanding it.

ExperienceBottleItem

This section of the article is empty.

 

You can help by expanding it.

FireChargeItem

This section of the article is empty.

 

You can help by expanding it.

FireworkRocketItem

This section of the article is empty.

 

You can help by expanding it.

FishingRodItem

This section of the article is empty.

 

You can help by expanding it.

FlintAndSteelItem

This section of the article is empty.

 

You can help by expanding it.

FoodOnAStickItem

This section of the article is empty.

 

You can help by expanding it.

GameMasterBlockItem

This section of the article is empty.

 

You can help by expanding it.

GlowInkSacItem

This section of the article is empty.

 

You can help by expanding it.

HangingEntityItem

This section of the article is empty.

 

You can help by expanding it.

HangingSignItem

This section of the article is empty.

 

You can help by expanding it.

HoeItem

This section of the article is empty.

 

You can help by expanding it.

HoneycombItem

This section of the article is empty.

 

You can help by expanding it.

InkSacItem

This section of the article is empty.

 

You can help by expanding it.

InstrumentItem

This section of the article is empty.

 

You can help by expanding it.

Item

This section of the article is empty.

 

You can help by expanding it.

ItemFrameItem

This section of the article is empty.

 

You can help by expanding it.

KnowledgeBookItem

This section of the article is empty.

 

You can help by expanding it.

LeadItem

This section of the article is empty.

 

You can help by expanding it.

LingeringPotionItem

This section of the article is empty.

 

You can help by expanding it.

MaceItem

This section of the article is empty.

 

You can help by expanding it.

MapItem

This section of the article is empty.

 

You can help by expanding it.

MinecartItem

This section of the article is empty.

 

You can help by expanding it.

MobBucketItem

This section of the article is empty.

 

You can help by expanding it.

NameTagItem

This section is missing information about: At what point in the code is the name tag prevented from being used in the Ender Dragon?

 

Please expand the section to include this information. Further details may exist on the talk page.

interactLivingEntity(...)

The interaction will only be successful, instead of being passed, when:

• the item has a custom_name component, and
• the entity isn't a player, leash knot, lightning bolt, or fishing bobber.

If the entity is alive, sets its CustomName to be the same as the name tag. If the entity is a mob, also sets PersistenceRequired true. Shrink the item stack of the item by one.

PlaceOnWaterBlockItem

This section of the article is empty.

 

You can help by expanding it.

PlayerHeadItem

This section of the article is empty.

 

You can help by expanding it.

PotionItem

useOn(...)

The interaction will only be successful when:

• the face of the interacted block was not directed downwards,
• the block is in the #convertable_to_mud tag, and
• the potion's content is water.

In case of success, apply in the following order:

1. Play sound generic splash (entity.generic.splash),
2. Set glass bottle in hand,
3. Send splash particles,
4. Play bottle empty sound (item.bottle.empty),
5. Produce the game event fluid_place,
6. Convert the block to mud.

getName(...)

If the item has the component potion_contents, the name name is defined from it. The item uses the translation key item.minecraft.<item type>.effect.<potion name>, where <potion name> is the custom name of the potion contents, if available, and otherwise is the name of the potion in potion contents (see Potion § Item data), if available. If nether is available, is "empty".

This name will replace the name defined by item_name. However, it can still be replaced by the custom_name, if available.

ProjectileItem

This section of the article is empty.

 

You can help by expanding it.

ProjectileWeaponItem

This section of the article is empty.

 

You can help by expanding it.

ScaffoldingBlockItem

This section of the article is empty.

 

You can help by expanding it.

ShearsItem

This section of the article is empty.

 

You can help by expanding it.

ShieldItem

getName(...)

If the item has the component base_color, the name is defined from it. The item uses the translation key item.minecraft.shield.<color>.

This name will replace the name defined by item_name component. However, it can still be replaced by the custom_name component, if available.

ShovelItem

This section of the article is empty.

 

You can help by expanding it.

SignItem

This section of the article is empty.

 

You can help by expanding it.

SmithingTemplateItem

This section of the article is empty.

 

You can help by expanding it.

SnowballItem

This section of the article is empty.

 

You can help by expanding it.

SolidBucketItem

This section of the article is empty.

 

You can help by expanding it.

SpawnEggItem

This section of the article is empty.

 

You can help by expanding it.

SpectralArrowItem

This section of the article is empty.

 

You can help by expanding it.

SplashPotionItem

This section of the article is empty.

 

You can help by expanding it.

SpyglassItem

This section of the article is empty.

 

You can help by expanding it.

StandingAndWallBlockItem

This section of the article is empty.

 

You can help by expanding it.

ThrowablePotionItem

This section of the article is empty.

 

You can help by expanding it.

TippedArrowItem

This section of the article is empty.

 

You can help by expanding it.

TridentItem

This section of the article is empty.

 

You can help by expanding it.

WindChargeItem

This section of the article is empty.

 

You can help by expanding it.

WritableBookItem

use(...)

Open item GUI and increases the used statistic by one. Always returns successful.

Note:

The item GUI depends on the components writable_book_content and written_book_content. Therefore:

• If the item does not have either component: nothing is opened, but there is still an increase in statistics and usage animation.
• If the item has only one of these components: the corresponding GUI opens.
• If both components are present: both GUIs open, but the written book content GUI completely overlays the writable book content GUI, which the player can see briefly on the screen.

Therefore, the GUI are entirely dependent on the components and independent of the item ID. However, it is only possible to open them with the book and quill and written book, since only these items attempt to open the GUI.

WrittenBookItem

use(...)

Completely identical to WritableBookItem; see the § WritableBookItem.

Items member access

Blocks

Entity

Misc

CauldronInteraction

This section of the article is empty.

 

You can help by expanding it.

DispenseItemBehavior

This section of the article is empty.

 

You can help by expanding it.

AnvilMenu

createResult

If the anvil input is an enchanted book, it will initially consider any enchantment as compatible. However, if the enchantment is the same or does it conflict with any enchantment in the current list of enchantments in the result, it will no longer be considered compatible.

In other words, it's as if the enchanted book were in supported_items for all enchantment definition, when we consider the anvil.

PotionSlot

mayPlaceItem

Returns true only if it is one of the four items listed above. Used to determine which items can be placed in the portion slot of the brewing stand.

It is also used in quickMoveStack, so that these items are attempted to be moved from the inventory to the potion slot with a quick click (click + Shift). Notes:

• If the item is in the #brewing_fuel tag, it will attempt to enter the fuel slot and not the potion slot (even if it fails to enter the fuel slot). Technically, the same would occur with ingredients, however, ingredients are also hardcoded and don't have intersection.
• This prevents quick clicking from moving them between storage slots and hotbar slots and vice versa, when the brewing stand menu is open. Even if the itens fails to move to the potion slot.

CartographyTableMenu

mayPlace

Returns true only if it is one of the three items listed above. Used to determine which items can be placed in the slot 1 of the cartography table.

setupResultSlot

Used to define the result item of the cartography table:

• If the mapStack (item in slot 0) does not have a mapData (data associated with its map_id component), it will not yield any results.

• If it's paper and the mapData is not locked and has a scale less than 4, the resulting is one copy of the mapStack with the map_post_processing component set to 1 (SCALE).

• If it's glass and the mapData is not locked, the resulting is one copy of the mapStack with the map_post_processing component set to 0 (LOCK).

• If it's empty map, the resulting is two copy of the mapStack.

Note: It's possible to use the cartography table regardless of the mapStack ID; it only needs to have the map_id component with data. However, when retrieving an item that the ID isn't filled_map with the map_post_processing component, the game crashes^[2]. However, using the empty map still works for item duplication.

quickMoveStack

When using the quick click (click + Shift) in the inventory with the table and control menu, it attempts to move these items to slot 1. Notes:

• If the item has the map_id component, it attempts to move it to slot 0 and does not go to slot 1 (even if it fails to go to slot 0).
• This prevents quick clicking from moving them between storage slots and hotbar slots and vice versa, when the cartography table menu is open. Even if the itens fails to move to the slot 1.

Future subsections

This section of the article is empty.

 

You can help by expanding it.

Old article stub

This section represents the former body of the article.

 

Keep it until all listed information is documented elsewhere on the article. The article was not originally collapsed.

List

This section is missing information about:

• Is entity_data used by spawn eggs, boats, minecarts, armor stands, paintings, item frames and end crystals by default, or are those controlled by the item ID?

 

Please expand the section to include this information. Further details may exist on the talk page.

• Block items
  • ID of the block placed
    • block_state can control the specific state an item places, but cannot control the exact ID.
• Projectile items: eggs, snowballs, splash potions, lingering potions, bottles o' enchanting, eyes of ender, ender pearls, firework rockets(?), wind charges
  • The entity spawned does not appear to be customizable.
• Fishing rods
  • What entity is spawned, and presumably many other things.
• Bows
  • Almost all aspects of behavior. ​^{[more information needed]}
• Crossbows
  • Much the same: defaults for animation, charge time, accepted items for loading, ...
• Tridents
  • Animation, charge time
• Swords
  • The ability to sweep attack
• Mace
• Items which can be fed to zombie villagers to cure them
• Lead
• Fire charge
  • Dispenser behavior appears to be hardcoded
  • ID of block placed
• Flint and Steel
  • ID of block placed
• Things in buckets
  • ID of block placed, and possibly entity spawned if this isn't handled already
  • Cauldron interaction
• Buckets
  • What block IDs (and states) / fluid IDs can be deleted on right click
  • Milking cows
  • Interacting with empty cauldrons
• Bowls
  • Milking mooshrooms
• Items that interact with blocks on right click, possibly including a loot table for dropped items, and whether the item should be deleted, damaged, or converted to something else on use
  • Hoes on tillable blocks - converting things to farmland, or coarse dirt to dirt
  • Shovels on dirt-like blocks, converting them into dirt paths
  • Axes on logs/wood and stems/hyphae, stripping
  • Axes on oxidised copper, reducing
  • Axes on waxed copper, dewaxing
  • Honeycomb on unwaxed copper, waxing
  • Water bottle on dirt-like blocks, converting to mud
  • Eye of Ender on empty end portal frame, adding the eye
  • Pottable plants used on flower pots, turning the pot into a potted plant
  • Shears on an uncarved pumpkin, carving it and producing seeds
  • Shears on a full beehive or bee nest, producing honeycomb and setting honey level to 0
  • Empty bottle on a full beehive or bee nest, converting it to a honey bottle and setting honey level to 0
• Bone meal usage
• Items used on entities
  • Shears
    • On sheep, to shear them
    • On mooshrooms, to shear them
    • On snow golems, to remove the pumpkin
    • On bogged, to obtain mushrooms
    • On leashed mobs, to obtain the lead
    • On some equipped mobs, to obtain the equipment
      • It is possible to control which equipment will be picked up with the scissors with the component equippable~{can_be_sheared:true}, but not which scissors (and not another item) will be used for this.
    • On copper golems, to obtain the poppy
  • Iron ingots
    • On iron golems, to heal them
  • Dyes
    • On sheep, to dye their wool
    • On wolves, to dye their collars
    • On cats, to dye their collars
  • Brush
    • On armadillos to get scutes
  • Axe
    • On oxidized copper golem, reducing
    • On waxed copper golem, dewaxing
  • Honeycomb
    • On unwaxed copper golem, waxing
• Empty bottles
  • Using on water or water cauldrons to fill the bottle
  • Using on dragon breath to fill the bottle
• Water bottles
  • Using on empty cauldrons or non-full water cauldrons to fill the cauldron
• Brush usage

History

This section is missing information about: History before Java Edition 26.1

 

Please expand the section to include this information. Further details may exist on the talk page.

Notes

References