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

# SocketItemOption

This configuration file defines the effects provided by seed spheres inserted into socket items: individual seed effects, set bonuses for specific element sequences in a single item, and global package bonuses that count element types across all equipped socket items.

## File Location

```
Data/Item/SocketItemOption.xml
```

## Dependencies

| Depends On                                              | Purpose                                                                  |
| ------------------------------------------------------- | ------------------------------------------------------------------------ |
| [SocketItemType.xml](/docs/data/item/socketitemtype.md) | Defines which items can have sockets and element restrictions by section |
| [ItemOptionRate.xml](/docs/data/item/itemoptionrate.md) | SocketOptions table rolls the per-drop socket count                      |

Related references:

* [Item.xml](/docs/data/item/item.md) for section and type numbering
* [ItemOption.xml](/docs/data/item/itemoption.md) and the [OptionIndex reference](/docs/data/item/optionindex-reference.md) for the standard (non-socket) option enum; socket options use their own enum documented below

## Structure Overview

The file has three sections:

1. **Options** - individual seed sphere effects, keyed by `Index`
2. **BonusOptions** - per-item set bonuses triggered when a specific element sequence fills the first socket slots in order
3. **PackageOptions** - global bonuses triggered when equipped socket items together contain at least the required count of each element type

## Options Section

Defines the effect of each seed sphere type.

```xml
<Options>
    <Option Index="0" Type="1" SubIndex="0"
            Name="Attack power increase" Rate="20"
            Value1="17" Value2="19" Value3="21" Value4="23" Value5="25"
            OptionType="3"/>
</Options>
```

### Option Attributes

