# 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

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

## Dependencies

| Depends On | Purpose                   |
| ---------- | ------------------------- |
| Item.xml   | Item definitions by index |

| Depended On By     | Purpose                                                         |
| ------------------ | --------------------------------------------------------------- |
| ItemOptionRate.xml | ExcOptions section determines COUNT, this file determines WHICH |
| ItemDrop.xml       | 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** determines HOW MANY excellent options (0-6)
2. **For each option to add**, the server calls `GetExcellentOptionByRate()`
3. All valid options for the item's index range are collected
4. Already-applied options are excluded (prevents duplicates)
5. One option is randomly selected using Rate weights
6. The option bit is applied via bitwise OR
7. Repeat until desired count is reached

{% 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 |

## 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 (Categories 6-11)

| 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" %}
**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 overrides 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           |
| Custom Wings                                 | 4           |

## 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="warning" %}
**Wings/Pets Have Different Options**: Wings and pets use different option systems. This file only applies to equipment categories 0-11.
{% 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. All matching entries are added to the selection pool, even if they have the same OptionIndex. This allows boosting an option's weight by adding multiple entries with the same OptionIndex but different ranges or by intentionally duplicating entries.
{% endhint %}
