The final version for 1.21! This means I can finally move to 26.x and leave this mess of a versioning system and much more behind! 🎉🎉🎉 This version expands melee weapon items significantly.

A new roadmap has been made alongside this version showing what to expect and how I will migrate to 26.x as quickly as possible. For a few more details regarding the new future you can look at the roadmap to 26.x!

Changes

Item Behaviour Components

minecraft:useable

• Added an optional effects field.
  • Its format is the same as the minecraft:use_effects data component.
  • Provides the minecraft:use_effects data component.

minecraft:weapon

• Added the types field, which is a map of melee weapon components.
  • See the Melee Weapons section for more information.
• Replaced the may_smash field with more possibilities in the new minecraft:smashing melee weapon component.
• Moved the disable_blocking_for_seconds field to the new minecraft:disables_blocking melee weapon component.

So if you had this:

{
  "minecraft:weapon": {
    "attack_damage": {
      "default_damage": 5.0,
      "rules": []
    },
    "attack_speed": 0.15,
    "may_smash": true
  }
}

You now have to use this instead:

{
  "minecraft:weapon": {
    "attack_damage": {
      "default_damage": 5.0,
      "rules": []
    },
    "attack_speed": 0.15,
    "types": {
      "minecraft:smashing": {
        "heavy_smash_attack_fall_distance": 5.0,
        "hit_sounds": {
          "in_air": "minecraft:item.mace.smash_air",
          "on_ground_large_fall_distance": "minecraft:item.mace.smash_ground_heavy",
          "on_ground_small_fall_distance": "minecraft:item.mace.smash_ground"
        },
        "knockback_power": 0.699999988079071,
        "smash_attack_fall_distance": 1.5
      }
    }
  }
}

Example from the Iron Spear:

{
  "minecraft:weapon": {
    "attack_damage": {
      "default_damage": 2.0,
      "rules": []
    },
    "attack_range": {
      "hitbox_margin": 0.125,
      "max_creative_reach": 6.5,
      "max_reach": 4.5,
      "min_creative_reach": 2.0,
      "min_reach": 2.0,
      "mob_factor": 0.5
    },
    "attack_speed": 0.2631579041481018,
    "damage_type": "minecraft:spear",
    "minimum_attack_charge": 1.0,
    "swing_animation": {
      "type": "stab",
      "duration": 19
    },
    "types": {
      "minecraft:kinetic": {
        "damage_conditions": {
          "max_duration_ticks": 225,
          "min_relative_speed": 4.6
        },
        "damage_multiplier": 0.95,
        "delay_ticks": 12,
        "dismount_conditions": {
          "max_duration_ticks": 50,
          "min_speed": 8.0
        },
        "forward_movement": 0.38,
        "hit_sound": "minecraft:item.spear.hit",
        "knockback_conditions": {
          "max_duration_ticks": 135,
          "min_speed": 5.1
        },
        "sound": "minecraft:item.spear.use"
      },
      "minecraft:piercing": {
        "hit_sound": "minecraft:item.spear.hit",
        "sound": "minecraft:item.spear.attack"
      }
    }
  }
}

• Added an optional attack_range field.
  • Determines the attack range and hitbox margin when trying to attack entities.
  • Its format is the same as the minecraft:attack_range data component.
  • Provides the minecraft:attack_range data component.
• Added an optional damage_type field.
  • Specifies the damage type the weapon deals.
  • Its format is an id pointing to a damage type.
  • Provides the minecraft:damage_type data component.
• Added an optional minimum_attack_charge field.
  • Specifies the minimum attack charge on the attack indicator required to attack with the weapon.
  • Its format is a float ranging from 0 to 1 inclusive.
  • Provides the minecraft:minimum_attack_charge data component.
• Added an optional swing_animation field.
  • Allows a different animation to be used when attacking.
  • Its format is the same as the minecraft:swing_animation data component.
  • Provides the minecraft:swing_animation data component.

Melee Weapons

Allows a melee weapon to be used in a specific way. Its value is a component map with melee weapon components.

