Documentation navigation

Custom Enchantments

Define custom enchantments with item profiles, enchantment slots, effects, and special abilities.

Using Datapacks you are able to create your own custom enchantments, this is already possible in Vanilla, but thanks to Vanilla Squareds new special enchantments, you are able to easily incorporate a keybind with cooldown bar and limits into your enchantments. I have to admit this part is heavily undertested and likely might not work in every case so please report any bugs to us on the bug tracker. I will try to fix them as soon as possible. This article will go over how to define custom enchantments, it will go through each and every one of the new enchantment effects added by the mod itself and also showcase how to implement special enchantments.

For further documentation on the Vanilla parts of custom enchantments, please check out the Minecraft Wiki page for custom enchantments.

Enchantment definitions are data-pack files. Place them at:

data/<namespace>/enchantment/<path>.json

The file data/example/enchantment/whirlwind.json has the enchantment ID example:whirlwind.

JSON format

The top-level fields description, supported_items, primary_items, weight, and anvil_cost use the vanilla enchantment format. Vanilla Squared moves the remaining settings into profiles.

  • The enchantment definition.
    • description: A text component that is used to display the enchantment on items.
    • supported_items: An item ID or item tag beginning with #.
    • primary_items (optional): Items on which the enchantment may appear through normal enchanting.
    • weight: Selection weight used by random enchanting. (Unused due to Vanilla Squareds custom enchanting table)
    • anvil_cost: Anvil cost multiplier.
    • profiles: Item-specific definitions. The first matching profile is used.
      • An enchantment profile.
        • requirement (optional): Restricts this profile to an item or item tag.
          • type: item for the enchanted item, or projectile_takeover for the item which fired a projectile.
          • item: An item ID or item tag beginning with #.
        • enchantment_slot: special, damage, secondary, defense, util, or curse.
        • exclusive_set (optional): Enchantments incompatible with this profile.
        • max_level: Maximum level, from 1 to 255.
        • effects (optional): Enchantment Effect Components.
          • <component ID>: An effect component
            • Fields depending on the component
        • special (optional): Makes the profile activatable with the special-enchantment key.
          • cooldown: Cooldown in seconds. Accepts a constant or level-based value.
          • display_limit (optional): effect_id — which effects uses should be displayed in the bar. (not defined = none)
          • cooldown_after_limit (optional): Delays the cooldown until this effect's uses are exhausted.
        • slots: List of Equipment Slots that this enchantment works in.
          • one of any, hand, mainhand, offhand, armor, feet, legs, chest, head, body, saddle — a slot
        • min_cost: A level-based value — Minimum enchanting cost.
        • max_cost: A level-based value — Maximum enchanting cost.

Use separate profiles when an enchantment needs different effects or slot types on different items. Put the most specific profile first because only the first match is selected.

projectile_takeover lets an enchantment on another equipped item provide effects for a projectile source. For example, an enchantment on a helmet could alter arrows fired from a bow matching the profile's item field.

Special enchantments

A profile containing special is activated with the Special Enchantment key, which is Left Alt by default. The main-hand enchantment takes priority over the off-hand enchantment. Its cooldown and use count are shown above the hotbar.

Every entry in an effects array must have a unique effect_id. Add special to an effect entry when it should have a limited number of uses during one activation:

{
  "effect_id": "whirlwind_use",
  "special": {
    "limit": 1
  },
  "effect": {
    "type": "vsq:begin_swirling",
    "duration": 3,
    "radius": 3,
    "damage": {
      "damage_type": "minecraft:player_attack",
      "amount": 4
    }
  },
  "enchanted": "attacker",
  "affected": "attacker"
}

limit accepts a constant or a level-based value. If omitted inside the effect's special object, it defaults to 1. Effects without this object do not consume a use, but still require the special profile to be active.

Example enchantment

Create data/example/enchantment/whirlwind.json:

{
  "description": {
    "text": "Whirlwind"
  },
  "supported_items": "minecraft:diamond_sword",
  "primary_items": "minecraft:diamond_sword",
  "weight": 2,
  "anvil_cost": 4,
  "profiles": [
    {
      "requirement": {
        "type": "item",
        "item": "minecraft:diamond_sword"
      },
      "enchantment_slot": "special",
      "max_level": 1,
      "effects": {
        "vsq:swirling": [
          {
            "enchanted": "attacker",
            "affected": "attacker",
            "effect_id": "whirlwind_use",
            "special": {
              "limit": 1
            },
            "effect": {
              "type": "vsq:begin_swirling",
              "duration": 3,
              "warmup_duration": 0.25,
              "radius": 3,
              "hit_interval": 4,
              "damage": {
                "damage_type": "minecraft:player_attack",
                "amount": 4
              }
            }
          }
        ]
      },
      "special": {
        "cooldown": 8,
        "display_limit": "whirlwind_use"
      },
      "slots": [
        "mainhand"
      ],
      "min_cost": {
        "base": 10,
        "per_level_above_first": 0
      },
      "max_cost": {
        "base": 30,
        "per_level_above_first": 0
      }
    }
  ]
}

