# JewelOfHarmonyOption

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

## File Location

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

## Dependencies

| Depends On             | Purpose                             |
| ---------------------- | ----------------------------------- |
| JewelOfHarmonyType.xml | Defines which items can receive JoH |

## How It Works

### Jewel of Harmony (Normal Items)

1. When Jewel of Harmony is applied to an eligible item
2. Server determines item type (Weapon, Staff, or Armor)
3. Selects random option from the appropriate section using Rate weights
4. Filters options by item Level requirement
5. Stores option type (upper 4 bits) and level (lower 4 bits) in `m_JewelOfHarmonyOption`
6. **Initial JoH level is set to the option's Level attribute** (e.g., Level=7 option starts at JoH level 7)
7. Smelt Stone upgrades increase the option level up to item level or 12 (max JoH level 12)

### Jewel of Elevation (Lucky Items)

1. Works only on Lucky Items (items with Luck option)
2. Same option selection process
3. **Initial JoH level is set to item's +level, capped at 13** (e.g., +15 item starts at JoH level 13)
4. Cannot be upgraded with Smelt Stone
5. This allows high-level options (Level=13) to be applied with maximum bonuses immediately

## 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 (see enum per section)     |
| `Name`      | string | Display name                            |
| `Rate`      | int    | Selection weight (higher = more likely) |
| `Level`     | int    | Minimum item level to apply this option |
| `Value0-15` | int    | Bonus value at each JoH level (0-15)    |
| `Money0-15` | int    | Zen cost to restore at each JoH level   |

## Weapon Options (eJewelOfHarmonyOption)

| Index | Name                        | Effect                      | Level Req |
| ----- | --------------------------- | --------------------------- | --------- |
| 1     | Add Min Physical Damage     | +value min damage           | 0         |
| 2     | Add Max Physical Damage     | +value max damage           | 0         |
| 3     | Sub Require Strength        | -value STR requirement      | 0         |
| 4     | Sub Require Dexterity       | -value AGI requirement      | 0         |
| 5     | Add Physical Damage         | +value min AND max damage   | 7         |
| 6     | Add Critical Damage         | +value critical damage      | 7         |
| 7     | Add Skill Damage            | +value skill damage         | 10        |
| 8     | Add Attack Success Rate PvP | +value% attack rate in PvP  | 11        |
| 9     | Sub SD Rate                 | -value% enemy SD absorption | 10        |
| 10    | Add SD Ignore Rate          | +value% SD bypass           | 13        |

## Staff Options

| Index | Name                        | Effect                      | Level Req |
| ----- | --------------------------- | --------------------------- | --------- |
| 1     | Add Magic Damage            | +value magic damage         | 0         |
| 2     | Sub Require Strength        | -value STR requirement      | 0         |
| 3     | Sub Require Dexterity       | -value AGI requirement      | 0         |
| 4     | Add Skill Damage            | +value skill damage         | 7         |
| 5     | Add Critical Damage         | +value critical damage      | 7         |
| 6     | Sub SD Rate                 | -value% enemy SD absorption | 10        |
| 7     | Add Attack Success Rate PvP | +value% attack rate in PvP  | 11        |
| 8     | Add SD Ignore Rate          | +value% SD bypass           | 13        |

## Armor Options

| Index | Name                         | Effect                      | Level Req |
| ----- | ---------------------------- | --------------------------- | --------- |
| 1     | Add Defense                  | +value defense              | 0         |
| 2     | Add Max BP                   | +value AG (Stamina)         | 4         |
| 3     | Add Max HP                   | +value HP                   | 4         |
| 4     | Add HP Recovery              | +value HP regen             | 7         |
| 5     | Add MP Recovery              | +value MP regen             | 10        |
| 6     | Add Defense Success Rate PvP | +value% defense rate in PvP | 11        |
| 7     | Add Damage Reduction         | +value% damage reduction    | 10        |
| 8     | Add SD Rate                  | +value% SD absorption       | 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 level
* Value scales from +2 at JoH 0 to +20 at JoH 13+
  {% 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 item
* **When applied, immediately starts at JoH level 13 with 5% SD ignore bonus**
* Cannot be upgraded further (max JoH level is 12 via Smelt Stone, but this already starts at 13)
* This is a "Lucky Item" only option (Jewel of Elevation for +13 items)
  {% 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 STR requirement by the value. At JoH 13, reduces by 40 STR. This option is skipped if the item has no STR requirement.
{% endtab %}
{% endtabs %}

## Important Behavior

{% hint style="info" %}
**JoH Level Storage**: The option is stored as a single byte - upper 4 bits = option type (1-10), lower 4 bits = JoH level (0-15). This limits max JoH level to 15.
{% endhint %}

{% hint style="info" %}
**Initial JoH Level**: When first applied, JoH level starts at the option's Level attribute, NOT at 0. A Level=7 option immediately starts at JoH level 7 with full bonuses.
{% endhint %}

{% hint style="info" %}
**Option Level vs Item Level**: JoH level cannot exceed item level. A +7 item can only have JoH level 0-7, so high-level options (Level=10+) cannot be upgraded on low-level items.
{% endhint %}

{% hint style="info" %}
**Smelt Stone Max**: Smelt Stone can upgrade JoH level up to item level or 12, whichever is lower. Stops at level 12 - cannot upgrade from 12 to 13.
{% endhint %}

{% hint style="info" %}
**Maximum JoH Level**: Max level is 13 (via Jewel of Elevation on +13+ Lucky Items). Regular items max out at 12 via Smelt Stone.
{% endhint %}

{% hint style="info" %}
**Requirement Options Filtering**: Sub Require Strength/Dexterity options are automatically excluded if the item doesn't have that requirement.
{% endhint %}

{% hint style="warning" %}
**Rate for Selection**: Higher Rate = more likely to be selected. An option with Rate=50 is 5x more likely than Rate=10.
{% endhint %}

{% hint style="warning" %}
**Money Cost**: Money values are for JoH restoration (removing JoH at Elpis NPC), not application cost.
{% endhint %}

## Common Issues

{% hint style="warning" %}
**Option Not Available**: Check that item level meets the option's Level requirement.
{% endhint %}

{% hint style="warning" %}
**Initial Bonus**: When first applied, JoH level equals the option's Level attribute. Options with Level=7 start at JoH level 7, immediately granting Value7 bonus (not Value0). Options with Level=0 start at JoH level 0.
{% endhint %}

{% hint style="danger" %}
**Socket Items Excluded**: Socket items cannot receive Jewel of Harmony. The check is explicit in source code.
{% endhint %}
