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

# JewelOfHarmonyOption

This configuration file defines the available Jewel of Harmony (JoH) enhancement options, their bonus values at each level, and Zen restoration costs.

## File Location

```
Data/Item/JewelOfHarmonyOption.xml
```

## Dependencies

| Depends On                      | Purpose                                                                                            |
| ------------------------------- | -------------------------------------------------------------------------------------------------- |
| [Item](/docs/data/item/item.md) | Provides item categories and per-item Strength/Dexterity requirements used during option filtering |

| Related                                                                 | Purpose                                                                                                                           |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [JewelOfHarmonyType](/docs/data/item/jewelofharmonytype.md)             | Controls which items can be smelted into Refining Stones in the Chaos Machine (separate system; not used to gate JoH application) |
| [ItemOption](/docs/data/item/itemoption.md)                             | Related option fields stored on items                                                                                             |
| [Item Option Index Reference](/docs/data/item/optionindex-reference.md) | Reference for the option-index conventions used on items                                                                          |

## How It Works

### Jewel of Harmony (Normal Items)

1. Player applies a Jewel of Harmony to an eligible item
2. Server determines item type group: Weapon, Staff, or Armor (see Category Eligibility below)
3. Selects a random option from that group using Rate weights
4. Filters out options whose Level attribute exceeds the item's enhancement level
5. Filters out Sub Require Strength / Sub Require Dexterity options when the item has no such requirement
6. Stores option in the item's JoH option byte: upper 4 bits = option index, lower 4 bits = JoH level
7. Initial JoH level equals the option's Level attribute (a Level=7 option starts at JoH level 7 with Value7 bonus)
8. Smelt Stone can later increase the JoH level

### Jewel of Elevation (Lucky Items)

1. Works only on Lucky Items
2. Rejected if the target item is already JoH'd or is a Socket item
3. Set Item restriction is NOT enforced for Elevation (only for Jewel of Harmony)
4. Same option selection process as Jewel of Harmony
5. Initial JoH level is set to the item's enhancement level, capped at 15
6. Smelt Stone is effectively useless afterward because the JoH level already equals the item's enhancement level, and Smelt Stone refuses to raise the JoH level past the item's enhancement level
7. Allows high-Level options to start with high bonuses immediately on a high enhancement item

### Smelt Stone Upgrade

1. Increases the current JoH level by 1 on success
2. On failure, the JoH level is reset to the option's base Level attribute (not to 0, and not preserved)
3. Cannot upgrade if current JoH level is already at the item's enhancement level
4. Cannot upgrade if current JoH level is already 15 (maximum table index)
5. Lower Refining Stone uses one success rate, Higher Refining Stone uses a separate (typically higher) rate

## Structure

```xml
<JewelOfHarmonyOptionList>
    <WeaponOptions>
        <Option Index="1" Name="Add Min Physical Damage" Rate="50" Level="0"
                Value0="2" Value1="3" ... Value15="20"
                Money0="100000" Money1="110000" ... Money15="500000"/>
    </WeaponOptions>
    <StaffOptions>
        <!-- Staff-specific options -->
    </StaffOptions>
    <ArmorOptions>
        <!-- Armor-specific options -->
    </ArmorOptions>
</JewelOfHarmonyOptionList>
```

## Attributes

| Attribute   | Type   | Description                                                                                         |
| ----------- | ------ | --------------------------------------------------------------------------------------------------- |
| `Index`     | int    | Option index within the section (1-15)                                                              |
| `Name`      | string | Display name (informational)                                                                        |
| `Rate`      | int    | Selection weight (higher = more likely)                                                             |
| `Level`     | int    | Minimum item enhancement level required to roll this option, and the initial JoH level once applied |
| `Value0-15` | int    | Bonus value at each JoH level (0-15)                                                                |
| `Money0-15` | int    | Zen cost to restore (remove) JoH at that level                                                      |

## Category Eligibility

JoH application checks the item's category directly. [JewelOfHarmonyType](/docs/data/item/jewelofharmonytype.md) is NOT consulted for the application path; it only affects the Chaos Machine Smelt Mix that creates Refining Stones.

