Minecraft:Enchantment definition

Minecraft:Enchantments are stored as Minecraft:JSON files within a Minecraft:data pack in the path Template:Cd. Template:TOC

JSON format

• Template:Nbt: The root object.
  • Template:Nbt: A Minecraft:text component that is used to display the enchantment on items.
  • Template:NbtTemplate:Nbt: Template:Json ref/enchantment — Enchantments that are incompatible with this enchantment. — Defaults to an empty list.
  • Template:NbtTemplate:Nbt: Template:Json ref/item — Items on which this enchantment can be applied using an anvil or using the [[Minecraft:Commands/enchant|Template:Cd]] command.
  • Template:NbtTemplate:Nbt: (Optional) Template:Json ref/item; has to be a subset of Template:NbtTemplate:Nbt — Items for which this enchantment (if present in Template:Tag link) appears in an Minecraft:enchanting table. If unspecified, defaults to being the same as Template:NbtTemplate:Nbt.
  • Template:Nbt: Value between 1 and 1024 (inclusive) — Controls the probability of this enchantment when enchanting. The probability is determined Template:Cd, where Template:Cd is the sum of the weights of all available enchantments.
  • Template:Nbt: Value between 1 and 255 (inclusive) — The maximum level of this enchantment.
  • Template:Nbt: The minimum base cost of this enchantment in levels. The base cost range will be modified before use.
    • Template:Nbt: The minimum cost for a level I enchantment.
    • Template:Nbt: The amount of levels added to the minimum for each level above level I.
  • Template:Nbt: The maximum base cost of this enchantment in levels. The base cost range will be modified before use.
    • same fields as above
  • Template:Nbt: The base cost when applying this enchantment to another item using an Minecraft:anvil. Halved when adding using a book, multiplied by the level of the enchantment.
  • Template:Nbt: List of equipment slots that this enchantment works in.
    • Template:Nbt: one of Template:Cd, Template:Cd, Template:Cd, Template:Cd, Template:Cd, Template:Cd, Template:Cd, Template:Cd, Template:Cd, Template:Cd, Template:Cd — a slot
  • Template:Nbt: Effect components — Controls the effect of the enchantment.
    • Template:NbtTemplate:Nbt: An effect component
      • Fields depending on the component

Effect components

Components with value effects

These components use a value effect to change a value and an optional condition to check beforehand. The general format for them is:

• Template:Nbt
  • Template:Nbt
    • Template:Nbt: value effect — Determines how to modify the value.
    • Template:Nbt: Optional Minecraft:predicate — Determines when the effect is active. Cannot be of type minecraft:reference; all predicates must be in-lined.<ref name=":0">Minecraft 1.21 Pre-release 1 – minecraft.net, May 29, 2024.</ref>

      Additional fields of the Template:Cd component:

    • Template:Nbt: One of Template:Cd, or Template:Cd. — which entity has to have the enchantment

Component ID	Value changed	Minecraft:Loot context for predicate
Template:Cd	Effectiveness of the armor on the target of the attack. Template:Cd completely ineffective; Template:Cd completely effective	Template:Cd: Template:Cd entity: The attacked entity Template:Cd entity: the attacking entity Template:Cd entity: the projectile entity Enchantment level Origin: The position of the attacked entity Damage source
Template:Cd	Amount of damage dealt by an attack
Template:Cd	Amount of protection from incoming damage (specifically, from the portion of the damage that remains after accounting for armor). Each point of Template:Cd reduces this damage by 4%, up to a maximum of 80% per damaged entity.
Template:Cd	Amount of damage added to the smash attack of a Minecraft:mace, per block fallen
Template:Cd	Knockback caused by the attack
Template:Cd	Chance of equipment dropping from the killed entity. Value between Template:Cd and Template:Cd
Template:Cd	Amount of ammunition used when firing a Minecraft:bow or Minecraft:crossbow	Template:Cd: Tool: The ammo item Enchantment level
Template:Cd	Count of pierced entities by fired projectiles
Template:Cd	Amount of experience awarded for breaking a block	Template:Cd: Tool: The enchanted item Enchantment level
Template:Cd	Damage to repair per Minecraft:XP collected
Template:Cd	Amount of durability to lose when damaged
Template:Cd	Amount of projectiles spawned when firing	Template:Cd: Template:Cd entity: The projectile Enchantment level Origin The position of the projectile
Template:Cd	Used for Minecraft:tridents returning to their owner Template:More info
Template:Cd	Maximum spread of projectiles in degrees from firing direction	Template:Cd: Template:Cd entity: The player / attacking entity Enchantment level Origin The position of the attacking entity
Template:Cd	Time saved during Minecraft:fishing in seconds. A higher number means shorter total fishing time.
Template:Cd	Added Minecraft:luck used in the fishing Minecraft:loot table
Template:Cd	Amount of experience awarded for killing a mob	Template:Cd: Template:Cd entity: The killed mob Enchantment level Origin The position of the killed mob

