> 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/item/excellentoptionrate.md).

# ExcellentOptionRate

This configuration file defines which excellent option bits can be applied to which item index ranges. Without this file properly configured, excellent items will not receive any excellent options.

## File Location

```
Data/Item/ExcellentOptionRate.xml
```

## Dependencies

| Depends On                          | Purpose                   |
| ----------------------------------- | ------------------------- |
| [Item.xml](/docs/data/item/item.md) | Item definitions by index |

| Depended On By                                          | Purpose                                                         |
| ------------------------------------------------------- | --------------------------------------------------------------- |
| [ItemOptionRate.xml](/docs/data/item/itemoptionrate.md) | ExcOptions section determines COUNT, this file determines WHICH |
| [ItemDrop.xml](/docs/data/item/itemdrop.md)             | ExcOption index triggers excellent generation                   |
| MapManager.xml                                          | ExcItemDropRate triggers random excellent chance                |

## How It Works

When an item spawns with excellent options enabled:

1. [ItemOptionRate.xml](/docs/data/item/itemoptionrate.md) determines HOW MANY excellent options to roll
2. For each option to add, the server picks one at random weighted by `Rate`
3. All entries whose index range contains the item's index are collected
4. Entries whose OptionIndex bit is already set on the item are skipped (prevents duplicates)
5. One option is randomly selected from the remaining pool using Rate weights
6. The option bit is OR-ed into the item's option byte
7. Repeat until the requested count is reached or the pool runs out

{% hint style="info" %}
**Weighted Selection**: If two options both have Rate=1000, each has 50% chance. Rate values are relative weights, not percentages.
{% endhint %}

## Structure

```xml
<ExcellentOptionRateList>
    <Option OptionIndex="1" ItemMinIndex="0" ItemMaxIndex="511"
            Rate="1000" Name="Exc Dmg Rate"/>
    <Option OptionIndex="2" ItemMinIndex="0" ItemMaxIndex="511"
            Rate="1000" Name="Level Dmg"/>
    ...
</ExcellentOptionRateList>
```

## Attributes

| Attribute      | Type   | Description                                        |
| -------------- | ------ | -------------------------------------------------- |
| `OptionIndex`  | int    | Excellent option bit (1, 2, 4, 8, 16, 32)          |
| `ItemMinIndex` | int    | Minimum item index (inclusive)                     |
| `ItemMaxIndex` | int    | Maximum item index (inclusive)                     |
| `Rate`         | int    | Weight for random selection (higher = more likely) |
| `Name`         | string | Description (for documentation only)               |

## Item Index Calculation

```
ItemIndex = Category * 512 + Index
```

| Category | Item Type           | Index Range |
| -------- | ------------------- | ----------- |
| 0        | Swords              | 0 - 511     |
| 1        | Axes                | 512 - 1023  |
| 2        | Maces/Scepters      | 1024 - 1535 |
| 3        | Spears              | 1536 - 2047 |
| 4        | Bows/Crossbows      | 2048 - 2559 |
| 5        | Staffs              | 2560 - 3071 |
| 6        | Shields             | 3072 - 3583 |
| 7        | Helms               | 3584 - 4095 |
| 8        | Armors              | 4096 - 4607 |
| 9        | Pants               | 4608 - 5119 |
| 10       | Gloves              | 5120 - 5631 |
| 11       | Boots               | 5632 - 6143 |
| 12       | Wings/Capes         | 6144 - 6655 |
| 13       | Rings/Pendants/Pets | 6656 - 7167 |

## Excellent Option Bits

### Weapons (Categories 0-5)

| Bit | Value | Effect                                                  |
| --- | ----- | ------------------------------------------------------- |
| 1   | 0x01  | Excellent Damage Rate +10%                              |
| 2   | 0x02  | Increase Damage +level/20                               |
| 4   | 0x04  | Increase Damage +2%                                     |
| 8   | 0x08  | Increase Wizardry Damage +level/20 (or Attack Speed +7) |
| 16  | 0x10  | Increase Life after killing monster +life/8             |
| 32  | 0x20  | Increase Mana after killing monster +mana/8             |

