ItemEffect.xml

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.

Schema#

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