> 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/cn-er/pei-zhi/native-enchantment-effects.md).

# 原生附魔效果

根节点的 `effects` 部分用于定义 **Minecraft 原生附魔效果组件**。这些效果会作为附魔本身的一部分注册，并由 Minecraft 的常规附魔引擎处理。

对于原版附魔系统已经支持的机制，例如属性修改器、原生伤害调整、伤害免疫、攻击后效果或基于位置的方块效果，应使用 `effects`。需要 EnchantmentReform 的能力触发器、能力条件、能力修改器、能力、随机概率、冷却或状态时，应使用 [`powers`](/cn-er/pei-zhi/bian-ji-guai-wu-neng-li.md)。

一个附魔可以同时使用这两个系统。

{% hint style="warning" %}
`effects` 属于注册表数据。修改后必须**完整重启服务器**。`/enchantmentreform reload` 无法重建已经冻结的附魔注册表条目。
{% endhint %}

## `effects` 与 `powers` 对比

| 功能    | `effects`                   | `powers`                             |
| ----- | --------------------------- | ------------------------------------ |
| 执行引擎  | Minecraft 原生附魔引擎            | EnchantmentReform 运行时能力引擎            |
| 语法    | 使用 YAML 编写的原版附魔效果组件数据       | 触发器 → 条件 → 修改器 → 能力                  |
| 等级缩放  | `minecraft:linear` 等原版等级值结构 | `{level}`、变量、选择器和数学表达式               |
| 条件    | `requirements` 中的原版战利品条件谓词  | 能力条件                                 |
| 概率与冷却 | 仅在对应原生组件或效果结构支持时可用          | 通用的 `random`、`cooldown` 和 `times` 字段 |
| 重载行为  | 必须完整重启                      | 在重载功能支持的范围内，可以重新读取运行时部分              |

## 基础语法

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

`effects` 正下方的键是 Minecraft 附魔效果组件键。对应值的结构取决于该组件，可能是列表、对象、数字或其他原生数据结构。

EnchantmentReform 不会为这一部分再设计一层额外结构。插件会将 YAML 映射和列表转换为原生数据，然后传递给当前服务端版本的 `EnchantmentEffectComponents` Codec。

顶层组件键未填写命名空间时，会自动按照 `minecraft:<key>` 处理，但仍建议明确填写完整的命名空间键：

```yaml
effects:
  minecraft:attributes: []
```

嵌套标识符应始终填写完整命名空间，例如 `minecraft:max_health` 或 `enchantmentreform:my_modifier`。

## 将原版 JSON 转换为 YAML

原版附魔定义可能包含类似下面的 JSON：

```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"
      }
    ]
  }
}
```

在 YAML 中写入相同结构，并移除最外层 JSON 对象：

```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
```

转换规则如下：

* JSON 对象转换为 YAML 节点；
* JSON 数组转换为以 `-` 开头的 YAML 列表；
* 字符串、布尔值和数字保持原值；
* 空 JSON 对象转换为 `{}`；
* 带命名空间的标识符应保持不变。

## 属性效果示例

下面的附魔在 I 级时提供 `+2` 最大生命值，并且每高于 I 级一级再增加 1 点：

```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
```

### 属性字段

| 字段          | 用途                                                                                     |
| ----------- | -------------------------------------------------------------------------------------- |
| `id`        | 原生属性修改器的稳定命名空间标识符。不要为互不相关的效果重复使用同一个 ID。                                                |
| `attribute` | Minecraft 属性注册表键。                                                                      |
| `amount`    | 原生的随等级变化数值。                                                                            |
| `operation` | 原生属性运算方式。当前服务端版本支持时，可使用 `add_value`、`add_multiplied_base` 或 `add_multiplied_total` 等值。 |

附魔定义中的 `active-slots` 字段决定物品必须装备在哪些槽位，依赖装备的原生效果才会生效。

## 原生等级缩放

插件变量和数学占位符**不会在 `effects` 内展开**。不要这样填写：

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

应改用 Minecraft 原生的等级值结构：

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

对于这个线性数值：

* I 级 = `base`；
* II 级 = `base + per_level_above_first`；
* III 级 = `base + per_level_above_first × 2`。

当前服务端版本的 Codec 可能还接受其他原生等级值类型。类型名称和字段必须与对应 Minecraft 版本的原版格式一致。

## 带条件的原生效果示例

许多原生效果组件使用包含 `effect` 和可选原版战利品条件 `requirements` 的条目。

下面的示例会阻止踩在燃烧方块上造成的伤害，但不会阻止带有“绕过无敌”标签的伤害来源：

```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` 使用 Minecraft 原生战利品条件和谓词语法。它不是能力条件部分，因此不能在其中使用 `type: health_percent` 等字段。

并非每个效果组件都使用 `{ effect, requirements }` 包装结构。例如，`minecraft:attributes` 会直接使用属性条目。必须始终遵循所选组件的原版结构。

## 位置效果示例

下面的原生位置效果会将穿戴者脚下附近的熔岩替换为岩浆块：

```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
```

`offset` 必须是按照 X、Y、Z 顺序排列的三个数字坐标列表。

## 常见原生组件分类

实际可用的组件键和嵌套字段由当前 Minecraft 服务端版本决定。常见分类包括：

| 组件分类                                               | 常见用途                         |
| -------------------------------------------------- | ---------------------------- |
| `minecraft:attributes`                             | 附魔激活时添加原生属性修改器。              |
| `minecraft:damage` / `minecraft:damage_protection` | 修改造成伤害或保护计算。                 |
| `minecraft:damage_immunity`                        | 使符合条件的伤害来源无法造成伤害。            |
| `minecraft:item_damage`                            | 修改耐久消耗。                      |
| `minecraft:post_attack`                            | 攻击后执行原生实体效果。                 |
| `minecraft:tick`                                   | 附魔激活期间持续执行原生实体效果。            |
| `minecraft:location_changed`                       | 移动或位置更新后执行原生位置效果。            |
| 与弹射物相关的组件                                          | 修改弹射物数量、散布、弹药消耗、蓄力时间或其他相关行为。 |

此表并非完整的结构列表。只要当前服务端的原生附魔效果 Codec 接受，EnchantmentReform 就可以接受对应数据。

## 同时使用 `effects` 和 `powers`

原生属性效果可以与插件驱动的能力组合使用：

```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}'
```

原生属性由 `effects` 注册，击杀后的行为则由 `powers` 独立处理。

## 验证与常见错误

### 原生结构无效

如果组件键、效果类型、谓词、注册表键或必填字段无效，服务器会在启动阶段失败，并显示类似下面的错误：

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

继续阅读 Codec 错误的剩余部分，其中通常会指出无效的字段或值。

### 在原生效果中使用插件语法

以下系统不会在 `effects` 内生效：

* 能力条件；
* 能力修改器；
* 能力；
* 根节点 `variables` 和 `{level}` 数学表达式；
* `random`、`cooldown` 和 `times` 等通用能力字段。

需要这些功能时应使用 `powers`。

### 从其他 Minecraft 版本复制数据

不同 Minecraft 版本之间的原生效果组件结构可能发生变化。应从相同服务端版本的原版附魔数据或示例中复制定义。

### 缩进错误

每个组件都必须直接放在根节点 `effects` 下：

```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
```

不要把原生效果放在 `powers`、某个触发器或 `abilities` 下。

## 内置示例

默认配置在以下位置提供了实用的原生效果示例：

```
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
```

可以将这些文件作为模板，然后把组件专用字段替换为适用于当前服务端版本的值。