> 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/gong-neng/custom-attributes.md).

# 自定义属性

`plugins/EnchantmentReform/attributes` 中的每个 `.yml` 文件定义一个持久化的玩家整数属性。基础值和持久 modifier 保存在玩家 PDC 中，应用 modifier 后的最终值会作为 `{level}` 传递给配置的 Power。

```yaml
name: '{lang:custom-attribute-hunger_slowdown-name}'
description: '{lang:custom-attribute-hunger_slowdown-description}'

minimum-value: 0
maximum-value: 1000
default-value: 0

skip-power-at-default-value: true
skip-power-at-zero: true

variables:
  prevention_chance: '%:{level} / 10'

powers:
  on-food-level-change:
    conditions:
      food-decreased:
        type: food_change
        compare: '<'
        value: 0
    modifiers:
      slow-hunger-loss:
        type: food
        operation: ADD
        value: 1
        random: '{level} / 1000'
```

## 配置项

| 配置项                           | 默认值        | 说明                                                                             |
| ----------------------------- | ---------- | ------------------------------------------------------------------------------ |
| `name`                        | 文件 ID      | 显示名称，支持 `{lang:...}`。                                                          |
| `description`                 | 无          | 可选描述，支持 `{lang:...}`、`{level}` 和 `variables` 中的变量；描述里的 `{level}` 是查看者当前的最终属性值。 |
| `minimum-value`               | `0`        | 可以保存的最小值。                                                                      |
| `maximum-value`               | Java 整数最大值 | 可以保存的最大值。                                                                      |
| `default-value`               | `0`        | 玩家没有 PDC 数据时返回的基础值。                                                            |
| `skip-power-at-default-value` | `false`    | 最终值等于 `default-value` 时不把该属性加入 Power 执行。                                       |
| `skip-power-at-zero`          | `false`    | 最终值为零时不把该属性加入 Power 执行。                                                        |
| `variables`                   | 无          | 描述与 Power 共用的数值/公式变量，语法与附魔变量相同。                                                |
| `powers`                      | 必填         | 与附魔和自定义物品使用相同的触发器、条件、修改器及能力格式。                                                 |

基础值和最终值超出范围时会自动限制到最小值或最大值。所有 operation 计算完毕后，最终值会四舍五入为整数。即使默认值正好是零，两个跳过选项仍然分别生效。

描述会按照玩家当前的最终属性值渲染，因此基础值或 modifier 改变后，描述也会随之更新。在描述公式前添加 `%:` 可以在计算后自动追加百分号；例如属性值为 `500` 时，`'%:{level} / 10'` 会显示为 `50%`。

## Modifier

每个 modifier 包含一个命名空间 ID、一个可带小数的 amount 和一个 operation。计算顺序如下：

1. `ADD_VALUE`：直接加上 amount。
2. `ADD_MULTIPLIED_BASE`：加上“基础值 × amount”。
3. `ADD_MULTIPLIED_TOTAL`：把累计结果乘以 `1 + amount`；存在多个时依次相乘。

例如基础值为 `100`，同时拥有 `ADD_VALUE 20`、`ADD_MULTIPLIED_BASE 0.5` 和 `ADD_MULTIPLIED_TOTAL 0.1`，最终结果为 `(100 + 20 + 100 × 0.5) × 1.1 = 187`。

指令创建的 modifier 会持久化到玩家 PDC。`refresh_attribute` 创建的临时 modifier 只存在于运行时，并会在到期、附魔/自定义物品来源失效或 ability 卸载时移除。

内置 `hunger_slowdown` 属性范围为 `0..1000`。数值为 `500` 时，每次正常降低饱食度约有 50% 概率被阻止；数值为 `1000` 时会阻止常规的单点饱食度降低。`attributes` 目录为空时会自动释放该配置。

内置 `liquid_surface_breathing_distance` 属性范围为 `0..64`。玩家眼睛在水或岩浆中，并且到正上方同一液体表面的距离不超过属性值时，不会损失空气值。这个效果完全由属性 YAML 中的 `on-air-change` Power、`air_change` 条件、`liquid_surface_distance` 条件和 `air` 修改器驱动，没有绑定该属性 ID 的专用监听器。此配置文件缺失时会自动释放，但不会覆盖已有文件。

代码可以通过 `AttributeManager.attributeManager` 使用 `getBaseValue`、最终值 `getValue`、`setValue`、`addValue`、`resetValue`、`getModifiers`、`addModifier`、`setModifier` 和 `removeModifier`。

管理员可以通过以下指令修改在线玩家的属性值：

```
/enchantmentreform setattribute <玩家> <属性> <值>
/enchantmentreform addattribute <玩家> <属性> <增量>
/enchantmentreform addattributemodifier <玩家> <属性> <modifier-id> <amount> <operation>
/enchantmentreform setattributemodifier <玩家> <属性> <modifier-id> <amount> <operation>
```

`setattribute` 和 `addattribute` 修改基础值。`addattributemodifier` 与原版添加 modifier 的行为一致，遇到已存在的 ID 会拒绝执行；`setattributemodifier` 会创建或覆盖该 ID。

玩家可以使用 `/enchantmentreform attributegui` 查看全部自定义属性，包括自己的基础值、最终值、范围和当前 modifier。

安装 PlaceholderAPI 后，`%enchantmentreform_attribute_<id>%` 会显示玩家的当前属性值。例如 `%enchantmentreform_attribute_hunger_slowdown%` 显示 `hunger_slowdown` 的值。

`set_attribute` 和 `refresh_attribute` ability 同时接受 Bukkit 属性与自定义属性 ID。自定义属性可以写成 `hunger_slowdown`、`custom_attribute:hunger_slowdown` 或 `enchantmentreform:hunger_slowdown`；其目标必须是玩家。`set_attribute` 修改基础值，`refresh_attribute` 应用临时 modifier，并同时接受上面的新 operation 名称和旧 Bukkit 名称。