Some components don't check a predicate and always modify a value when applied. Their format is:

• Template:Nbt: value effect — Determines how to modify the value.

Component ID	Value changed
Template:Cd	Time of crossbow charging in seconds
Template:Cd	Strength of the spin attack of a Minecraft:trident.Template:More info Any value larger than Template:Cd causes the trident to not be thrown.

Components with entity effects

These components use an entity effect to change a value and an optional condition to check beforehand. The general format for them is:

• Template:Nbt
  • Template:Nbt
    • Template:Nbt: entity effect — The entity effect to apply
    • Template:Nbt: Optional Minecraft:predicate — Determines when the effect is active. Cannot be of type minecraft:reference; all predicates must be in-lined.

      Additional fields of the Template:Cd component:

    • Template:Nbt: One of Template:Cd, Template:Cd, or Template:Cd. — which entity has to have the enchantment
    • Template:Nbt: One of Template:Cd, Template:Cd, or Template:Cd. — which entity is affected by the Template:Nbt.

Component ID	Effect applied	Minecraft:Loot context for predicate
Template:Cd	After an entity hits a block using the enchanted item	Template:Cd: Enchantment level Template:Cd entity: the entity hitting the block (the projectile if applicable) Origin: if hit with a Minecraft:melee attack, the center of the hit block; if hit with a Minecraft:projectile, the position the projectile hit the block at.<ref group="note">Unlike the projectile, the origin will always be within the bounds of the hit block. In other words, its block position always matches that of the hit block.</ref> Block state: the block state of the hit block
Template:Cd	Every tick	Template:Cd: Enchantment level Template:Cd entity: the owner of the enchanted item Origin: the position of the owner
Template:Cd	After a projectile entity has been spawned from a Minecraft:bow, Minecraft:crossbow, Minecraft:snowball, Minecraft:trident, Minecraft:splash potion, Minecraft:lingering potion, Minecraft:ender pearl, Minecraft:firework rocket, Minecraft:wind charge, or Minecraft:egg.	Template:Cd: Enchantment level Template:Cd entity: the projectile that spawned Origin: the position of the projectile
Template:Cd	After an attack damages an entity	Template:Cd: Template:Cd entity: the attacked entity Template:Cd entity: the attacking entity Template:Cd entity: the projectile entity Enchantment level Origin: the position of the attacked entity Damage source
Template:Cd	After a piercing attack is made, regardless of whether it hits anything	Template:Cd: Enchantment level Template:Cd entity: the owner of the enchanted item Origin: the position of the owner The predicate gets validated as if it gets the Template:Cd context.

location_changed

Enables or disables a location-based effect when the owners block position changed, i.e. when the integer portion of the coordinate changes. Also triggers when the equipment is equipped, and when an entity with the enchantment is loaded.

• Template:Nbt
  • Template:Nbt
    • Template:Nbt: location-based effect — The effect to apply
    • Template:Nbt: Optional Minecraft:predicate — Determines when the effect is active. Cannot be of type minecraft:reference; all predicates must be in-lined<ref name=":0" />.

The Minecraft:loot context for the predicate is Template:Cd:

• Template:Cd entity: The entity that moved
• Enchantment level
• Origin: The position of the entity that moved
• Enchantment active status: Flag whether the enchantment was active before, i.e. the predicate succeeded at the old position.