### Armor and Accessories (Categories 6-13)

| Bit | Value | Effect                          |
| --- | ----- | ------------------------------- |
| 1   | 0x01  | Increase Zen after monster +40% |
| 2   | 0x02  | Defense success rate +10%       |
| 4   | 0x04  | Reflect damage +5%              |
| 8   | 0x08  | Damage decrease +4%             |
| 16  | 0x10  | Increase Max Mana +4%           |
| 32  | 0x20  | Increase Max HP +4%             |

{% hint style="info" %}
The stock config includes entries for Cat 12 (Wings/Capes) and Cat 13 (Rings/Pendants/Pets) using the armor bit set.
{% endhint %}

{% hint style="info" %}
**Bit Values**: Options are combined via bitwise OR. An item with bits 1, 4, and 16 would have NewOption value of 21 (1+4+16).
{% endhint %}

{% hint style="warning" %}
**Config Naming**: The default config uses "Life Leech" and "Mana Leech" as Name values, but this is misleading. The actual effect is HP/MP restoration after killing a monster, not on-hit stealing.
{% endhint %}

## Special Items with Limited Options

Some items have a maximum option count that caps the number of rolls regardless of the requested count:

| Item                                         | Max Options                                      |
| -------------------------------------------- | ------------------------------------------------ |
| 2nd Wings (Cat 12, Index 3-6, 42, 49)        | 3                                                |
| Cape of Lord (Cat 13, Index 30)              | 4                                                |
| 3rd Wings (Cat 12, Index 36-40, 43, 50)      | 4                                                |
| Monster Wings (Cat 12, Index 262-265)        | 2                                                |
| Wings of Conqueror (Cat 12, Index 266)       | 3                                                |
| Wings of Angel and Devil (Cat 12, Index 267) | 3                                                |
| Dinorant (Cat 13, Index 3)                   | 3                                                |
| Fenrir (Cat 13, Index 37)                    | 3                                                |
| All other items                              | Uses the requested count, capped at 6 total bits |

## Examples

{% tabs %}
{% tab title="Default Setup" %}
All options have equal weight (1000 each = \~16.7% chance per option):

```xml
<!-- Swords: All 6 options equally likely -->
<Option OptionIndex="1"  ItemMinIndex="0" ItemMaxIndex="511" Rate="1000" Name="Exc Dmg Rate"/>
<Option OptionIndex="2"  ItemMinIndex="0" ItemMaxIndex="511" Rate="1000" Name="Level Dmg"/>
<Option OptionIndex="4"  ItemMinIndex="0" ItemMaxIndex="511" Rate="1000" Name="Inc Dmg 2%"/>
<Option OptionIndex="8"  ItemMinIndex="0" ItemMaxIndex="511" Rate="1000" Name="Wiz Dmg"/>
<Option OptionIndex="16" ItemMinIndex="0" ItemMaxIndex="511" Rate="1000" Name="Life After Kill"/>
<Option OptionIndex="32" ItemMinIndex="0" ItemMaxIndex="511" Rate="1000" Name="Mana After Kill"/>
```

{% endtab %}

{% tab title="Rare HP Option" %}
Make Max HP option 5x rarer than others:

```xml
<!-- Armor: HP option is rare -->
<Option OptionIndex="1"  ItemMinIndex="4096" ItemMaxIndex="4607" Rate="1000" Name="Zen After Kill"/>
<Option OptionIndex="2"  ItemMinIndex="4096" ItemMaxIndex="4607" Rate="1000" Name="Def Rate"/>
<Option OptionIndex="4"  ItemMinIndex="4096" ItemMaxIndex="4607" Rate="1000" Name="Reflect"/>
<Option OptionIndex="8"  ItemMinIndex="4096" ItemMaxIndex="4607" Rate="1000" Name="Dmg Decrease"/>
<Option OptionIndex="16" ItemMinIndex="4096" ItemMaxIndex="4607" Rate="1000" Name="Max Mana"/>
<Option OptionIndex="32" ItemMinIndex="4096" ItemMaxIndex="4607" Rate="200" Name="Max HP"/>
```

