# ItemOption

This configuration file defines the stat bonuses that items receive based on their option values.

## File Location

```
GameServer/Data/Item/ItemOption.xml
```

## Dependencies

| Depends On         | Purpose                                     |
| ------------------ | ------------------------------------------- |
| ItemOptionRate.xml | Determines which option values are selected |
| Item.xml           | Item definitions that receive these bonuses |

## How It Works

After ItemOptionRate determines WHAT options an item has, ItemOption determines the EFFECT of those options.

Each item has **14 special option slots** (Index 0-13) that store active bonuses. The `Index` attribute determines which slot receives the bonus.

Each option entry can specify:

* **Which slot** to store the bonus in (Index 0-13)
* **Which items** it applies to (by index range)
* **Conditions** (skill, luck, excellent flags, level, ancient tier)
* **What stat bonus** to apply (OptionIndex + OptionValue)

{% hint style="info" %}
**Multiple Entries, Same Slot**: If multiple entries match the same Index slot, only the **last matching entry** is applied. This creates a priority system where later entries override earlier ones.
{% endhint %}

## Configuration Structure

```xml
<ItemOptionList>
    <Option Index="0" OptionIndex="80" OptionValue="10"
            ItemMinIndex="*" ItemMaxIndex="*"
            SkillSwitch="*" LuckSwitch="*"
            AditionalMin="*" AditionalMax="*"
            Excellent="*" ItemLvlMin="*" ItemLvlMax="*"
            Ancient="*" />
</ItemOptionList>
```

## Attributes

| Attribute      | Type    | Default  | Description                                                                                                     |
| -------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `Index`        | int     | Required | **Target slot** on item (0-13). Determines which special option slot stores this bonus. See slot mapping below. |
| `OptionIndex`  | int     | Required | Stat type to modify (see Option Index Reference)                                                                |
| `OptionValue`  | int     | Required | Amount to add/multiply                                                                                          |
| `ItemMinIndex` | int/`*` | `*`      | Minimum item index (wildcard = any)                                                                             |
| `ItemMaxIndex` | int/`*` | `*`      | Maximum item index (wildcard = any)                                                                             |
| `SkillSwitch`  | int/`*` | `*`      | Required skill option value (1=has skill, 0=no skill, \*=any)                                                   |
| `LuckSwitch`   | int/`*` | `*`      | Required luck option value (1=has luck, 0=no luck, \*=any)                                                      |
| `AditionalMin` | int/`*` | `*`      | Minimum JoL option value (0-28)                                                                                 |
| `AditionalMax` | int/`*` | `*`      | Maximum JoL option value (0-28)                                                                                 |
| `Excellent`    | int/`*` | `*`      | Excellent option bitmask filter (see below)                                                                     |
| `ItemLvlMin`   | int/`*` | `*`      | Minimum item level (0-15)                                                                                       |
| `ItemLvlMax`   | int/`*` | `*`      | Maximum item level (0-15)                                                                                       |
| `Ancient`      | int/`*` | `*`      | Ancient tier requirement (0=none, 1=tier1, 2=tier2, 3=any ancient, \*=ignore)                                   |

### Special Option Slot Mapping (Index Values)

Each item stores bonuses in 14 fixed slots:

| Index | Slot Purpose       | Typical Use                          |
| ----- | ------------------ | ------------------------------------ |
| 0     | Skill Option       | Bonus when item has +Skill           |
| 1     | Luck Option        | Bonus when item has +Luck            |
| 2     | JoL Option         | Bonus based on Jewel of Life level   |
| 3     | Excellent Option 1 | Bonus for 1st excellent flag (bit 0) |
| 4     | Excellent Option 2 | Bonus for 2nd excellent flag (bit 1) |
| 5     | Excellent Option 3 | Bonus for 3rd excellent flag (bit 2) |
| 6     | Excellent Option 4 | Bonus for 4th excellent flag (bit 3) |
| 7     | Excellent Option 5 | Bonus for 5th excellent flag (bit 4) |
| 8     | Excellent Option 6 | Bonus for 6th excellent flag (bit 5) |
| 9     | Common Slot 1      | Custom/general bonuses               |
| 10    | Common Slot 2      | Custom/general bonuses               |
| 11    | Common Slot 3      | Custom/general bonuses               |
| 12    | Common Slot 4      | Custom/general bonuses               |
| 13    | Common Slot 5      | Custom/general bonuses               |