| Attribute    | Type   | Description                                                                                                                                                                                                                                                         |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Index`      | int    | Seed option ID (see [Seed Options](#seed-options)). Valid range 0-49.                                                                                                                                                                                               |
| `Type`       | int    | Element type (1-6).                                                                                                                                                                                                                                                 |
| `SubIndex`   | int    | Sub-index within the element type. Used by seed creation and client display.                                                                                                                                                                                        |
| `Name`       | string | Display name (max 31 chars).                                                                                                                                                                                                                                        |
| `Rate`       | int    | Selection weight used when picking a random option of the given element type.                                                                                                                                                                                       |
| `Value1-5`   | int    | Effect value at sphere levels 1-5.                                                                                                                                                                                                                                  |
| `OptionType` | int    | Client-side display hint: `1`=flat, `2`=percent, `3`=scaled by character level, `4`=scaled by Max HP, `5`=scaled by Max MP. Defaults to `1`. The server always reads the value from `Value1-5` based on sphere level; the actual formula is fixed per option index. |

### Element Types

| Type | Element   | Theme                     |
| ---- | --------- | ------------------------- |
| 1    | Fire      | Attack / damage           |
| 2    | Water     | Defense / block           |
| 3    | Ice       | Skill / hunt              |
| 4    | Wind      | Recovery / HP and MP pool |
| 5    | Lightning | Critical / excellent      |
| 6    | Earth     | Base stats                |

Weapons (Sections 0-5, excluding Arrows at 4/7 and Bolts at 4/15) can only roll Fire, Ice, and Lightning seeds. Armor pieces (Sections 6-11) can only roll Water, Wind, and Earth seeds.

### Seed Options

The list below reflects the stock XML. Every entry fires a dedicated stat addition in the server's socket applier; "Formula" describes what the server actually does with `Value`.

#### Fire Element (Type 1) - Attack

| Index | Name                                    | Formula                                                                                                                                       |
| ----- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 0     | Attack power increase (scales by level) | All damage min/max += `CharacterLevel / Value`. Lower `Value` = more damage.                                                                  |
| 1     | Attack speed increase                   | PhysiSpeed and MagicSpeed += `Value`.                                                                                                         |
| 2     | Minimum attack power increase           | Min physical, min magic, and min curse damage += `Value`. (Stock XML mislabels this as "Maximum"; the server handler is the min-damage case.) |
| 3     | Maximum attack power increase           | Max physical, max magic, and max curse damage += `Value`. (Stock XML mislabels this as "Minimum"; the server handler is the max-damage case.) |
| 4     | Attack power increase                   | All damage min and max (Physi, Magic, Curse) += `Value`.                                                                                      |
| 5     | AG consumption decrease                 | `BPConsumptionRate` -= `Value`. Lowers the AG cost multiplier on skills.                                                                      |

{% hint style="warning" %}
Indices 2 and 3 in stock XML have their `Name` attributes swapped relative to the server's enum. The effect applied in game matches the enum (2 = min, 3 = max), not the display name. If you rely on the display name stay consistent across client and server.
{% endhint %}

#### Water Element (Type 2) - Defense

| Index | Name                       | Formula                                                                                                  |
| ----- | -------------------------- | -------------------------------------------------------------------------------------------------------- |
| 10    | Block rating increase      | `DefenseSuccessRate` += `DefenseSuccessRate * Value / 100` (percent multiplier on current defense rate). |
| 11    | Defense increase           | `Defense` += `Value`.                                                                                    |
| 12    | Shield protection increase | `ShieldDamageReduction` += `Value` (percent).                                                            |
| 13    | Damage reduction           | Socket slot of the damage-reduction table += `Value`.                                                    |
| 14    | Damage reflection          | `DamageReflect` += `Value`.                                                                              |

#### Ice Element (Type 3) - Skill / Hunt

| Index | Name                         | Formula                                                                                                                               |
| ----- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| 16    | Monster attack HP recovery   | `HuntHP` += `100 / Value`. Lower `Value` yields a higher HuntHP percent. On kill, HP restored = `MaxHP * HuntHP / 100 + TargetLevel`. |
| 17    | Monster attack MP recovery   | `HuntMP` += `100 / Value`. Lower `Value` yields a higher HuntMP percent. On kill, MP restored = `MaxMP * HuntMP / 100`.               |
| 18    | Skill attack increase        | `SkillDamageBonus` += `Value`.                                                                                                        |
| 19    | Attack success rate increase | `AttackSuccessRate` += `Value`.                                                                                                       |
| 20    | Item durability increase     | Weapon and armor durability rate += `Value` (percent).                                                                                |

{% hint style="info" %}
Indices 16 and 17 store `100 / Value`, not `HP / Value`. With `Value = 4` the sphere adds 25 to HuntHP or HuntMP, which is then applied as a percent of the character's max pool when monsters are killed.
{% endhint %}

#### Wind Element (Type 4) - Recovery / Pool

| Index | Name                 | Formula                                                        |
| ----- | -------------------- | -------------------------------------------------------------- |
| 21    | HP recovery increase | `HPRecovery` += `Value`.                                       |
| 22    | Maximum HP increase  | `AddLife` += `MaxLife * Value / 100` (percent of base Max HP). |
| 23    | Maximum MP increase  | `AddMana` += `MaxMana * Value / 100` (percent of base Max MP). |
| 24    | MP recovery increase | `MPRecovery` += `Value`.                                       |
| 25    | Maximum AG increase  | `AddBP` += `Value`.                                            |
| 26    | AG recovery increase | `BPRecovery` += `Value`.                                       |

#### Lightning Element (Type 5) - Critical / Excellent

| Index | Name                           | Formula                           |
| ----- | ------------------------------ | --------------------------------- |
| 29    | Excellent damage increase      | `ExcellentDamage` += `Value`.     |
| 30    | Excellent damage rate increase | `ExcellentDamageRate` += `Value`. |
| 31    | Critical damage increase       | `CriticalDamage` += `Value`.      |
| 32    | Critical damage rate increase  | `CriticalDamageRate` += `Value`.  |

#### Earth Element (Type 6) - Base Stats

| Index | Name               | Formula                    |
| ----- | ------------------ | -------------------------- |
| 34    | Strength increase  | `AddStrength` += `Value`.  |
| 35    | Dexterity increase | `AddDexterity` += `Value`. |
| 36    | Vitality increase  | `AddVitality` += `Value`.  |
| 37    | Energy increase    | `AddEnergy` += `Value`.    |

{% hint style="info" %}
Earth seeds (34-37) are applied in a separate pass from the rest. They feed the character's base stat adds; the other options feed derived combat fields.
{% endhint %}

### Seed Byte Encoding

Each filled socket slot on an item stores a single byte: `Index + Level * 50`, where `Index` is the seed option ID above and `Level` is the sphere level (0-4, representing spheres 1-5). Sentinel values are `0xFE` for an empty slot and `0xFF` for a non-existent slot.

## BonusOptions Section

Grants a bonus to an item when its first N socket slots contain a specific element sequence.

```xml
<BonusOptions>
    <BonusOption Index="0" MinItemSection="0" MaxItemSection="4"
                 Name="Attack power bonus" Value="11"
                 ReqOptionType1="1" ReqOptionType2="5" ReqOptionType3="3"
                 ReqOptionType4="0" ReqOptionType5="0"/>
