> For the complete documentation index, see [llms.txt](https://axiomemu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axiomemu.gitbook.io/docs/data/plugins/itemeffect.md).

# ItemEffect

Defines custom right-clickable items that apply timed buff effects (XP bonus, drop rate, damage, defense, etc.) when consumed. Server-authoritative; the client receives display data (name, description, icon) via GameDataSync.

## File Location

```
Data/Plugins/Items/ItemEffect.xml
```

Loaded once at GameServer startup. Supports hot reload via plugin admin command.

{% hint style="warning" %}
ItemEffectPlugin is a paid (license-gated) plugin. Creating new effects works only while the license is active on the GameServer.
{% endhint %}

## Schema

```xml
<ItemEffectList>
    <Effect Index="..." ItemIndex="..." Group="..." IconIndex="..." Count="..." Save="..."
            ExpRate="..." MasterExpRate="..." AddDamage="..." AddDefense="..." AddDropRate="..."
            Name="..." Description="..." />
</ItemEffectList>
```

## Attributes

| Attribute       | Type          | Effect                                                                                                                                                                                                                  |
| --------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Index`         | 220-255       | Unique effect ID. Range reserved for ItemEffect plugin                                                                                                                                                                  |
| `ItemIndex`     | int           | Item that triggers this effect. `Category * 512 + Slot`                                                                                                                                                                 |
| `Group`         | int           | Effects sharing a Group are mutually exclusive; new one replaces old. Use the same Group for tier variants (e.g. XP Scroll I, II, III)                                                                                  |
| `IconIndex`     | int           | Buff icon shown above the player. Pulled from the client buff-icon table. Examples: `29` Seal of Ascension, `30` Seal of Wealth, `31` Seal of Sustenance, `87` Seal of Life, `88` Seal of Mana, `195` Blessing of Light |
| `Count`         | seconds       | Duration. `1800` = 30 minutes                                                                                                                                                                                           |
| `Save`          | 0 or 1        | `1` persists across logout, `0` clears on disconnect                                                                                                                                                                    |
| `ExpRate`       | int %         | Experience gain bonus                                                                                                                                                                                                   |
| `MasterExpRate` | int %         | Master experience gain bonus                                                                                                                                                                                            |
| `AddDamage`     | int           | Flat damage bonus (applied to physical + magic + curse)                                                                                                                                                                 |
| `AddDefense`    | int           | Flat defense bonus                                                                                                                                                                                                      |
| `AddDropRate`   | int per-mille | Drop rate bonus. `10` = +1%                                                                                                                                                                                             |
| `Name`          | string        | Display name shown in the buff tooltip header. Up to 63 characters                                                                                                                                                      |
| `Description`   | string        | Tooltip body. Up to 255 characters. Use `%%` for a literal `%`                                                                                                                                                          |

## Group Semantics

Two effects with the same `Group` value cannot coexist on the same character. Consuming a higher-tier scroll while a lower-tier is active replaces it. Consuming the same tier refreshes the timer.

## Item Category Requirement

The triggering item must be in the consumables category for the right-click use handler to route it to the plugin. Consumables live in Category 14 in the item catalog.

## Index Range

Indices must be in `[220-255]`. Outside this range the engine ignores the effect. Up to 36 distinct effects at a time.

## Cross-File Dependencies

| Attribute        | Related in                                                     |
| ---------------- | -------------------------------------------------------------- |
| `ItemIndex`      | [Item.xml](/docs/data/item/item.md)                            |
| `IconIndex`      | Client buff-icon table (matches the client binary)             |
| Paid plugin gate | Requires an active license that includes the ItemEffect module |

## Common Issues

* **Effect does not trigger when item is used** - item not flagged as right-clickable in Item.xml, or the plugin's license is not active
* **Buff icon wrong** - `IconIndex` does not match any entry in the client buff-icon table
* **Buff disappears on logout** - `Save="0"`; set to `1` for persistent buffs
* **Two scrolls both active at once** - they have different `Group` values. Assign the same `Group` to make them mutually exclusive
* **`AddDropRate="100"` only adds 10%** - value is per-mille, not percent. For +10% use `AddDropRate="100"`; for +1% use `AddDropRate="10"`
* **Effect index outside 220-255 silently dropped** - pick an index within the reserved range