We're skipping an entire Minecraft drop and ended up on 1.21.5! This preview overhauls the action context parameter system by using the vanilla context instead. This version took a second because of some additional changes in Minecraft.

For a few more details regarding the split and future you can look at the roadmap to 1.21!

Changes

• Removed smithing templates.
  • This only provided the tooltip and textures, of which the former has been extracted from the behaviour entirely.

Items

• Removed #minecraft:prevent_mining_in_creative
  • Its functionality is now part of minecraft:tool.

Item Behaviour Components

• Replaced usages of entity initialisers with entity types directly.

• Removed the following item behaviour components:

  • minecraft:pointable
    • This should now be replicated with item assets in resource packs.
    • Setting the item pointer location should now be replicated with actions instead.
  • minecraft:saddle
    • This has been replaced entirely by minecraft:equipment.
  • minecraft:tinted
    • This should now be replicated with item assets in resource packs.

• Renamed minecraft:smithing_template to minecraft:smithing_template_provider.

  • It now only references the type, which was previously present in smithing templates.
  • Now only determines the textures used in a Smithing Table.
  • The tooltip is also no longer provided by the behaviour and must be placed in the item display instead.

So if you had this:

{
  "minecraft:smithing_template": {
    "template": "minecraft:bolt_pattern"
  }
}

You now have to use this:

{
  "minecraft:smithing_template_provider": "minecraft:trim_pattern"
}

minecraft:attack_blocking

• Blocks attacks when used.
• The fields are the same as the minecraft:blocks_attacks data component.

Example:

{
  "minecraft:attack_blocking": {
    "block_delay_seconds": 0.25,
    "block_sound": "minecraft:item.shield.block",
    "bypassed_by": "#minecraft:bypasses_shield",
    "disabled_sound": "minecraft:item.shield.break",
    "item_damage": {
      "base": 1.0,
      "factor": 1.0,
      "threshold": 3.0
    }
  }
}

minecraft:bucket

• The entity target in the entity field now only accepts an entity type instead of an entity initialiser.

So if you had this:

{
  "minecraft:bucket": {
    "emptying_sound_event": "minecraft:item.bucket.empty_fish",
    "entity": {
      "entity": {
        "type": "minecraft:pufferfish"
      },
      "require_other_successful_placement": true
    },
    "fluid": "minecraft:water",
    "transforms_into": "minecraft:bucket"
  }
}

You now have to use this instead:

{
  "minecraft:bucket": {
    "emptying_sound_event": "minecraft:item.bucket.empty_fish",
    "entity": {
      "entity": "minecraft:pufferfish",
      "require_other_successful_placement": true
    },
    "fluid": "minecraft:water",
    "transforms_into": "minecraft:bucket"
  }
}

minecraft:entity

• The entity field now only accepts an entity type instead of an entity initialiser.

So if you had this:

{
  "minecraft:entity": {
    "entity": {
      "type": "minecraft:oak_boat"
    }
  }
}

You now have to use this instead:

{
  "minecraft:entity": {
    "entity": "minecraft:oak_boat"
  }
}

minecraft:playable

• Renamed instruments to default_instrument and now only accepts one instrument.

minecraft:projectile

• The entity field now only accepts an entity type instead of an entity initialiser.

So if you had this:

{
  "minecraft:projectile": {
    "entity": {
      "type": "minecraft:trident"
    }
  }
}

You now have to use this instead:

{
  "minecraft:projectile": {
    "entity": "minecraft:trident"
  }
}

• Added an optional components field, which is a set of components to apply to the spawned entity.

Example:

{
  "minecraft:projectile": {
    "components": {
      "minecraft:chicken/variant": "minecraft:cold"
    },
    "entity": "minecraft:egg"
  }
}

minecraft:text_holder

• Now opens a book on use directly instead of needing an action.

minecraft:trim_material_provider

• Provides a trim material for use in recipes.
• Its value is an id pointing to a trim material.
• This value can be changed for individual item stacks in the new minecraft:provides_trim_material data component.

Example:

{
  "minecraft:trim_material_provider": "minecraft:diamond"
}

minecraft:weapon

• Renamed the damage_per_attack field to item_damage_per_attack.
• Added the disable_blocking_for_seconds field.
  • Disables blocking when used on a target wielding an item that is attack blocking.
  • Its value is a non-negative float.