damage_immunity

Applies damage immunity if the requirements are fulfilled.

• Template:Nbt
  • Template:Nbt
    • Template:Nbt: Template:Cd
    • Template:Nbt: Optional Minecraft:predicate — Determines when the damage immunity is applied. Cannot be of type minecraft:reference; all predicates must be in-lined<ref name=":0" />.

The Minecraft:loot context for the predicate is Template:Cd:

• Template:Cd entity: The attacked entity (i.e the owner of the enchanted item)
• Template:Cd entity: the attacking entity
• Template:Cd entity: the projectile entity
• Enchantment level
• Origin Template:More info
• Damage source

prevent_equipment_drop

Prevents the item from being dropped on death of the owner when the component is present.

• Template:Nbt: Template:Cd

prevent_armor_change

Prevents the item from being unequipped from an armor slot.

• Template:Nbt: Template:Cd

attributes

Always applies all listed attribute effects.

• Template:Nbt:
  • Template:Nbt an attribute effect

crossbow_charging_sounds

Changes the sounds used when charging a Minecraft:crossbow.

• Template:Nbt:
  • Template:Nbt: the sounds used at enchantment level I
    • Template:Nbt: Template:Json ref — Optional, sound to use at start of charging
    • Template:Nbt: Template:Json ref — Optional, sound to use in the middle of charging
    • Template:Nbt: Template:Json ref — Optional, sound to use for the end of charging
  • Template:Nbt: the sounds used at enchantment level II
  • ...

trident_sound

Changes the sounds of a Minecraft:trident.

• Template:Nbt:
  • Template:Nbt: Template:Json ref — the sounds used at enchantment level I
  • Template:Nbt: Template:Json ref — the sounds used at enchantment level II
  • ...

Value effects

Value effects are used to modify a value, see Template:Slink.

set

Sets the value to the specified value.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: level based value determining the new value.

add

Adds the specified value to the old value.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: level based value determining the value to add.

multiply

Multiplies the old value with the specified factor.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: level based value determining the value to multiply.

remove_binomial

Runs a single<ref group="note">Although not clarified by Mojang, the Template:Code used in Template:Code indicates this. The Template:Cd is <math>\frac{level}{level+1}</math> for tools and <math>\frac{2\times level}{(5\times level)+5}</math> for armors, which is exactly the chance of not losing the durability upon each use (see Minecraft:unbreaking).</ref>Template:More info test with the Template:Cd of removing Template:Cd from the value.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: level based value determining the chance to remove Template:Cd .

all_of

Runs multiple value effects in series.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt: List of value effects
    • Template:Nbt: A value effect

Attribute effects

Attribute effects are used to apply an Minecraft:attribute modifier to the entity that has an enchanted item equipped.

• Template:Nbt The attribute effect
  • Template:Nbt: The id of the Minecraft:attribute to modify
  • Template:NbtTemplate:Nbt: level-based value — amount to add depending on level of the enchantment
  • Template:Nbt: One of Template:Cd, Template:Cd and Template:Cd — The operation to apply, see Template:Slink
  • Template:Nbt: A Minecraft:resource location to use for this attribute modifier. Must be unique. The equipment slot is postfixed to this id.

Entity effects

These effects are used to affect an entity by an enchantment component, see Template:Slink. The affected entity is determined by the component

all_of

Runs multiple entity effects in sequence.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt: The list of entity effects to run
    • Template:Nbt: A entity effect

apply_impulse

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt: The first step of determining the impulse is applying this vector as local coordinates (the same used by Template:Cd) onto the entity look vector
  • Template:Nbt: The second step is scaling the resulting vector by this vector on each axis in world space, X, Y and Z
  • Template:Nbt: The third step is scaling the resulting vector by this level-based value

apply_exhaustion

Applies an exhaustion effect to the affected player.

• Template:Nbt: Template:Cd
• Template:Nbt: The exhaustion to apply by this level-based value

apply_mob_effect