With these rates, HP has \~200/5200 = 3.8% chance vs \~19.2% for others.
{% endtab %}

{% tab title="Disable Option" %}
Remove an option entirely by not including it:

```xml
<!-- Swords: No mana restoration option -->
<Option OptionIndex="1"  ItemMinIndex="0" ItemMaxIndex="511" Rate="1000" Name="Exc Dmg Rate"/>
<Option OptionIndex="2"  ItemMinIndex="0" ItemMaxIndex="511" Rate="1000" Name="Level Dmg"/>
<Option OptionIndex="4"  ItemMinIndex="0" ItemMaxIndex="511" Rate="1000" Name="Inc Dmg 2%"/>
<Option OptionIndex="8"  ItemMinIndex="0" ItemMaxIndex="511" Rate="1000" Name="Wiz Dmg"/>
<Option OptionIndex="16" ItemMinIndex="0" ItemMaxIndex="511" Rate="1000" Name="Life After Kill"/>
<!-- OptionIndex="32" removed - no mana restoration possible -->
```

{% endtab %}

{% tab title="Specific Item" %}
Special rates for a specific item (Hand Axe = Cat 1, Index 1):

```xml
<!-- Hand Axe only: Guaranteed life restoration -->
<Option OptionIndex="16" ItemMinIndex="513" ItemMaxIndex="513" Rate="10000" Name="Life After Kill"/>
<Option OptionIndex="1"  ItemMinIndex="513" ItemMaxIndex="513" Rate="1" Name="Exc Dmg Rate"/>
```

The high rate for life restoration (10000 vs 1) makes it nearly guaranteed.
{% endtab %}
{% endtabs %}

## Important Behavior

{% hint style="info" %}
**No Duplicate Options**: Once an option bit is applied, it's excluded from future selection. If you request 6 options but only 5 are defined, you'll get 5.
{% endhint %}

{% hint style="info" %}
**Selection Stops When Empty**: If no valid options remain (all already applied or none defined), option generation stops even if more were requested.
{% endhint %}

{% hint style="info" %}
**Wings and Pets**: Wings (Cat 12) and pets/rings/pendants (Cat 13) go through this same file. The stock config uses the armor bit set for those categories. Wings and specific pets additionally cap the maximum option count (see table above).
{% endhint %}

## Common Issues

{% hint style="danger" %}
**No Options Appearing**: If excellent items have no options, check that this file has entries for the item's index range. Missing entries = no options possible.
{% endhint %}

{% hint style="warning" %}
**Wrong Option Type**: Remember that bits 1-32 have DIFFERENT meanings for weapons vs armor. Bit 1 is "Exc Damage Rate" on weapons but "Zen After Kill" on armor.
{% endhint %}

{% hint style="warning" %}
**Index Range Calculation**: Double-check your index calculations. Cat 8, Index 5 = 8\*512+5 = 4101, not 85. A wrong range means options won't apply.
{% endhint %}

{% hint style="info" %}
**Overlapping Ranges**: Multiple entries can cover the same item. Every matching entry is added to the weighted pool, even if two share the same OptionIndex - this is the way to boost a specific option's effective weight. However, once a bit is already set on the item, all further entries with that same OptionIndex are skipped for that roll.
{% endhint %}

## See Also

* [ItemOptionRate.xml](/docs/data/item/itemoptionrate.md) - Controls how many excellent options roll (ExcOptions section)
* [ItemDrop.xml](/docs/data/item/itemdrop.md) - Drop table entries that trigger excellent generation
* [Item.xml](/docs/data/item/item.md) - Base item definitions by Category and Type
* [ItemOption.xml](/docs/data/item/itemoption.md) - Standard level-based option stat bonuses