> 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/custom-items.md).

# Custom Items

Every `.yml` file in `plugins/EnchantmentReform/items` defines one custom item. The file name without `.yml` is its ID. Legacy root-level ItemFormat and `{ item: ... }` definitions are not supported.

```yaml
base-item:
  material: GOLDEN_HELMET
  name: '{lang:custom-item-night_vision_helmet-name}'
  lore:
    - '{lang:custom-item-night_vision_helmet-lore}'
    - '<gray>Armor: <white>{attribute:minecraft:armor}'
    - '<gray>Hunger slowdown: <white>{attribute:custom_attribute:hunger_slowdown}'

variables:
  armor-roll: 'random(1, 3)'

base-attributes:
  minecraft:armor: '{armor-roll} + 1'
  custom_attribute:hunger_slowdown: '80 + random(0, 20)'

active-slots:
  - HEAD

allow-duplicate: false

powers:
  on-tick:
    interval: 10
    abilities:
      night-vision:
        type: potion_effect
        target: SOURCE
        potion: minecraft:night_vision
        duration: 30
        particles: false
```

## Fields

| Field                | Default  | Description                                                                                           |
| -------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `enabled`            | `true`   | Whether this custom item definition is loaded.                                                        |
| `base-item`          | required | The [ItemFormat™](/for-enchantmentreform/shared-formats/itemformat-tm.md) used to build the item.     |
| `base-attributes`    | empty    | Vanilla and custom attribute modifiers supplied by the item. Uses the format described below.         |
| `active-slots`       | required | Equipment slots in which the item activates its powers.                                               |
| `allow-duplicate`    | `false`  | Allows each equipped copy to execute its powers separately.                                           |
| `execution-priority` | `0`      | Execution order relative to other active power sources. Higher values execute first.                  |
| `variables`          | empty    | Variables shared by the item's power configuration.                                                   |
| `powers`             | required | Uses the same trigger, condition, modifier, and ability format as enchantments and custom attributes. |

Valid active slots are `HAND`, `OFF_HAND`, `HEAD`, `CHEST`, `LEGS`, `FEET`, `ARMOR`, and `ANY`. `ARMOR` covers all four armor slots. `ANY` covers every supported equipment slot.

## Base attributes

Each key below `base-attributes` is an attribute ID and its value is a number or mathematical expression. Use `minecraft:<id>` for a vanilla attribute. Custom attributes accept a bare ID, `custom_attribute:<id>`, or `enchantmentreform:<id>`; explicit `custom_attribute:` is recommended when a name could be ambiguous. Every entry uses `ADD_NUMBER`, and its equipment slot is selected automatically from the item material.

Values use the same numeric pipeline as powers: `{level}` (always `1` for a custom item), root `variables`, build arguments, PlaceholderAPI values when a player is available, mathematical expressions, `2~5` ranges, and functions such as `random(1, 5)` are supported. Each expression is evaluated exactly once when the item is generated.

The calculated result for every vanilla and custom attribute is stored as a `DOUBLE` in the item's PDC. Cloning or moving the item preserves the roll. Reloading or changing the configuration does not reroll existing items; generate a new item to apply new formulas.

Use `{attribute:<attribute ID>}` in `base-item.name`, `base-item.item-name`, or `base-item.lore` to display the generated value. The ID in the placeholder must match the key under `base-attributes`, for example `{attribute:minecraft:armor}`. Display values use the same compact number formatting as descriptions.

Vanilla modifiers are written into the generated item's `ItemMeta`, preserving its material's default modifiers, and their calculated values are also stored in PDC.

Custom-attribute modifiers read their calculated values from item PDC while an identified custom item is actually held or equipped in its automatic slot. They affect the final attribute value and description, appear in the attribute GUI, disappear immediately when the item is removed, and are never written to player PDC.

## Identity and power activation

Items built from a definition receive a persistent custom-item ID. Merely recreating the same material, name, and lore does not make another item a custom item.

When a player holds or wears the item in a configured active slot, its powers join that player's active power sources. With `allow-duplicate: false`, only one copy of the same definition executes. With `allow-duplicate: true`, every copy in a matching slot executes separately.

The value passed to the power as `{level}` is `1`.

## Default custom item

When the `items` directory is empty, EnchantmentReform extracts `night_vision_helmet.yml`. Wearing this Golden Helmet in the head slot continuously provides Night Vision. Its name and lore use `{lang:...}` placeholders from the language files.

## Creating and giving custom items

The following commands operate on the new custom-item definitions:

```
/enchantmentreform saveitem <id> [bukkit|itemformat]
/enchantmentreform givesaveitem <id> [player] [amount]
/enchantmentreform generateitemformat
```

`saveitem` creates an `items/<id>.yml` definition from the item in the player's main hand. It creates `active-slots: [HAND]` and an empty `powers` section, which can then be edited. `givesaveitem` builds the configured item and writes its persistent custom-item ID before giving it.

`generateitemformat` converts the main-hand item to a standalone ItemFormat and writes it to `plugins/EnchantmentReform/generated-item-format.yml`. It does not create a custom-item definition.

After manually changing a definition, reload EnchantmentReform before testing it.