| Group  | Categories      | Notes                                        |
| ------ | --------------- | -------------------------------------------- |
| Weapon | Categories 0-4  | Excludes item 4/7 and item 4/15 (ammunition) |
| Staff  | Category 5      | All items                                    |
| Armor  | Categories 6-11 | All items at the category check              |

Additional exclusions applied to ALL groups during Jewel of Harmony application:

* Items that already carry a JoH option are rejected
* Socket items are rejected
* Set items are rejected unless `SetItemAcceptHarmonySwitch=1` is set in server config
* Lucky Items (Category 7-11 with Type between 62 and 72) are rejected; they use the Jewel of Elevation path instead

## Weapon Options

| Index | Name                        | Effect                                     | Level Req |
| ----- | --------------------------- | ------------------------------------------ | --------- |
| 1     | Add Min Physical Damage     | +value to min physical damage              | 0         |
| 2     | Add Max Physical Damage     | +value to max physical damage              | 0         |
| 3     | Sub Require Strength        | -value Strength requirement                | 0         |
| 4     | Sub Require Dexterity       | -value Dexterity (Agility) requirement     | 0         |
| 5     | Add Physical Damage         | +value to both min AND max physical damage | 7         |
| 6     | Add Critical Damage         | +value to critical damage                  | 7         |
| 7     | Add Skill Damage            | +value to skill damage                     | 10        |
| 8     | Add Attack Success Rate PvP | +value to attack success rate in PvP       | 11        |
| 9     | Sub SD Rate                 | +value% to enemy SD decrease rate          | 10        |
| 10    | Add SD Ignore Rate          | +value% chance to ignore enemy SD          | 13        |

## Staff Options

| Index | Name                        | Effect                                 | Level Req |
| ----- | --------------------------- | -------------------------------------- | --------- |
| 1     | Add Magic Damage            | +value to min and max magic damage     | 0         |
| 2     | Sub Require Strength        | -value Strength requirement            | 0         |
| 3     | Sub Require Dexterity       | -value Dexterity (Agility) requirement | 0         |
| 4     | Add Skill Damage            | +value to skill damage                 | 7         |
| 5     | Add Critical Damage         | +value to critical damage              | 7         |
| 6     | Sub SD Rate                 | +value% to enemy SD decrease rate      | 10        |
| 7     | Add Attack Success Rate PvP | +value to attack success rate in PvP   | 11        |
| 8     | Add SD Ignore Rate          | +value% chance to ignore enemy SD      | 13        |

## Armor Options

| Index | Name                         | Effect                                | Level Req |
| ----- | ---------------------------- | ------------------------------------- | --------- |
| 1     | Add Defense                  | +value to defense                     | 0         |
| 2     | Add Max BP                   | +value to AG (Stamina) pool           | 4         |
| 3     | Add Max HP                   | +value to maximum HP                  | 4         |
| 4     | Add HP Recovery              | +value to HP regeneration             | 7         |
| 5     | Add MP Recovery              | +value to MP regeneration             | 10        |
| 6     | Add Defense Success Rate PvP | +value to defense success rate in PvP | 11        |
| 7     | Add Damage Reduction         | +value% damage reduction (JoH slot)   | 10        |
| 8     | Add SD Rate                  | +value% to SD absorption rate         | 13        |

## Examples

{% tabs %}
{% tab title="Weapon Option" %}

```xml
<Option Index="1" Name="Add Min Physical Damage" Rate="50" Level="0"
        Value0="2" Value1="3" Value2="4" Value3="5" Value4="6"
        Value5="7" Value6="9" Value7="11" Value8="12" Value9="14"
        Value10="15" Value11="16" Value12="17" Value13="20" Value14="20" Value15="20"
        Money0="100000" Money1="110000" Money2="120000" .../>
```

* Rate=50: Common option
* Level=0: Available at any item enhancement level
* Initial JoH level when applied is 0 with +2 bonus
* Smelt Stone can upgrade up to the item's enhancement level (max 15)
  {% endtab %}

{% tab title="High-Level Option" %}