Applies a Minecraft:status effect to the affected mob.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: Template:Json ref — The effect(s) to apply.
  • Template:NbtTemplate:Nbt: level-based value — minimum possible duration of the effect in seconds
  • Template:NbtTemplate:Nbt: level-based value — maximum possible duration of the effect in seconds
  • Template:NbtTemplate:Nbt: level-based value — minimum possible amplifier of the effect
  • Template:NbtTemplate:Nbt: level-based value — maximum possible amplifier of the effect

damage_entity

Deals (extra) damage to the affected entity.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt: Template:Json ref
  • Template:NbtTemplate:Nbt: level-based value — minimum possible damage
  • Template:NbtTemplate:Nbt: level-based value — maximum possible damage

change_item_damage

Reduces the durability of the enchanted item

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: level-based value — The amount of durability to remove from the item

explode

Causes an explosion

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt: Should the explosion be attributed to the entity using the enchanted item?
  • Template:Nbt: Optional. Template:Json ref — the explosion deals no damage if this field is omitted.
  • Template:NbtTemplate:Nbt: Optional. Template:Json ref/block — blocks that fully block the explosion and can't be destroyed.
  • Template:NbtTemplate:Nbt: Optional level-based value, defaults to Template:Cd — Multiplier of the explosion knockback.
  • Template:Nbt: Optional list of 3 Template:Nbt, defaults to Template:Cd — X, Y, Z position offset to spawn the explosion.
  • Template:NbtTemplate:Nbt: level-based value — The radius of the explosion
  • Template:Nbt: Should Minecraft:fire be placed by the explosion?
  • Template:Nbt: One of Template:Cd (no effect), Template:Cd (like a bed explosion), Template:Cd (like a creeper explosion), Template:Cd (like tnt explosion), Template:Cd (like a wind-charge explosion). — How the explosion should interact with blocks.
  • Template:Nbt: The small particle the explosion emits.
    • Template:Nbt inherit/particle
  • Template:Nbt: The large particle the explosion emits.
    • Template:Nbt inherit/particle
  • Template:Nbt: Optional, particles for each air block in the radius of the explosion.
    • Template:Nbt: A block particle option.
      • Template:Nbt: The weight for this option to be chosen.
      • Template:Nbt: The particle to spawn.
        • Template:Nbt inherit/particle
      • Template:Nbt: Scaling of the distance from the center of the explosion to the block position.
      • Template:Nbt: Multiplier of the speed of the particle.
  • Template:Nbt: Template:Json ref — The sound to play.

ignite

Ignites the affected entity

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: level-based value — The duration the fire should last in seconds.

play_sound

Plays a sound

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:NbtTemplate:Nbt List of Template:Json ref to play, one for each level of enchantment. If a level is higher than the number of sounds, the last sound in the list is used.
    • Template:Nbt inherit/sound event
  • Template:NbtTemplate:Nbt: Float between Template:Cd and Template:Cd — Volume of the sound
    • Template:Nbt inherit/float provider
  • Template:NbtTemplate:Nbt: Float between Template:Cd and Template:Cd — Pitch of the sound. Values less than 0.5 are treated as 0.5.
    • Template:Nbt inherit/float provider

replace_block

Places a block

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt The block to place.
    • Template:Nbt inherit/block state provider
  • Template:Nbt: Optional list of 3 Template:Nbt, defaults to Template:Cd — X, Y, Z position offset to place the block.
  • Template:Nbt: Template:Json ref — The game event to trigger on placing the block.
  • Template:Nbt: Optional — A Minecraft:block predicate used to test if the block should be placed.
    • Template:List indent

replace_disk

Places a half-sphereTemplate:Verify.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt The block to place.
    • Template:Nbt inherit/block state provider
  • Template:Nbt: Optional list of 3 Template:Nbt, defaults to Template:Cd — X, Y, Z position offset to place the center of the disk.
  • Template:NbtTemplate:Nbt: level-based value — The radius of the disk.
  • Template:NbtTemplate:Nbt: level-based value — The height of the disk.
  • Template:Nbt: Template:Json ref — The game event to trigger on placing each block.
  • Template:Nbt: Optional — A Minecraft:block predicate used to test each position in the disk to determine if a block should be placed.
    • Template:List indent

run_function