Run /reload or rejoin your world, after that, run this command:

/enchant @s example:whirlwind 1

Added effect components

Vanilla effect components remain available inside each profile. If you want to know more about those, checkout the mc wiki.s

vsq:swirling

Runs when the player presses the special-enchantment key.

  • The vsq:swirling component.
    • A targeted entity effect.
      • effect_id: Unique ID used by special limits and the cooldown display.
      • enchanted: attacker or damaging_entity. victim is not available for this component.
      • affected: attacker or damaging_entity. Both resolve to the player using the ability.
      • effect: The entity effect to run.
      • requirements (optional): A vanilla loot condition.
      • special (optional): Use limit for this effect.
        • limit (optional): Constant or a level-based value. Defaults to 1.

vsq:post_block

Runs after an attack is blocked. It uses the same targeted-effect structure as minecraft:post_attack.

  • The vsq:post_block component.
    • A targeted entity effect.
      • effect_id: Unique effect ID.
      • enchanted: attacker when used by the weapon, or victim when used by the blocking item.
      • affected: attacker, damaging_entity, or victim.
      • effect: The entity effect to run.
      • requirements (optional): A vanilla loot condition evaluated against the blocked attack.
      • special (optional): Use limit for special profiles.

vsq:channeling_path

Runs while a vsq:channeling effect travels to another target.

  • The vsq:channeling_path component.
    • A targeted location effect.
      • effect_id: Unique effect ID.
      • enchanted: attacker, damaging_entity, or victim.
      • affected: attacker, damaging_entity, or victim.
      • effect: The location effect applied along the channeling path.
      • requirements (optional): A vanilla loot condition.
      • special (optional): Use limit for special profiles.

Added entity effects

These objects are placed directly in an effect entry's effect field. They may also be nested inside a minecraft:all_of effect.

vsq:begin_swirling

Starts an area attack around the affected entity. Durations are measured in seconds.

  • The vsq:begin_swirling entity effect.
    • type: Must be vsq:begin_swirling.
    • duration: Duration as a constant or level-based value.
    • warmup_duration (optional): Delay before the first hit. Defaults to 0.35.
    • radius: Effect radius. Values are clamped from 0 to 16.
    • hit_interval (optional): Ticks between hits. Defaults to 4 and has a minimum of 1.
    • damage: Damage dealt by each hit.
      • damage_type: Damage type ID.
      • amount: Damage amount.

vsq:begin_lunging

Launches the affected entity in its facing direction.

  • The vsq:begin_lunging entity effect.
    • type: Must be vsq:begin_lunging.
    • direction (optional): Local [x, y, z] direction added to the entity's look direction. Defaults to [0, 0, 1].
    • coordinate_scale (optional): [x, y, z] multiplier applied to the direction. Defaults to [1, 1, 1].
    • magnitude: Launch strength as a constant or level-based value.
    • speed (optional): Speed multiplier. Defaults to 1.
    • damage_taken_multiplier (optional): Incoming damage multiplier while lunging. Defaults to 1.
    • range: Maximum travel range. Values are clamped from 0 to 7.

vsq:channeling

Creates a path through matching entities, starting from the affected entity.

  • The vsq:channeling entity effect.
    • type: Must be vsq:channeling.
    • algorithm: Vanilla entity predicate used to select targets.
    • target_limit: Maximum targets as a constant or level-based value.
    • block_limit (optional): Maximum path length through blocks. Defaults to 16.
    • particle_path (optional): Particle path ID. Defaults to vsq:lightning.
    • duration: Path duration as a constant or level-based value.
    • pass_through: Block ID or block tag beginning with # through which the path may travel.

vsq:send_chat_msg

Sends a system message to the affected player, or to the enchanted entity when the affected entity is not a player.

  • The vsq:send_chat_msg entity effect.
    • type: Must be vsq:send_chat_msg.
    • message (optional): Message to send. $a inserts the affected entity, $e the enchanted entity, and $i the enchanted item.