> 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

Defines stat bonuses and effects applied by item options

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 30 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 **30 special option slots** (Index 0-29) 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-29)
* 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-29). 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-15)` 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-15). Matches the item's additional (JoL) option.                                                                                                            |
| `AditionalMax`     | int/`*` | `*`      | Maximum JoL value (0-15).                                                                                                                                                        |
| `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 30-slot array. The loader writes `OptionIndex`/`OptionValue` into the slot selected by `Index`.

| Index | Slot                    | Purpose                                                                                                                                                                                                                                                                      |
| ----- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0     | Skill slot              | Skill option (set to the item's skill ID when the Skill flag is on). Wing and pet items also use this slot for the wing and Fenrir bonus options (OptionIndex 49, 62 and 76).                                                                                                |
| 1     | Luck slot               | Luck option. Entries in this slot also carry LuckJoSRate and LuckChaosMixRate.                                                                                                                                                                                               |
| 2     | JoL slot                | JoL option. Stored value = `OptionValue * (JoL value 0-15)`, applied at item generation. The applier reads the already-multiplied amount as a flat number. The reachable ceiling is `MaxItemOption` in [Common.dat](/docs/gameserver/common-dat.md) (default `7`, max `15`). |
| 3     | Excellent slot 1        | Excellent option slot 1                                                                                                                                                                                                                                                      |
| 4     | Excellent slot 2        | Excellent option slot 2                                                                                                                                                                                                                                                      |
| 5     | Excellent slot 3        | Excellent option slot 3                                                                                                                                                                                                                                                      |
| 6     | Excellent slot 4        | Excellent option slot 4                                                                                                                                                                                                                                                      |
| 7     | Excellent slot 5        | Excellent option slot 5                                                                                                                                                                                                                                                      |
| 8     | Excellent slot 6        | Excellent option slot 6                                                                                                                                                                                                                                                      |
| 9     | Custom bonus slot 1     | Custom bonus slot 1                                                                                                                                                                                                                                                          |
| 10    | Custom bonus slot 2     | Custom bonus slot 2                                                                                                                                                                                                                                                          |
| 11    | Custom bonus slot 3     | Custom bonus slot 3                                                                                                                                                                                                                                                          |
| 12    | Custom bonus slot 4     | Custom bonus slot 4                                                                                                                                                                                                                                                          |
| 13    | Custom bonus slot 5     | Custom bonus slot 5                                                                                                                                                                                                                                                          |
| 14-29 | Custom bonus slots 6-21 | Additional custom bonus slots. Identical behaviour to 9-13 - pure filter rows with no special meaning attached to the slot number                                                                                                                                            |

{% 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 excellent option bit.
{% endhint %}

{% hint style="info" %}
**Slots 9-29 are interchangeable.** Every slot from 9 upwards is resolved by the same loop and behaves identically, so an item can carry up to 21 filter-driven custom bonuses on top of its skill, luck, JoL and six excellent slots. Use separate `Index` values only to keep bonuses from overwriting each other - two entries that match the same `Index` still collapse to the last match.
{% 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 option flags. 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 the item's excellent option flags share any bit with this value

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

{% hint style="warning" %}
**Slot 2 exception: JoL variants**

On `Index="2"` (JoL) rows, `Excellent="16"` and `Excellent="32"` are **not** filters - they declare *additional JoL variants* for that item range.

When an item has more than one slot-2 variant available, the server picks one of them **at random** as the item is generated. This is how the shipped wings roll either extra Life or extra damage from their JoL level.

A variant is only offered while no real excellent option on the item already occupies that bit. Last-match-wins does not apply across variants.
{% endhint %}

## Ancient Filter

The `Ancient` filter matches against the item's ancient tier: 0 = not ancient, 1 = tier 1, 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 = physical damage per 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. This holds for every slot except the Index=2 JoL variants described under the Excellent Filter, which are chosen at random rather than by file order.
{% 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 to `MaxItemOption`, default 7, max 15 - see [Common.dat](/docs/gameserver/common-dat.md)) 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 %}