## Option Index Reference

The `OptionIndex` value determines what stat is modified. Values range from **80 to 154**.

See [**OptionIndex Reference**](https://axiomemu.gitbook.io/docs/gameserver/item/optionindex-reference) for the complete list of all 75 option types.

Common examples:

| OptionIndex | Effect                          |
| ----------- | ------------------------------- |
| 80          | Add Physical Damage             |
| 83          | Add Defense                     |
| 91          | Multiply HP (%)                 |
| 94          | Multiply Physical Damage (%)    |
| 117         | Add Experience Rate             |
| 136-140     | Add Stats (STR/AGI/VIT/ENE/CMD) |

## Excellent Bitmask

The `Excellent` attribute filters based on the item's excellent options using **bitwise AND**.

Items store their excellent options in a bitmask (`m_NewOption`). Each bit represents a different excellent option:

| Bit | Value | Excellent Option        |
| --- | ----- | ----------------------- |
| 0   | 1     | First excellent option  |
| 1   | 2     | Second excellent option |
| 2   | 4     | Third excellent option  |
| 3   | 8     | Fourth excellent option |
| 4   | 16    | Fifth excellent option  |
| 5   | 32    | Sixth excellent option  |

**How the filter works**: `(item.NewOption & Excellent) != 0`

This means the option applies if the item has **ANY** of the specified bits set.

| Excellent Value | Matches Items With                   |
| --------------- | ------------------------------------ |
| `*`             | Any item (no filter)                 |
| `1`             | Bit 0 set (first exc option)         |
| `2`             | Bit 1 set (second exc option)        |
| `3`             | Bit 0 OR bit 1 set (first OR second) |
| `63`            | Any excellent option (all 6 bits)    |

{% hint style="info" %}
**To require multiple specific options**: Use a value with those bits set. For example, `Excellent="5"` (binary 101) matches items with bit 0 OR bit 2 set.
{% endhint %}

## Wildcard Usage

Using `*` (asterisk) means "any value" - the condition is ignored:

```xml
<!-- Applies to ALL items regardless of options: +10 physical damage -->
<Option Index="0" OptionIndex="80" OptionValue="10"
        ItemMinIndex="*" ItemMaxIndex="*" SkillSwitch="*"
        LuckSwitch="*" AditionalMin="*" AditionalMax="*"
        Excellent="*" ItemLvlMin="*" ItemLvlMax="*" Ancient="*" />

<!-- Only applies to items WITH skill option: +20 physical damage -->
<Option Index="0" OptionIndex="80" OptionValue="20"
        ItemMinIndex="*" ItemMaxIndex="*" SkillSwitch="1"
        LuckSwitch="*" AditionalMin="*" AditionalMax="*"
        Excellent="*" ItemLvlMin="*" ItemLvlMax="*" Ancient="*" />
```

## Examples

{% tabs %}
{% tab title="Level-Based Damage" %}

```xml
<!-- Damage scales with level: (Level+MasterLevel)/20 for all weapons in slot 0 -->
<!-- OptionIndex 93 = ADD_PHYSI_DAMAGE_BY_LEVEL -->
<!-- Formula: Damage += (CharLevel + MasterLevel) / OptionValue -->
<!-- Example: Level 400 char = +20 damage (400/20) -->
<Option Index="0" OptionIndex="93" OptionValue="20"
        ItemMinIndex="0" ItemMaxIndex="2559"
        SkillSwitch="*" LuckSwitch="*" AditionalMin="*"
        AditionalMax="*" Excellent="*" ItemLvlMin="*"
        ItemLvlMax="*" Ancient="*" />
```

{% endtab %}

{% tab title="Excellent Item Bonus" %}

```xml
<!-- +15% physical damage for items with ANY excellent option (stored in slot 1) -->
<!-- Excellent="63" = binary 111111 = any of the 6 excellent bits -->
<!-- OptionIndex 94 = MUL_PHYSI_DAMAGE (percentage multiplier) -->
<Option Index="1" OptionIndex="94" OptionValue="15"
        Excellent="63" ItemMinIndex="*" ItemMaxIndex="*"
        SkillSwitch="*" LuckSwitch="*" AditionalMin="*"
        AditionalMax="*" ItemLvlMin="*" ItemLvlMax="*"
        Ancient="*" />
```

{% endtab %}

{% tab title="Slot Priority System" %}

```xml
<!-- Priority system: General bonus first, specific bonuses override -->

<!-- All weapons get base +10 damage in slot 9 -->
<Option Index="9" OptionIndex="80" OptionValue="10"
        ItemMinIndex="0" ItemMaxIndex="2559"
        SkillSwitch="*" LuckSwitch="*" AditionalMin="*"
        AditionalMax="*" Excellent="*" ItemLvlMin="*"
        ItemLvlMax="*" Ancient="*" />

<!-- But specific weapon ranges get higher bonus in slot 9 (overrides above) -->
<Option Index="9" OptionIndex="80" OptionValue="25"
        ItemMinIndex="0" ItemMaxIndex="511"
        SkillSwitch="*" LuckSwitch="*" AditionalMin="*"
        AditionalMax="*" Excellent="*" ItemLvlMin="*"
        ItemLvlMax="*" Ancient="*" />

<!-- Ancient tier 2 gets even more in slot 9 (overrides both) -->
<Option Index="9" OptionIndex="80" OptionValue="50"
        ItemMinIndex="0" ItemMaxIndex="2559"
        SkillSwitch="*" LuckSwitch="*" AditionalMin="*"
        AditionalMax="*" Excellent="*" ItemLvlMin="*"
        ItemLvlMax="*" Ancient="2" />
```

{% endtab %}

{% tab title="Ancient Tier Bonus" %}

```xml
<!-- +50 defense for ancient tier 2 items (slot 2 = JoL slot) -->
<Option Index="2" OptionIndex="83" OptionValue="50"
        ItemMinIndex="*" ItemMaxIndex="*" SkillSwitch="*"
        LuckSwitch="*" AditionalMin="*" AditionalMax="*"
        Excellent="*" ItemLvlMin="*" ItemLvlMax="*"
        Ancient="2" />

<!-- Bonus for ANY ancient tier item (3 = any tier 1 or tier 2) -->
<Option Index="9" OptionIndex="83" OptionValue="30"
        ItemMinIndex="*" ItemMaxIndex="*" SkillSwitch="*"
        LuckSwitch="*" AditionalMin="*" AditionalMax="*"
        Excellent="*" ItemLvlMin="*" ItemLvlMax="*"
        Ancient="3" />
```

{% endtab %}
{% endtabs %}

## Important Behavior

{% hint style="info" %}
**Last Match Wins**: When multiple entries target the same Index slot and all match the item's properties, only the **last matching entry** in the file is applied. This allows you to create priority systems where more specific conditions override general ones.
{% endhint %}

{% hint style="info" %}
**Ancient Tier Values**:

* `Ancient="0"` - Only non-ancient items
* `Ancient="1"` - Only ancient tier 1
* `Ancient="2"` - Only ancient tier 2
* `Ancient="3"` - Any ancient (tier 1 OR tier 2)
* `Ancient="*"` - Ignore ancient status
  {% endhint %}

## Common Issues

{% hint style="warning" %}
**Wildcards Not Working**: Make sure you're using `*` (asterisk character), not `-1` or leaving the attribute empty.
{% endhint %}

{% hint style="warning" %}
**Bonuses Not Applying**: Check that all conditions match - ItemMinIndex/MaxIndex, SkillSwitch, LuckSwitch, etc. must ALL match for the option to apply.
{% endhint %}

{% hint style="warning" %}
**Bonus Overwritten**: If you have multiple entries with the same Index value that both match an item, only the last one applies. Make conditions mutually exclusive or use different Index slots.
{% endhint %}