Actions

• Removed action context parameters in favour of entity targets and new position targets.
  • These values need to be updated accordingly.
  • There is more information on this in the Entity Targets section below.

So if you had this:

{
  "type": "minecraft:play_sound",
  "category": "neutral",
  "pitch": 1.0,
  "position": "this",
  "sound": "minecraft:item.bottle.fill",
  "volume": 1.0
}

You now have to use this instead:

{
  "type": "minecraft:play_sound",
  "category": "neutral",
  "pitch": 1.0,
  "position": "origin",
  "sound": "minecraft:item.bottle.fill",
  "volume": 1.0
}

• Various actions gained fields for entity targets.
• Exchanging stacks now works in more places and in more contexts.
• Simplified action requirements to only take a predicate due to the migration towards context parameters.

So if you had this:

{
  "requirements": {
    "conditions": {
      "condition": "minecraft:location_check",
      "predicate": {
        "block": {
          "blocks": "minecraft:respawn_anchor"
        }
      }
    },
    "context": {
      "entity": "this",
      "position": "target"
    }
  }
}

You now have to use this instead:

{
  "requirements": {
    "condition": "minecraft:location_check",
    "position": "interacted",
    "predicate": {
      "block": {
        "blocks": "minecraft:respawn_anchor"
      }
    }
  }
}

• Removed the following actions:
  • minecraft:open_book_from_item
    • This is now part of the minecraft:text_holder item behaviour component.
  • minecraft:saddle_entity_at_position
    • This has been replaced by equipment and minecraft:equip_entity_at_position should be used instead.
  • minecraft:set_item_pointer_location
    • This has been moved to an item modifier.

minecraft:attach_leashed_entities_on_block

• Added a new field called position:
  • Its value is a position target and determines the position the leashed entities will be attached to.

minecraft:damage_item

• Removed the ignore_game_mode field.
  • The action now always takes the game mode into account.

minecraft:drop_item_from_block

• Changed the item field to take an item stack instead of an item.

minecraft:exchange_item

• Changed the item field to take an item stack instead of an item.
• Removed the components field.
  • The components are now defined in the item field instead.

So if you had this:

{
  "type": "minecraft:exchange_item",
  "components": {
    "minecraft:potion_contents": {
      "potion": "minecraft:water"
    }
  },
  "item": "minecraft:potion"
}

You now have to use this instead:

{
  "type": "minecraft:exchange_item",
  "item": {
    "id": "minecraft:potion",
    "components": {
      "minecraft:potion_contents": {
        "potion": "minecraft:water"
      }
    },
    "count": 1
  }
}

minecraft:fertilize

• Added a new field called position:
  • Its value is a position target and determines the position to fertilize.

minecraft:modify_item

• Removed the context field.
  • The item modifier now uses the exact same context as the action.
  • Added the stack field, which is an item stack target to use a specific item stack from the context.

minecraft:prime_tnt

• Does not prime tnt when the tntExplodes game rule is disabled.
• Turns any block into primed TNT now instead of just TNT.
  • The block that is primed is used for the display.
• Checking for the TNT block must be done in the action requirements now.

So if you had this:

{
  "action": {
    "type": "minecraft:prime_tnt",
    "position": "target"
  }
}

You now have to use this instead:

{
  "action": {
    "type": "minecraft:prime_tnt",
    "position": "interacted"
  },
  "requirements": {
    "condition": "minecraft:location_check",
    "position": "interacted",
    "predicate": {
      "block": {
        "blocks": "minecraft:tnt"
      }
    }
  }
}

minecraft:run_function

• Moved the entity and position fields up due to the removal of action context parameters.

So if you had this:

{
  "type": "minecraft:run_function",
  "function": "example:function",
  "context": {
    "entity": "this",
    "position": "this"
  }
}

You now have to use this instead:

{
  "type": "minecraft:run_function",
  "function": "example:function",
  "entity": "this",
  "position": "origin"
}

• Both fields are optional now and will never try to pass the parameter if not specified.

So if you only want the position context you can use this:

{
  "type": "minecraft:run_function",
  "function": "example:function",
  "position": "origin"
}

minecraft:sequence

• Now no longer incorrectly reports duplicate actions defined in the same sequence as recursive.

minecraft:swing_hand