</BonusOptions>
```

### BonusOption Attributes

| Attribute          | Type   | Description                                                                                                                                                                                                                                                                                 |
| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Index`            | int    | Bonus option ID (0-49).                                                                                                                                                                                                                                                                     |
| `MinItemSection`   | int    | Minimum item section the bonus applies to.                                                                                                                                                                                                                                                  |
| `MaxItemSection`   | int    | Maximum item section the bonus applies to.                                                                                                                                                                                                                                                  |
| `Name`             | string | Display name (max 31 chars).                                                                                                                                                                                                                                                                |
| `Value`            | int    | Effect value.                                                                                                                                                                                                                                                                               |
| `ReqOptionType1-5` | int    | Required element type at each socket slot in order. `0` means the slot is not checked. The check is positional: slot 1 must hold an element of `ReqOptionType1`, slot 2 of `ReqOptionType2`, and so on. If a required slot is empty or holds the wrong element, the bonus does not trigger. |

### Bonus Types (stock)

| Index | Sections      | Name               | Required Elements             | Effect                                          |
| ----- | ------------- | ------------------ | ----------------------------- | ----------------------------------------------- |
| 0     | 0-4 (weapons) | Attack power bonus | Fire(1), Lightning(5), Ice(3) | All damage min/max += `Value`.                  |
| 1     | 0-4 (weapons) | Skill damage bonus | Lightning(5), Ice(3), Fire(1) | `SkillDamageBonus` += `Value`.                  |
| 2     | 5 (staffs)    | Magic power bonus  | Fire(1), Lightning(5), Ice(3) | Physical and magical damage min/max += `Value`. |
| 3     | 5 (staffs)    | Skill damage bonus | Lightning(5), Ice(3), Fire(1) | `SkillDamageBonus` += `Value`.                  |
| 4     | 6-12 (armor)  | Defense bonus      | Water(2), Earth(6), Wind(4)   | `Defense` += `Value`.                           |
| 5     | 6-12 (armor)  | Max HP bonus       | Earth(6), Wind(4), Water(2)   | `AddLife` += `Value`.                           |

Each equipped socket item is evaluated independently and only the first matching bonus is applied to that item.

## PackageOptions Section

Grants a global bonus when the character's equipped socket items together contain at least the required number of seeds of each element type.

```xml
<PackageOptions>
    <PackageOption Index="0" Name="Double damage rate" Value="3"
                   ReqOptionTypeCount1="1" ReqOptionTypeCount2="1"
                   ReqOptionTypeCount3="1" ReqOptionTypeCount4="1"
                   ReqOptionTypeCount5="1" ReqOptionTypeCount6="0"/>
</PackageOptions>
```

### PackageOption Attributes

| Attribute               | Type   | Description                                                                                                                                                                                                                                    |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Index`                 | int    | Package option ID (0-49).                                                                                                                                                                                                                      |
| `Name`                  | string | Display name (max 31 chars).                                                                                                                                                                                                                   |
| `Value`                 | int    | Effect value.                                                                                                                                                                                                                                  |
| `ReqOptionTypeCount1-6` | int    | Minimum required count per element type (1=Fire, 2=Water, 3=Ice, 4=Wind, 5=Lightning, 6=Earth) summed across all equipped socket items. The check is "at least this many"; having more seeds of a type than required still triggers the bonus. |

### Package Options (stock)

| Index | Name                | Required Counts (Fire / Water / Ice / Wind / Lightning / Earth) | Effect                                    |
| ----- | ------------------- | --------------------------------------------------------------- | ----------------------------------------- |
| 0     | Double damage rate  | 1 / 1 / 1 / 1 / 1 / 0                                           | `DoubleDamageRate` += `Value` (stock 3).  |
| 1     | Ignore defense rate | 1 / 1 / 3 / 1 / 1 / 0                                           | `IgnoreDefenseRate` += `Value` (stock 1). |

## Examples

{% tabs %}
{% tab title="Fire Seed" %}

```xml
<!-- Attack power increase scaled by level - sphere level 5 uses Value5=25 -->
<Option Index="0" Type="1" SubIndex="0"
        Name="Attack power increase" Rate="20"
        Value1="17" Value2="19" Value3="21" Value4="23" Value5="25"
        OptionType="3"/>