minecraft:disables_blocking

• Provides a way to disable an attack blocking item that is being used.
• Fields:
  • seconds: A non-negative float. The amount of seconds to disable the attack blocking item for.
• The disable_blocking_for_seconds in the minecraft:weapon data component is still present and used to keep compatibility with existing data components.

Example:

{
  "minecraft:disables_blocking": {
    "seconds": 5.0
  }
}

minecraft:kinetic

• Allows this weapon to have a charging attack when using the item.
• Its format is the same as the minecraft:kinetic_weapon data component.

Example:

{
  "minecraft:kinetic": {
    "damage_conditions": {
      "max_duration_ticks": 225,
      "min_relative_speed": 4.6
    },
    "damage_multiplier": 0.95,
    "delay_ticks": 12,
    "dismount_conditions": {
      "max_duration_ticks": 50,
      "min_speed": 8.0
    },
    "forward_movement": 0.38,
    "hit_sound": "minecraft:item.spear.hit",
    "knockback_conditions": {
      "max_duration_ticks": 135,
      "min_speed": 5.1
    },
    "sound": "minecraft:item.spear.use"
  }
}

minecraft:piercing

• Allows this weapon to damage multiple entities along a ray instead of a single entity.
• Its format is the same as the minecraft:piercing_weapon data component.

Example:

{
  "minecraft:piercing": {
    "hit_sound": "minecraft:item.spear.hit",
    "sound": "minecraft:item.spear.attack"
  }
}

minecraft:smashing

• Allows this weapon to attack entities by falling on them.
• Fields:
  • hit_sounds: A map with sounds. The sounds to play when hitting entities with a smashing attack.
    • in_air: A sound event. The sound to play when airborne.
    • on_ground_small_fall_distance: A sound event. The sound to play when dealing a regular smashing attack.
    • on_ground_large_fall_distance: A sound event. The sound to play when dealing a heavy smashing attack.
  • smash_attack_fall_distance: A positive double. The minimum distance required to fall to deal a smashing attack.
  • heavy_smash_attack_fall_distance: A positive double. The minimum distance required to fall to deal a heavy smashing attack.
  • knockback_power: A positive double. The maximum knockback power to deal to nearby entities when dealing a smashing attack.

Example:

{
  "minecraft:smashing": {
    "heavy_smash_attack_fall_distance": 5.0,
    "hit_sounds": {
      "in_air": "minecraft:item.mace.smash_air",
      "on_ground_large_fall_distance": "minecraft:item.mace.smash_ground_heavy",
      "on_ground_small_fall_distance": "minecraft:item.mace.smash_ground"
    },
    "knockback_power": 0.699999988079071,
    "smash_attack_fall_distance": 1.5
  }
}

Data Components

• Added the following data components:
  • minecraft:smashing_weapon

minecraft:smashing_weapon

• Specified and used by the minecraft:smashing melee weapon component in the minecraft:weapon behaviour component.
• If removed, no smash attack will be applied.
• Its value is the same as the one specified in the minecraft:smashing melee weapon component.

Example:

{
  "heavy_smash_attack_fall_distance": 5.0,
  "hit_sounds": {
    "in_air": "minecraft:item.mace.smash_air",
    "on_ground_large_fall_distance": "minecraft:item.mace.smash_ground_heavy",
    "on_ground_small_fall_distance": "minecraft:item.mace.smash_ground"
  },
  "knockback_power": 0.699999988079071,
  "smash_attack_fall_distance": 1.5
}

Predicates

Item Predicates

• Removed the data_components field in favour of vanilla's component predicates.

So if you had this:

{
  "data_components": [
    "minecraft:bees"
  ]
}

You now have to use this instead:

{
  "predicates": {
    "minecraft:bees": {}
  }
}

Fixes

• Skeleton-like entities can now use any direct shooter instead of just Bows.
• Piglins and Pillagers can now use any chargeable shooter instead of just Crossbows.
• Melee weapons now correctly do not apply item damage when attacking an entity in creative mode.
• The correct sounds are now played when using a smashing weapon.