• Added a new field called entity:
  • Its value is an entity target and determines whose hand to swing.

Predicates

• Added a minecraft:villager entity sub-predicate, which is a temporary solution that will be removed once a component predicate for a Villager's type has been added (alongside data-driven trades as those will be part of vanilla by then)
  • Fields:
    • variant, which is a Villager variant, list of Villager variants or hash-prefixed Villager variant tag and the Villager's variant must match in order to pass.

Example:

{
  "type": "minecraft:villager",
  "variant": [
    "minecraft:swamp",
    "minecraft:snow",
    "minecraft:plains"
  ]
}

minecraft:location_check

• Added a new optional field called position:
  • Its value is a position target and is the position to retrieve to use for the check.
  • Its default value is "origin" to match existing behaviour.
  • Fails if the position defined is not present in the context.

Example:

{
  "condition": "minecraft:location_check",
  "position": "interacted",
  "predicate": {
    "block": {
      "blocks": "minecraft:tnt"
    }
  }
}

Item Modifiers

minecraft:set_item_pointer_location

• Sets the minecraft:lodestone_tracker data component to the provided position.
• Fields:
  • position, which is a position target to use as the item pointer location.

Example:

{
  "function": "minecraft:set_item_pointer_location",
  "position": "interacted"
},

minecraft:split

• Splits the item stack into the original and one with the provided count.
• Fields:
  • count, which is a number provider to split the item stack into one with the provided new count.

Example:

{
  "count": 1.0,
  "function": "minecraft:split"
}

Context Parameters

Added the following context parameters from the migration:

• minecraft:side, which is the side of a block that was interacted with.
  • Passed in the minecraft:bucket item behaviour.
  • Passed in the minecraft:entity item behaviour.
  • Used in dispense behaviour to interact with the Dispenser's facing direction.
  • Used in the minecraft:side_check predicate.
  • Used in the minecraft:drop_item_from_block action.
  • Used in the minecraft:fertilize action.
  • Used in the minecraft:use_bucket action.
• minecraft:interacted_position, which is the position that the user interacted with.
  • Passed and used in various item behaviour.
  • Used in dispense behaviour to interact with the Dispenser's output position.
• minecraft:equipment_slot, which is used when an item is broken.
• minecraft:hand, which is the hand used to execute an action.
  • Passed to various item events when an item is being used.
  • Used in the minecraft:swing_hand action to swing the hand.
  • Used in the minecraft:open_book_from_item action to get the book from the executing entity.
• minecraft:target_entity, which is the entity that was interacted with.
  • Used in the minecraft:entity and minecraft:throwable item behaviour for the spawned entities.
  • Passed to the minecraft:hit_entity and minecraft:use_weapon item events for the attacked entity.
  • Passed to the minecraft:use_on_entity item event for the interacted entity.

Action context parameters were replaced with new targets to be consistent with vanilla. This means that all parameters are now passed to loot tables, item modifiers and predicates instead of having to select specific ones using action context parameters, which were removed as well. This also means that you may need to update the value of certain fields. All changes are visible below.

Entity Targets

Old	New	Context Parameter
"this"	"this"	minecraft:this_entity
"target"	"target_entity"	minecraft:target_entity

So if you had this:

{
  "type": "minecraft:set_entity_name_from_item",
  "entity": "target"
}

You now have to use this instead:

{
  "type": "minecraft:set_entity_name_from_item",
  "entity": "target_entity"
}

Position Targets

Old	New	Context Parameter
"this"	"origin"	minecraft:origin
"target"	"interacted"	minecraft:interacted_position

So if you had this:

{
  "type": "minecraft:set_block_state",
  "position": "target",
  "state": {
    "Name": "minecraft:farmland",
    "Properties": {
      "moisture": "0"
    }
  }
}

You now have to use this instead:

{
  "type": "minecraft:set_block_state",
  "position": "interacted",
  "state": {
    "Name": "minecraft:farmland",
    "Properties": {
      "moisture": "0"
    }
  }
}

Item Stack Targets

These are new and point to item stacks to use from the context. Currently the only available value is tool, which points to the minecraft:tool context parameter.

Trades

• Added an optional merchant_predicate field, which is a predicate that must pass in order for the trade to be considered of a merchant's trade set.

Fixes

• The minecraft:charge_type property now works correctly again on item assets.