```xml
<Option Index="10" Name="Add SD Ignore Rate" Rate="10" Level="13"
        Value0="0" Value1="0" ... Value12="0" Value13="5" Value14="10" Value15="10"
        Money0="0" Money1="0" ... Money12="0" Money13="400000" .../>
```

* Rate=10: Rare option
* Level=13: Requires +13 (or higher) item to roll this option
* When applied, initial JoH level is 13 with the Value13 bonus (5%)
* Smelt Stone can still raise it toward 14 / 15 if the item is +14 or +15
  {% endtab %}

{% tab title="Requirement Reduction" %}

```xml
<Option Index="3" Name="Sub Require Strength" Rate="40" Level="0"
        Value0="6" Value1="8" Value2="10" ... Value13="40" Value14="40" Value15="40"
        Money0="100000" Money1="110000" .../>
```

Reduces Strength requirement by Value at the current JoH level. At JoH 13, reduces by 40. This option is filtered out when rolling JoH on items that have no Strength requirement.
{% endtab %}
{% endtabs %}

## Important Behavior

{% hint style="info" %}
**JoH Level Storage**: The JoH option is packed into a single byte. Upper 4 bits hold the option index (1-15), lower 4 bits hold the JoH level (0-15). The maximum JoH level is therefore 15.
{% endhint %}

{% hint style="info" %}
**Initial JoH Level**: When first applied, the JoH level is set to the option's Level attribute, not 0. A Level=7 option immediately grants Value7. A Level=0 option starts at JoH level 0 with Value0.
{% endhint %}

{% hint style="info" %}
**Option Level vs Item Level**: At calculation time the JoH level is ignored if it exceeds the item's enhancement level. Smelt Stone also refuses to upgrade past the item's enhancement level.
{% endhint %}

{% hint style="info" %}
**Smelt Stone Maximum**: Smelt Stone stops upgrading once the JoH level reaches either the item's enhancement level OR 15, whichever is lower.
{% endhint %}

{% hint style="warning" %}
**Smelt Stone Failure Resets to Base Level**: If Smelt Stone fails the random roll, the current JoH level is reset to the option's Level attribute (not preserved, not zeroed). Plan around this.
{% endhint %}

{% hint style="info" %}
**Jewel of Elevation Cap**: Initial JoH level under Elevation is set to the item's enhancement level, capped at 15.
{% endhint %}

{% hint style="info" %}
**Requirement Options Filtering**: Sub Require Strength / Sub Require Dexterity options are excluded from the random pool if the item has no Strength / Dexterity requirement.
{% endhint %}

{% hint style="warning" %}
**Rate for Selection**: Higher Rate = higher selection weight. Rate=50 is five times more likely than Rate=10 (within the same eligible pool after Level and requirement filtering).
{% endhint %}

{% hint style="warning" %}
**Money Cost**: Money values are the Zen cost paid at the JoH Restore Mix to remove the option, not the application cost.
{% endhint %}

## Common Issues

{% hint style="warning" %}
**Option Not Available**: The item's enhancement level must meet the option's Level. Sub Require options require the item to actually have that requirement.
{% endhint %}

{% hint style="warning" %}
**Initial Bonus Higher Than Expected**: This is intentional. Options with Level>0 start at JoH level = Level, granting the corresponding Value immediately.
{% endhint %}

{% hint style="danger" %}
**Socket Items Excluded**: Socket items cannot receive Jewel of Harmony or Jewel of Elevation; both application paths block the combination.
{% endhint %}

{% hint style="danger" %}
**Lucky Items Use Elevation, Not Harmony**: Applying a Jewel of Harmony to a Lucky Item is blocked. Lucky Items must use the Jewel of Elevation path instead.
{% endhint %}

{% hint style="info" %}
**Success Rate**: Jewel of Harmony and Jewel of Elevation share the same per-account-level success rate (`HarmonySuccessRate`). On failure the jewel is consumed and the target item is unchanged. Smelt Stone uses two separate rates (`SmeltStoneSuccessRate1` for Lower Refining Stone, `SmeltStoneSuccessRate2` for Higher Refining Stone).
{% endhint %}