# LuckyItem

This configuration file defines Lucky Items - special armor pieces with time-based durability decay and configurable enhancement options.

## File Location

```
GameServer/Data/Item/LuckyItem.xml
```

## Dependencies

| Depends On         | Purpose                                 |
| ------------------ | --------------------------------------- |
| Item.xml           | Item definitions by Index               |
| ItemOptionRate.xml | Option0-6 reference option rate indices |

## How It Works

1. Lucky items have time-based durability decay (same as Wings/Pendants, not damage-based)
2. Durability decreases every few seconds while equipped
3. Each item has configurable enhancement options (Option0-6)
4. Items are grouped for class-based availability
5. Jewel of Extension can restore durability to full (255) when between 1-254

## Structure

```xml
<LuckyItemList>
    <Item Index="3646" Group="0" Decay="2400"
          Option0="10" Option1="10" Option2="10" Option3="10"
          Option4="10" Option5="10" Option6="10" Comment="Scale Helm"/>
</LuckyItemList>
```

## Attributes

| Attribute | Type   | Description                                                                                                                                                               |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Index`   | int    | Item index (Category \* 512 + Type)                                                                                                                                       |
| `Group`   | int    | Lucky item group (0 or 1)                                                                                                                                                 |
| `Decay`   | int    | Decay threshold - Time until 1 durability point is lost (in ticks of 10 each second). Higher = slower decay. Example: 2400 = 240 seconds (4 minutes) per durability point |
| `Option0` | int    | Level option index (ItemOptionRate)                                                                                                                                       |
| `Option1` | int    | Skill option index                                                                                                                                                        |
| `Option2` | int    | Luck option index                                                                                                                                                         |
| `Option3` | int    | Excellent option index                                                                                                                                                    |
| `Option4` | int    | Additional level option index                                                                                                                                             |
| `Option5` | int    | Set option index                                                                                                                                                          |
| `Option6` | int    | Socket option index                                                                                                                                                       |
| `Comment` | string | Item name (optional, for reference)                                                                                                                                       |

### Index Calculation

```
Index = Category * 512 + Type
```

| Category | Base Index | Item Type |
| -------- | ---------- | --------- |
| 7        | 3584       | Helms     |
| 8        | 4096       | Armor     |
| 9        | 4608       | Pants     |
| 10       | 5120       | Gloves    |
| 11       | 5632       | Boots     |

## Examples

{% tabs %}
{% tab title="Helm Set" %}

```xml
<!-- Lucky Helms (Category 7, base index 3584) -->
<Item Index="3646" Group="0" Decay="2400"
      Option0="10" Option1="10" Option2="10" Option3="10"
      Option4="10" Option5="10" Option6="10" Comment="Scale Helm"/>
<Item Index="3650" Group="1" Decay="2400"
      Option0="10" Option1="10" Option2="10" Option3="10"
      Option4="10" Option5="10" Option6="10" Comment="Dark Soul Helm"/>
```

* Index 3646 = Category 7 \* 512 + Type 62
* Group 0 = Early-tier, Group 1 = Higher-tier
  {% endtab %}

{% tab title="Full Armor Set" %}

```xml
<!-- Storm Jahad Set pieces -->
<Item Index="3656" Group="1" Decay="2400" ... Comment="Storm Jahad Helm"/>
<Item Index="4168" Group="1" Decay="2400" ... Comment="Storm Jahad Armor"/>
<Item Index="4680" Group="1" Decay="2400" ... Comment="Storm Jahad Pants"/>
<Item Index="5704" Group="1" Decay="2400" ... Comment="Storm Jahad Boots"/>
```

Same Group value allows pieces to work together.
{% endtab %}

{% tab title="Custom Options" %}

```xml
<!-- High-tier item with faster decay -->
<Item Index="3650" Group="1" Decay="1800"
      Option0="10" Option1="10" Option2="10" Option3="11"
      Option4="10" Option5="10" Option6="10" Comment="Dark Soul Helm"/>
```

* Lower Decay = faster durability loss (1800 = 180 seconds = 3 minutes per point)
* Higher Decay = slower durability loss (2400 = 240 seconds = 4 minutes per point)
* Option3="11" = better excellent options
  {% endtab %}
  {% endtabs %}

## Important Behavior

{% hint style="info" %}
**Time-Based Decay**: Unlike normal items, lucky items lose durability over time while equipped, not from combat damage. The system checks every second and adds 10 to an internal counter. When the counter exceeds the Decay value, durability decreases by 1 and the counter resets.
{% endhint %}

{% hint style="info" %}
**Decay Calculation**: With Decay=2400, it takes 2400/10 = 240 seconds (4 minutes) per durability point. Total lifetime = Durability \* (Decay/10) seconds. Example: 255 durability at Decay=2400 = 1020 minutes (17 hours) of use.
{% endhint %}

{% hint style="info" %}
**Durability States**:

* 0 = Broken (unusable, cannot be repaired with Jewel of Extension)
* 1-254 = Usable (can be repaired to 255 with Jewel of Extension)
* 255 = Full (cannot use Jewel of Extension, already at max)
  {% endhint %}

{% hint style="info" %}
**Option Indices**: Option0-6 reference indices in ItemOptionRate.xml. These determine the enhancement values applied to the item.
{% endhint %}

{% hint style="info" %}
**Group Filtering**: GetLuckyItemIndex filters by category and group, and also checks class requirements from Item.xml.
{% endhint %}

{% hint style="warning" %}
**Version Requirement**: Lucky items require GAMESERVER\_UPDATE >= 502 to function. They're disabled in earlier versions.
{% endhint %}

{% hint style="warning" %}
**JoH Exclusion**: Lucky items (Type 62-72 in categories 7-11) cannot receive Jewel of Harmony options.
{% endhint %}

## Common Issues

{% hint style="warning" %}
**Item Not Recognized**: Verify the Index calculation is correct (Category \* 512 + Type) and matches Item.xml.
{% endhint %}

{% hint style="warning" %}
**Options Not Applied**: Check that Option0-6 values reference valid indices in ItemOptionRate.xml.
{% endhint %}

{% hint style="danger" %}
**Durability Tracking**: Lucky item durability is tracked separately via DataServer using `m_DurabilitySmall` field, which stores the internal decay counter. This is saved/loaded independently from the main durability value to persist the exact decay state across server restarts.
{% endhint %}

{% hint style="warning" %}
**Equipped Items Only**: Durability decay only occurs for items in equipped slots (2-6: Helm, Armor, Pants, Gloves, Boots). Items in inventory do not decay.
{% endhint %}