Run a function.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt: Template:Json ref — The function to run.

set_block_properties

Sets the block properties of a block.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt: Optional list of 3 Template:Nbt, defaults to Template:Cd — X, Y, Z position offset to place the block.
  • Template:Nbt: The block state properties to apply.
    • Template:Nbt: A key-value pair, where the key is a block state key and the value is a block state value to force place for this block, for example Template:Cd.
  • Template:Nbt: Template:Json ref — The game event to trigger on modifying the block.

spawn_particles

Spawns particles.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt: The particle to spawn.
    • Template:Nbt inherit/particle
  • Template:Nbt: How to spawn the particle horizontally
    • Template:Nbt: One of Template:Cd (spawn at position of entity) or Template:Cd (spawn at random position inside the bounding box of the entity)
    • Template:Nbt: Optional, defaults to Template:Cd — Offset to the position.

      Additional field if Template:Nbt is Template:Cd:

    • Template:Nbt: Optional, defaults to Template:Cd — Scaling factor of the bounding box.
  • Template:Nbt: How to spawn the particle vertically
    • same fields as Template:Nbt.
  • Template:Nbt: The initial horizontal velocity of the particle.
    • Template:NbtTemplate:Nbt: Optional, defaults to Template:Cd — Base speed of the particle
      • Template:Nbt inherit/float provider
    • Template:Nbt: Optional, defaults to Template:Cd — Factor of the entity speed to add to the particle speed. A value of Template:Cd adds the entity speed to the particle speed.
  • Template:Nbt: The initial vertical velocity of the particle.
    • same fields as Template:Nbt.
  • Template:NbtTemplate:Nbt: Optional, defaults to Template:Cd — Speed factor of the particle.
    • Template:Nbt inherit/float provider

summon_entity

Spawns an entity.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: Template:Json ref/entity type — The entity or entities Template:More info to spawn
  • Template:Nbt: Should the summoned entity join the team of the owner of the enchanted item?

Location-based effects

All entity effects are also location-based effects. In this case the Template:Cd effect also accepts location-based effects as sub-effects. Additionally the following location-based effect exists:

attribute

Applies Minecraft:attribute modifiers to the affected entity.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt: The id of the Minecraft:attribute to modify
  • Template:NbtTemplate:Nbt: level-based value — amount to add depending on level of the enchantment
  • Template:Nbt: One of Template:Cd, Template:Cd and Template:Cd — The operation to apply, see Template:Slink
  • Template:Nbt: A Minecraft:resource location to use for this attribute modifier. Must be unique.

Level-based value

A level-based value is used in enchantment effects to use different numbers depending on the level of the enchantment.

Constant

A constant float can be used instead of a compound to set a value that doesn't depend on the level of the enchantment

• Template:Nbt A constant value

exponent

Raises the base to the specified power level.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: Level-based value indicating the base of the exponent
  • Template:NbtTemplate:Nbt: Level-based value indicating the power of the exponent

linear

The value is linearly increased (or decreased) per level. The final value is Template:Cd.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt: Value to use for a level I enchantment
  • Template:Nbt: Amount added to the value for each level above the first.

levels_squared

The value is based on the square of the level. The final value is Template:Cd

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt: Value to add to the squared level

clamped

Uses another level-based value and clamps the resulting value to the range Template:Cd.

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: level-based value — input
  • Template:Nbt: The minimum value of the output
  • Template:Nbt: The maximum value of the output

fraction

Calculates a fraction of 2 level-based values: Template:Cd

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: level-based value — numerator of the fraction
  • Template:NbtTemplate:Nbt: level-based value — denominator of the fraction

lookup

Directly defines the value for each level, with a fallback for levels that aren't directly defined

• Template:Nbt
  • Template:Nbt: Template:Cd
  • Template:Nbt: List of values to use for each level, indexed by Template:Cd
    • Template:Nbt: Value to use for level Template:Cd
    • Template:Nbt: Value to use for level Template:Cd
    • ...
  • Template:NbtTemplate:Nbt: level-based value — Value to use when Template:Nbt doesn't define a value for the given level.

See also

• Minecraft:Enchantment tag (Java Edition)