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

# ItemOptionRate

This configuration file defines the probability tables used when picking item option values (level, skill flag, luck flag, JoL value, excellent count, set tier, socket count) during item generation.

## File Location

```
Data/Item/ItemOptionRate.xml
```

## Dependencies

| Depends On                                      | Purpose                                        |
| ----------------------------------------------- | ---------------------------------------------- |
| [Item.xml](/docs/data/item/item.md)             | Item definitions that receive these options    |
| [ItemOption.xml](/docs/data/item/itemoption.md) | Stat bonuses applied based on selected options |

## Related Option Tables

* [ExcellentOptionRate.xml](/docs/data/item/excellentoptionrate.md) - per-excellent-option weighting once ExcOptions has chosen the count
* [SetItemOption.xml](/docs/data/item/setitemoption.md) - ancient bonuses keyed by SetOptions tier
* [SocketItemOption.xml](/docs/data/item/socketitemoption.md) - socket seed / bonus / package rolls on sockets produced by SocketOptions
* [JewelOfHarmonyOption.xml](/docs/data/item/jewelofharmonyoption.md) - JoH options (independent of JoL)

## How It Works

When an item is generated, the server:

1. Looks up the Index for the source (monster drop, chaos mix, event bag, moss merchant, etc.).
2. Uses weighted random selection over the section's rate array.
3. Writes the selected value into the appropriate item field.

{% hint style="info" %}
**Weighted Selection**: Rates are relative weights, not cumulative probabilities. With Rate0=7000, Rate1=2000, Rate2=1000, the outcomes are 70%, 20%, 10% because the total happens to be 10000. If the total were 5000, 7000/5000 would still resolve to the same relative proportions but it is cleanest to keep totals at 10000.
{% endhint %}

## Configuration Sections

### LevelOptions

Controls item enhancement level (+0 to +15) when an item is generated.

```xml
<LevelOptions>
    <Level Index="0" Rate0="7000" Rate1="1500" Rate2="1000" Rate3="500"
           Rate4="0" ... Rate15="0" Name="Level Option (Common)"/>
</LevelOptions>
```

| Attribute          | Type   | Range   | Description                                               |
| ------------------ | ------ | ------- | --------------------------------------------------------- |
| `Index`            | int    | any     | Source identifier (see Index Reference below)             |
| `Rate0` - `Rate15` | int    | 0-10000 | Weight for each level (+0 to +15). Exactly 16 rate slots. |
| `Name`             | string | -       | Optional description                                      |

<details>

<summary>Level Index reference (values shipped with AXIOM-EMU)</summary>

| Index | Source                                                                  |
| ----- | ----------------------------------------------------------------------- |
| 0     | Common drops                                                            |
| 1     | Excellent generation (forces +0)                                        |
| 2     | Set generation (forces +0)                                              |
| 3     | Chaos item mix                                                          |
| 9     | Moss Merchant                                                           |
| 10    | Lucky item drops                                                        |
| 11-26 | EventItemBag (forces a fixed level: 11 -> +0, 12 -> +1, ..., 26 -> +15) |
| 27-53 | EventItemBag (random within a level range)                              |

</details>

**Example - common drop distribution:**

```xml
<Level Index="0" Rate0="7000" Rate1="1500" Rate2="1000" Rate3="500"
       Rate4="0" Rate5="0" ... Name="Level Option (Common)"/>
```

* 70% chance for +0
* 15% chance for +1
* 10% chance for +2
* 5% chance for +3
* 0% for +4 through +15

### SkillOptions

Controls whether an item is generated with the skill flag set (for weapons / books / staves).

```xml
<SkillOptions>
    <Skill Index="0" Rate0="9400" Rate1="600" Name="Skill Option (Common)"/>
</SkillOptions>
```

| Attribute | Type | Description               |
| --------- | ---- | ------------------------- |
| `Index`   | int  | Source identifier         |
| `Rate0`   | int  | Weight for no skill flag  |
| `Rate1`   | int  | Weight for skill flag set |

Shipped defaults include:

* Index 0 (Common): 94% no skill, 6% has skill
* Index 1 (Exc): 100% has skill
* Index 2 (Set): 100% has skill
* Index 3 (ChaosItemMix): 75% / 25%

### LuckOptions

Controls whether an item is generated with the luck flag set (+5% critical damage rate plus LuckJoSRate / LuckChaosMixRate from [ItemOption.xml](/docs/data/item/itemoption.md)).

```xml
<LuckOptions>
    <Luck Index="0" Rate0="9600" Rate1="400" Name="Luck Option (Common)"/>
</LuckOptions>
```

| Attribute | Type | Description              |
| --------- | ---- | ------------------------ |
| `Index`   | int  | Source identifier        |
| `Rate0`   | int  | Weight for no luck       |
| `Rate1`   | int  | Weight for luck flag set |

### JoLOptions

Controls the Jewel of Life additional option value (0-7).

```xml
<JoLOptions>
    <JoL Index="0" Rate0="9600" Rate1="150" Rate2="100" Rate3="50"
         Rate4="0" Rate5="0" Rate6="0" Rate7="0" Name="JoL Option (Common)"/>
</JoLOptions>
```

| Attribute         | Type | Range   | Description                                      |
| ----------------- | ---- | ------- | ------------------------------------------------ |
| `Index`           | int  | any     | Source identifier                                |
| `Rate0` - `Rate7` | int  | 0-10000 | Weight for each JoL value. Exactly 8 rate slots. |

{% hint style="info" %}
The JoL value becomes the item's additional option. ItemOption.xml entries in slot 2 multiply their `OptionValue` by this number, so each +1 of JoL grants the configured bonus once more.
{% endhint %}

### ExcOptions

Controls how many excellent options an item rolls (0-6).

```xml
<ExcOptions>
    <Exc Index="1" Rate0="0" Rate1="7500" Rate2="2500" Rate3="0"
         Rate4="0" Rate5="0" Rate6="0" Name="Exc Option (Exc)"/>
</ExcOptions>
```

| Attribute         | Type | Range   | Description                                                               |
| ----------------- | ---- | ------- | ------------------------------------------------------------------------- |
| `Index`           | int  | any     | Source identifier                                                         |
| `Rate0` - `Rate6` | int  | 0-10000 | Weight for each option count (0 through 6 options). Exactly 7 rate slots. |

For the shipped `Index="1"` (excellent generation): 75% chance for 1 excellent option, 25% for 2.

{% hint style="warning" %}
This only picks the count. The specific excellent flags are chosen by [ExcellentOptionRate.xml](/docs/data/item/excellentoptionrate.md) using the item's category and the running bitmask.
{% endhint %}

### SetOptions

Controls ancient set tier when a set item is generated.

```xml
<SetOptions>
    <Set Index="2" Rate0="0" Rate1="8000" Rate2="2000" Name="Set Option (Set)"/>
</SetOptions>
```

| Attribute | Type | Description                     |
| --------- | ---- | ------------------------------- |
| `Index`   | int  | Source identifier               |
| `Rate0`   | int  | Weight for tier 0 (not ancient) |
| `Rate1`   | int  | Weight for tier 1               |
| `Rate2`   | int  | Weight for tier 2               |

Exactly 3 rate slots.

### SocketOptions

Controls socket count for socket weapons / armors and for pentagram items.

```xml
<SocketOptions>
    <Socket Index="3" Rate0="0" Rate1="8400" Rate2="1550" Rate3="50"
            Rate4="0" Rate5="0" Name="Socket Option (OneHand)"/>
</SocketOptions>
```

| Attribute         | Type | Range   | Description                                                       |
| ----------------- | ---- | ------- | ----------------------------------------------------------------- |
| `Index`           | int  | any     | Source identifier                                                 |
| `Rate0` - `Rate5` | int  | 0-10000 | Weight for each socket count (0 through 5). Exactly 6 rate slots. |

## Index Reference (per section)

Each section maintains its own Index map. The same Index number can mean different things in different sections, depending on which generator code passes that Index to that section's lookup. Typical meanings in the shipped data:

| Index | Level / Skill / Luck / JoL                                           | ExcOptions             | SetOptions      | SocketOptions                   |
| ----- | -------------------------------------------------------------------- | ---------------------- | --------------- | ------------------------------- |
| 0     | Common drop                                                          | Common (no exc)        | Common (no set) | Common (no socket)              |
| 1     | Excellent generation (level forced to +0)                            | Excellent generation   | (no set)        | (no socket)                     |
| 2     | Set generation (level forced to +0)                                  | (no exc)               | Set generation  | (no socket)                     |
| 3     | Chaos item mix                                                       | DinorantMix            | -               | One-hand socket roll            |
| 4     | Wing2 mix                                                            | Wing2 mix              | -               | Two-hand socket roll            |
| 5     | Wing1 mix                                                            | Wing2 mix (Wing1 path) | -               | Pentagram socket roll           |
| 6     | Wing3 mix                                                            | Wing3 mix              | -               | Socket weapon mix (lower tier)  |
| 7     | Monster wing mix                                                     | Monster wing mix       | -               | Socket weapon mix (higher tier) |
| 8     | Socket weapon mix (Luck section only)                                | -                      | -               | -                               |
| 9     | Moss Merchant                                                        | Moss Merchant          | Moss Merchant   | Moss Merchant                   |
| 10    | Lucky item                                                           | Lucky item             | Lucky item      | Lucky item                      |
| 11+   | EventItemBag, custom map rates, event-specific entries (per section) | same                   | same            | same                            |

Custom indices (for example `Exc Index="100"` in the shipped data for Aida) are fully supported: any system that calls the generator with that index pulls the matching row.

## Examples

{% tabs %}
{% tab title="High-Quality Server" %}
Increase base item quality for a more rewarding experience:

```xml
<!-- More common +3 to +5 drops -->
<Level Index="0" Rate0="4000" Rate1="2500" Rate2="1500" Rate3="1000"
       Rate4="500" Rate5="500" Rate6="0" ... Name="Level Option (Common)"/>

<!-- Higher luck chance -->
<Luck Index="0" Rate0="9000" Rate1="1000" Name="Luck Option (Common)"/>
```

{% endtab %}

{% tab title="Hardcore Server" %}
Make items rarer for challenging gameplay:

```xml
<!-- Almost all drops are +0 -->
<Level Index="0" Rate0="9500" Rate1="400" Rate2="100" Rate3="0"
       Rate4="0" ... Name="Level Option (Common)"/>

<!-- Very rare luck -->
<Luck Index="0" Rate0="9900" Rate1="100" Name="Luck Option (Common)"/>
```

{% endtab %}

{% tab title="Event Rewards" %}
Custom event reward tiers:

```xml
<!-- Guaranteed +7 to +9 items (EventItemBag range index) -->
<Level Index="41" Rate0="0" Rate1="0" ... Rate7="3334" Rate8="3333"
       Rate9="3333" ... Name="Level Option (EventItemBag) (7~9)"/>

<!-- Always 2-3 excellent options. Use a custom Index that no generator currently calls,
     or override the existing entry for the EventItemBag tier you want to retune. -->
<Exc Index="22" Rate0="0" Rate1="0" Rate2="5000" Rate3="5000"
     Rate4="0" Rate5="0" Rate6="0" Name="Exc Option (EventItemBag) (2~3)"/>
```

{% endtab %}
{% endtabs %}

## Common Issues

{% hint style="warning" %}
**Rates Do Not Sum To 10000**: The generator works with relative weights regardless of the total, but non-10000 totals make balance calculations harder to reason about. Keep totals at 10000.
{% endhint %}

{% hint style="warning" %}
**Wrong Index Used**: If items are not rolling the expected options, confirm which Index the calling system uses for that source (drop, mix, bag, event).
{% endhint %}

{% hint style="danger" %}
**All Rates Zero**: A row where every Rate is 0 returns no value. Socket rows with all zeros will leave items with no sockets; set rows with all zeros will skip ancient assignment.
{% endhint %}