> For the complete documentation index, see [llms.txt](https://enchantedmobs.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://enchantedmobs.superiormc.cn/for-enchantmentreform/configs/native-enchantment-effects.md). # 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`](/for-enchantmentreform/configs/bian-ji-guai-wu-neng-li.md) 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. {% hint style="warning" %} `effects` is registry data. Changes require a **full server restart**. `/enchantmentreform reload` cannot rebuild an already-frozen enchantment registry entry. {% endhint %} ## `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 ```yaml effects: minecraft:: ``` 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:`, but explicit namespaced keys are recommended: ```yaml 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: ```json { "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: ```yaml 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: ```yaml 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: ```yaml 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: ```yaml 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: ```yaml 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: ```yaml 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: ```yaml 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: ```yaml 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.