```

At character level 400 with sphere level 5, all damage min/max gain `400 / 25 = 16`. Lower `ValueN` increases the per-level bonus.
{% endtab %}

{% tab title="Weapon Bonus" %}

```xml
<!-- Weapon with slot1=Fire, slot2=Lightning, slot3=Ice grants +11 Attack -->
<BonusOption Index="0" MinItemSection="0" MaxItemSection="4"
             Name="Attack power bonus" Value="11"
             ReqOptionType1="1" ReqOptionType2="5" ReqOptionType3="3"
             ReqOptionType4="0" ReqOptionType5="0"/>
```

The three slots must hold seeds of these element types in this order. Other elements at those slots break the bonus.
{% endtab %}

{% tab title="Package Bonus" %}

```xml
<!-- At least one seed of each element except Earth gives +3% double damage rate -->
<PackageOption Index="0" Name="Double damage rate" Value="3"
               ReqOptionTypeCount1="1" ReqOptionTypeCount2="1"
               ReqOptionTypeCount3="1" ReqOptionTypeCount4="1"
               ReqOptionTypeCount5="1" ReqOptionTypeCount6="0"/>
```

Seeds are counted across all equipped socket items. Extra copies above the requirement still satisfy the check.
{% endtab %}
{% endtabs %}

## Important Behavior

{% hint style="info" %}
**Sphere Level**: Seeds have levels 1-5. Each level maps to `Value1` through `Value5`. The level is encoded into the socket byte alongside the option index.
{% endhint %}

{% hint style="info" %}
**Bonus Sequence Matching**: BonusOptions are positional. Slot 1 must hold the element at `ReqOptionType1`, slot 2 the element at `ReqOptionType2`, and so on. A slot set to `0` in the requirement is ignored but any slot past it must still match if it is non-zero.
{% endhint %}

{% hint style="info" %}
**Package Counts Are Minimums**: PackageOptions compare required counts with `>=`. Having more seeds of a type than asked for does not prevent the bonus.
{% endhint %}

{% hint style="warning" %}
**Rate Is A Weight**: `Rate` on an Option is only used when the server picks a random seed of a given element type. It is not a drop rate.
{% endhint %}

{% hint style="info" %}
**Element Restrictions**: Weapons and staffs only accept Fire, Ice, and Lightning seeds. Armor pieces only accept Water, Wind, and Earth seeds. See [SocketItemType.xml](/docs/data/item/socketitemtype.md).
{% endhint %}

{% hint style="warning" %}
**Index Limits**: Each section (Options, BonusOptions, PackageOptions) accepts indices in the range 0-49. Indices outside that range are silently dropped by the loader.
{% endhint %}

## Common Issues

{% hint style="warning" %}
**Bonus Not Triggering**: Check that the element sequence is an exact positional match. Fire-Lightning-Ice is different from Lightning-Ice-Fire.
{% endhint %}

{% hint style="warning" %}
**Wrong Item Section**: BonusOptions filter by item section. Weapon bonuses (0-4) do not apply to armor (6-12). Staff bonuses (section 5) do not apply to non-staff weapons.
{% endhint %}

{% hint style="danger" %}
**Swapped Min/Max Labels**: Stock XML names indices 2 and 3 as "Maximum" and "Minimum" respectively, but the server applies them as "Minimum" and "Maximum". Do not rename these based on the display text alone.
{% endhint %}

{% hint style="danger" %}
**HP/MP Recovery Direction**: Indices 16 and 17 use `100 / Value` for the stored bonus. Higher `Value` means less HuntHP/HuntMP per kill. Do not confuse with flat additive options.
{% endhint %}