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

# ItemOption

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

## File Location

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

## Dependencies

| Depends On                                              | Purpose                                     |
| ------------------------------------------------------- | ------------------------------------------- |
| [ItemOptionRate.xml](/docs/data/item/itemoptionrate.md) | Determines which option values are selected |
| [Item.xml](/docs/data/item/item.md)                     | Item definitions that receive these bonuses |

## Related Option Tables

Bonuses from other option tables stack with ItemOption output when the character has the qualifying items:

* [ExcellentOptionRate.xml](/docs/data/item/excellentoptionrate.md) - picks which excellent flags an item rolls
* [SetItemOption.xml](/docs/data/item/setitemoption.md) - ancient and set bonuses applied independently of the 14 special-option slots
* [SocketItemOption.xml](/docs/data/item/socketitemoption.md) - socket seed, bonus, and package options
* [JewelOfHarmonyOption.xml](/docs/data/item/jewelofharmonyoption.md) - JoH enhancements
* [380ItemOption.xml](/docs/data/item/380itemoption.md) - 380 item options (PvP rates, max HP, max SD, SD recovery)

## How It Works

After ItemOptionRate determines which option values an item rolls, 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 item range it applies to (by item index)
* Filter conditions (skill, luck, JoL value, excellent flags, item 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 in the file 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 the item (0-13). See slot mapping below.                                                                                                                         |
| `OptionIndex`      | int     | Required | Stat type to modify. See [OptionIndex Reference](/docs/data/item/optionindex-reference.md).                                                                                     |
| `OptionValue`      | int     | Required | Amount to add or multiply. For slot 2 entries, the loader stores `OptionValue * JoL value (0-7)` on the item at generation time; supply the per-JoL-level bonus, not the total. |
| `ItemMinIndex`     | int/`*` | `*`      | Minimum item index (wildcard = any)                                                                                                                                             |
| `ItemMaxIndex`     | int/`*` | `*`      | Maximum item index (wildcard = any)                                                                                                                                             |
| `SkillSwitch`      | int/`*` | `*`      | Required skill flag (1 = has skill, 0 = no skill, `*` = any)                                                                                                                    |
| `LuckSwitch`       | int/`*` | `*`      | Required luck flag (1 = has luck, 0 = no luck, `*` = any)                                                                                                                       |
| `AditionalMin`     | int/`*` | `*`      | Minimum JoL value (0-7). Matches the item's additional (JoL) option.                                                                                                            |
| `AditionalMax`     | int/`*` | `*`      | Maximum JoL value (0-7).                                                                                                                                                        |
| `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 filter. See below.                                                                                                                                                 |
| `LuckJoSRate`      | int     | 0        | Jewel of Soul success-rate bonus (%) granted by the Luck slot. Applied to JoS enchant rolls; VIP bonus adds on top.                                                             |
| `LuckChaosMixRate` | int     | 0        | Chaos Machine +10\~+15 mix rate bonus (%) granted by the Luck slot. VIP bonus adds on top.                                                                                      |
| `Name`             | string  | -        | Optional human-readable description (ignored at runtime)                                                                                                                        |

### Special Option Slot Mapping (Index Values)

Each item has a fixed 14-slot array. The loader writes `OptionIndex`/`OptionValue` into the slot selected by `Index`.

| Index | Slot                | Purpose                                                                                                                                                                    |
| ----- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0     | SPECIAL\_OPTION1    | Skill option (set to the item's skill ID when the Skill flag is on). Wing/pet items also use this slot for the ADD\_WING\_\* or ADD\_FENRIR\* OptionIndex values 49/62/76. |
| 1     | SPECIAL\_OPTION2    | Luck option. Entries in this slot also carry LuckJoSRate and LuckChaosMixRate.                                                                                             |
| 2     | SPECIAL\_OPTION3    | JoL option. Stored value = `OptionValue * (JoL value 0-7)`, applied at item generation. The applier reads the already-multiplied amount as a flat number.                  |
| 3     | SPECIAL\_EXCELLENT1 | Excellent option slot 1                                                                                                                                                    |
| 4     | SPECIAL\_EXCELLENT2 | Excellent option slot 2                                                                                                                                                    |
| 5     | SPECIAL\_EXCELLENT3 | Excellent option slot 3                                                                                                                                                    |
| 6     | SPECIAL\_EXCELLENT4 | Excellent option slot 4                                                                                                                                                    |
| 7     | SPECIAL\_EXCELLENT5 | Excellent option slot 5                                                                                                                                                    |
| 8     | SPECIAL\_EXCELLENT6 | Excellent option slot 6                                                                                                                                                    |
| 9     | SPECIAL\_COMMON1    | Custom bonus slot 1                                                                                                                                                        |
| 10    | SPECIAL\_COMMON2    | Custom bonus slot 2                                                                                                                                                        |
| 11    | SPECIAL\_COMMON3    | Custom bonus slot 3                                                                                                                                                        |
| 12    | SPECIAL\_COMMON4    | Custom bonus slot 4                                                                                                                                                        |
| 13    | SPECIAL\_COMMON5    | Custom bonus slot 5                                                                                                                                                        |

{% hint style="info" %}
The six excellent slots (3-8) all use the same filter model. They are populated in order as the item's six excellent flags roll; there is no fixed mapping between a specific slot number and a specific bit of `NewOption`.
{% endhint %}

## Option Index Reference

The `OptionIndex` value determines what stat is modified. Values in the standard range run from **80 to 161** (80-154 core stats, plus 155-161 for the 380-set PvP / SD stats).

See [**OptionIndex Reference**](/docs/data/item/optionindex-reference.md) for the complete list of all option types.

Common examples:

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

{% hint style="info" %}
Wing and pet items use non-standard OptionIndex values in slot 0 (49 = Dinorant basic, 62 = Dark Horse basic, 76 = Fenrir basic). These are sentinels interpreted by other systems and produce no direct stat bonus through the option applier.
{% endhint %}

## Excellent Bitmask

The `Excellent` attribute filters using bitwise AND against the item's excellent bitmask (`NewOption`). Each of the six excellent flags is stored in its own bit:

| Bit | Value | Excellent Slot     |
| --- | ----- | ------------------ |
| 0   | 1     | Excellent option 1 |
| 1   | 2     | Excellent option 2 |
| 2   | 4     | Excellent option 3 |
| 3   | 8     | Excellent option 4 |
| 4   | 16    | Excellent option 5 |
| 5   | 32    | Excellent option 6 |

**Filter behavior**:

* `Excellent="*"` - ignore the flag
* `Excellent="0"` - match only items with no excellent options at all
* Any other value - match if `(NewOption & Excellent) != 0`

| Excellent Value | Matches Items With                |
| --------------- | --------------------------------- |
| `*`             | Any item (no filter)              |
| `1`             | Bit 0 set (excellent option 1)    |
| `2`             | Bit 1 set (excellent option 2)    |
| `3`             | Bit 0 or bit 1 set                |
| `63`            | Any of the six excellent bits set |

{% hint style="info" %}
The filter is an OR across the set bits: `Excellent="5"` (binary 101) matches items with bit 0 or bit 2 set. There is no built-in way to require two specific bits simultaneously.
{% endhint %}

## Ancient Filter

The loader reads `ancientType = (SetOption & 3)`, which produces values 0 (not ancient), 1 (tier 1), or 2 (tier 2).

| `Ancient` Value | Matches                             |
| --------------- | ----------------------------------- |
| `*`             | Any item                            |
| `0`             | Non-ancient items only              |
| `1`             | Ancient tier 1 only                 |
| `2`             | Ancient tier 2 only                 |
| `3`             | Any ancient item (tier 1 or tier 2) |

## Wildcard Usage

Using `*` (asterisk) means "any value" and disables that filter:

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

<!-- Only applies to items with the skill flag on -->
<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
<!-- (CharLevel + MasterLevel) / 20 added to physical damage -->
<!-- OptionIndex 93 = ADD_PHYSI_DAMAGE_BY_LEVEL -->
<!-- Example: Level 400 + ML 0 = +20, Level 400 + ML 200 = +30 -->
<Option Index="9" 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 excellent slot 1 (Index 3) -->
<!-- Excellent="63" = binary 111111 = any of the six excellent bits -->
<Option Index="3" OptionIndex="94" OptionValue="15"
        Excellent="63" ItemMinIndex="*" ItemMaxIndex="*"
        SkillSwitch="*" LuckSwitch="*" AditionalMin="*"
        AditionalMax="*" ItemLvlMin="*" ItemLvlMax="*"
        Ancient="*" />
```

{% endtab %}

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

```xml
<!-- Priority: general bonus first, specific entries override -->

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

<!-- Narrower weapon range overrides the general entry -->
<Option Index="9" OptionIndex="80" OptionValue="25"
        ItemMinIndex="0" ItemMaxIndex="511"
        SkillSwitch="*" LuckSwitch="*" AditionalMin="*"
        AditionalMax="*" Excellent="*" ItemLvlMin="*"
        ItemLvlMax="*" Ancient="*" />

<!-- Ancient tier 2 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, placed in a common slot -->
<Option Index="10" OptionIndex="83" OptionValue="50"
        ItemMinIndex="*" ItemMaxIndex="*" SkillSwitch="*"
        LuckSwitch="*" AditionalMin="*" AditionalMax="*"
        Excellent="*" ItemLvlMin="*" ItemLvlMax="*"
        Ancient="2" />

<!-- +30 defense for any ancient item (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 pass filters, only the last matching entry in the file is applied. Use mutually exclusive filters or different slots when you need simultaneous bonuses.
{% endhint %}

{% hint style="info" %}
**Slot 2 JoL Scaling**: For entries with Index=2, the loader pre-multiplies `OptionValue` by the item's JoL value (0-7) when the item is generated and stores the product on the item. Supply the per-JoL-level bonus, not the total. JoL=0 stores 0 (no bonus from this slot).
{% endhint %}

{% hint style="info" %}
**Luck Slot Side Effects**: Only entries with Index=1 contribute LuckJoSRate and LuckChaosMixRate. Setting these attributes on any other slot has no effect.
{% endhint %}

## Common Issues

{% hint style="warning" %}
**Wildcards Not Working**: Use the `*` character only. The loader does not treat empty strings or `-1` as wildcards.
{% endhint %}

{% hint style="warning" %}
**Bonuses Not Applying**: Every filter must match. Check ItemMinIndex / ItemMaxIndex, the skill / luck flags, JoL range, excellent bitmask, item level range, and ancient tier.
{% endhint %}

{% hint style="warning" %}
**Bonus Overwritten**: Two entries targeting the same slot that both match the item will only leave the last one applied. Separate them by slot or by filter.
{% endhint %}