✨Native Enchantment Effects

The root effects section defines Minecraft-native enchantment effect components. These effects are registered as part of the enchantment itself and are handled by Minecraft's normal enchantment engine.

Use effects for mechanics that already exist in the vanilla enchantment system, such as attribute modifiers, native damage changes, damage immunity, post-attack effects, or location-based block effects. Use powers when you need EnchantmentReform triggers, Power Conditions, Power Modifiers, Abilities, random chances, cooldowns, or state.

An enchantment may use both systems at the same time.

effects is registry data. Changes require a full server restart. /enchantmentreform reload cannot rebuild an already-frozen enchantment registry entry.

effects compared with powers

Feature	effects	powers
Execution engine	Minecraft's native enchantment engine	EnchantmentReform's runtime power engine
Syntax	Vanilla enchantment effect-component data written as YAML	Trigger → condition → modifier → ability
Level scaling	Vanilla level-based values such as minecraft:linear	{level}, variables, selectors, and math expressions
Conditions	Vanilla loot-condition predicates in requirements	Power Conditions
Chance and cooldown	Only when supported by the native component/effect schema	Common random, cooldown, and times fields
Reload behavior	Full restart required	Runtime sections may be re-read where reload supports them

Base syntax

effects:
  minecraft:<effect_component>:
    <value required by that Minecraft component>

The key directly below effects is a Minecraft enchantment effect-component key. The value's shape depends on that component: it may be a list, an object, a number, or another native data structure.

EnchantmentReform does not invent another nested schema for this section. It converts the YAML maps and lists into native data and passes them to the current server's EnchantmentEffectComponents codec.

Top-level component keys without a namespace are automatically treated as minecraft:<key>, but explicit namespaced keys are recommended:

effects:
  minecraft:attributes: []

Nested identifiers should always be written with their full namespace, for example minecraft:max_health or enchantmentreform:my_modifier.

Converting vanilla JSON to YAML

A vanilla enchantment definition may contain JSON similar to:

{
  "effects": {
    "minecraft:attributes": [
      {
        "id": "enchantmentreform:example_health",
        "attribute": "minecraft:max_health",
        "amount": {
          "type": "minecraft:linear",
          "base": 2.0,
          "per_level_above_first": 1.0
        },
        "operation": "add_value"
      }
    ]
  }
}

Write the same structure in YAML and remove the outer JSON object:

effects:
  minecraft:attributes:
    - id: enchantmentreform:example_health
      attribute: minecraft:max_health
      amount:
        type: minecraft:linear
        base: 2.0
        per_level_above_first: 1.0
      operation: add_value

Conversion rules:

• JSON objects become YAML sections.

• JSON arrays become YAML lists beginning with -.

• Strings, booleans, and numbers keep the same values.

• Empty JSON objects become {}.

• Namespaced identifiers should remain unchanged.

Attribute effect example

The following enchantment grants +2 maximum health at level I and one additional point for every level above I:

active-slots:
  - ARMOR

max-level: 5

effects:
  minecraft:attributes:
    - id: enchantmentreform:vitality
      attribute: minecraft:max_health
      amount:
        type: minecraft:linear
        base: 2.0
        per_level_above_first: 1.0
      operation: add_value

Attribute fields

Field	Purpose
id	Stable namespaced identifier for the native attribute modifier. Avoid reusing the same ID for unrelated effects.
attribute	Minecraft attribute registry key.
amount	Native level-based value.
operation	Native attribute operation, such as add_value, add_multiplied_base, or add_multiplied_total, when supported by the current server version.

The active-slots field in the enchantment definition determines where the enchantment must be equipped for equipment-dependent native effects to apply.

Native level scaling

Plugin variables and math placeholders are not expanded inside effects. Do not write:

effects:
  minecraft:attributes:
    - id: enchantmentreform:wrong_example
      attribute: minecraft:max_health
      amount: '{level} * 2' # Not a Power expression here.
      operation: add_value

Use Minecraft's native level-based value format instead:

amount:
  type: minecraft:linear
  base: 2.0
  per_level_above_first: 2.0

For this linear value:

• level I = base;

• level II = base + per_level_above_first;

• level III = base + per_level_above_first × 2.

Other native level-based value types may be accepted by the current server version's codec. Their names and fields must match the vanilla format for that exact Minecraft version.

Conditional native effect example

Many native effect components use entries containing an effect and optional vanilla loot-condition requirements.

This example prevents damage caused by stepping on a burning block, unless the damage source bypasses invulnerability:

effects:
  minecraft:damage_immunity:
    - effect: {}
      requirements:
        condition: minecraft:damage_source_properties
        predicate:
          tags:
            - expected: true
              id: minecraft:burn_from_stepping
            - expected: false
              id: minecraft:bypasses_invulnerability

requirements uses Minecraft's native loot-condition and predicate syntax. It is not a Power Conditions section, so fields such as type: health_percent cannot be used there.

Not every effect component uses the { effect, requirements } wrapper. For example, minecraft:attributes uses attribute entries directly. Always follow the vanilla schema of the selected component.

Location effect example

The following native location effect replaces nearby lava below the wearer with magma blocks:

active-slots:
  - FEET

effects:
  minecraft:location_changed:
    - effect:
        type: minecraft:replace_disk
        block_state:
          type: minecraft:simple_state_provider
          state:
            Name: minecraft:magma_block
        height: 1.0
        offset:
          - 0
          - -1
          - 0
        predicate:
          type: minecraft:all_of
          predicates:
            - type: minecraft:matching_block_tag
              offset:
                - 0
                - 1
                - 0
              tag: minecraft:air
            - type: minecraft:matching_blocks
              blocks: minecraft:lava
            - type: minecraft:matching_fluids
              fluids: minecraft:lava
        radius:
          type: minecraft:linear
          base: 3.0
          per_level_above_first: 1.0
        trigger_game_event: minecraft:block_place
      requirements:
        condition: minecraft:entity_properties
        entity: this
        predicate:
          flags:
            is_on_ground: true

An offset must be a list of three numeric coordinates in X, Y, Z order.

Common native component categories

The exact available component keys and nested fields are controlled by the current Minecraft server version. Common categories include:

Component category	Typical purpose
minecraft:attributes	Add native attribute modifiers while the enchantment is active.
minecraft:damage / minecraft:damage_protection	Modify outgoing damage or protection calculations.
minecraft:damage_immunity	Make matching damage sources deal no damage.
minecraft:item_damage	Modify durability consumption.
minecraft:post_attack	Execute native entity effects after an attack.
minecraft:tick	Execute a native entity effect while active.
minecraft:location_changed	Execute a native location effect after movement or location updates.
Projectile-related components	Modify projectile count, spread, ammunition use, charge time, or related behavior.

This table is intentionally not an exhaustive schema. EnchantmentReform accepts whatever the current server's native enchantment-effect codec accepts.

Using effects and powers together

A native attribute can be combined with a plugin-driven ability:

max-level: 3
active-slots:
  - HAND

variables:
  kill-heal: '1 + {level}'

effects:
  minecraft:attributes:
    - id: enchantmentreform:hybrid_attack_speed
      attribute: minecraft:attack_speed
      amount:
        type: minecraft:linear
        base: 0.1
        per_level_above_first: 0.05
      operation: add_value

powers:
  on-kill:
    abilities:
      heal:
        type: set_health
        target: SOURCE
        amount: '{health} + {kill-heal}'

The native attribute is registered from effects; the kill behavior is handled independently by powers.

Validation and common errors

Invalid native schema

If a component key, effect type, predicate, registry key, or required field is invalid, server bootstrap fails with an error similar to:

example.yml: invalid native enchantment effects: ...

Read the remainder of the codec error: it normally identifies the invalid field or value.

Using plugin syntax inside native effects

The following systems do not apply inside effects:

• Power Conditions;

• Power Modifiers;

• Abilities;

• root variables and {level} math expressions;

• common power fields such as random, cooldown, and times.

Use powers when these features are required.

Copying data from another Minecraft version

Native effect-component schemas can change between Minecraft versions. Copy definitions from vanilla enchantment data or examples made for the same server version.

Incorrect indentation

Every component belongs directly under the root effects section:

effects:
  minecraft:attributes:
    - id: enchantmentreform:example
      attribute: minecraft:max_health
      amount:
        type: minecraft:linear
        base: 1.0
        per_level_above_first: 1.0
      operation: add_value

Do not place native effects under powers, a trigger, or abilities.

Bundled examples

The default configuration includes practical native-effect examples in:

plugins/EnchantmentReform/enchantments/armor/vitality.yml
plugins/EnchantmentReform/enchantments/armor/jump_boost.yml
plugins/EnchantmentReform/enchantments/tools/entity_reach.yml
plugins/EnchantmentReform/enchantments/armor/lava_walker.yml

Use those files as templates and then replace the component-specific fields with values valid for your server version.