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

# LuckyItem

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

## File Location

```
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, not damage-based
2. Durability decreases over time while equipped (one point every Decay seconds)
3. Each item has configurable enhancement options (Option0-6)
4. Items are grouped into pools that the Lucky Ticket chaos mix picks from
5. Jewel of Extension restores durability to full (255) when current durability is between 1 and 254
6. Jewel of Elevation raises the item's Jewel of Harmony option level
7. Jewel of Harmony cannot be applied to Lucky items (use Jewel of Elevation instead)
8. The fractional decay counter (DurabilitySmall) is persisted to the DataServer at save time and on logout, so progress survives restarts and map changes

## 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. The internal counter rises by an effective rate of 1 unit per second of equipped wear; when the counter exceeds this value, durability drops by 1 and the counter resets to 0. Decay therefore equals the number of seconds per durability point. Example: 2400 = 2400 seconds (40 minutes) per durability point |
| `Option0` | int    | ItemOptionRate index used to roll the item's +Level                                                                                                                                                                                                                                                                               |
| `Option1` | int    | ItemOptionRate index used to roll the skill option (0/1)                                                                                                                                                                                                                                                                          |
| `Option2` | int    | ItemOptionRate index used to roll the luck option (0/1)                                                                                                                                                                                                                                                                           |
| `Option3` | int    | ItemOptionRate index used to roll the additional option (+4/+8/+12/+16 tier)                                                                                                                                                                                                                                                      |
| `Option4` | int    | ItemOptionRate index used to roll excellent options                                                                                                                                                                                                                                                                               |
| `Option5` | int    | ItemOptionRate index used to roll the ancient/set option                                                                                                                                                                                                                                                                          |
| `Option6` | int    | ItemOptionRate index used to roll the socket seed option                                                                                                                                                                                                                                                                          |
| `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 and Group 1 are two independent pools. The Lucky Ticket chaos mix picks one item at random from the pool that matches the ticket's group and category, filtered by the player's class.
  {% 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"/>
```

Each armor slot is rolled independently. Grouping a full set under Group 1 means the Lucky Ticket for that category always returns a piece of this tier.
{% 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 = 1800 seconds = 30 minutes per point)
* Higher Decay = slower durability loss (2400 = 2400 seconds = 40 minutes per point)
* Option3="11" references a different ItemOptionRate entry, typically one with higher roll weights
  {% 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 character second-tick raises an internal counter at an effective rate of 1 unit per second of wear. When the counter exceeds the Decay value, durability decreases by 1 and the counter resets to 0. Combat damage does not contribute to a lucky item's wear.
{% endhint %}

{% hint style="info" %}
**Decay Calculation**: The Decay value equals the number of seconds between durability losses. With Decay=2400, 1 durability point is lost every 2400 seconds (40 minutes). Total wear lifetime at full 255 durability = 255 \* Decay seconds. Example: 255 durability at Decay=2400 = 170 hours of equipped 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 rows in [ItemOptionRate](/docs/data/item/itemoptionrate.md). Option0 drives the +Level roll, Option1 the skill flag, Option2 the luck flag, Option3 the additional-option tier, Option4 the excellent options, Option5 the ancient/set option, and Option6 the socket seed option. Each Option attribute is passed through the matching ItemOptionRate section, so the rolled outcome is whatever that row's weights produce.
{% endhint %}

{% hint style="info" %}
**Lucky Ticket Rolls**: When a Lucky Ticket chaos mix succeeds, the server walks the Lucky Item table looking for the first entry whose section matches the requested armor category, whose Group matches the ticket's group, and whose item class requirement (from [Item](/docs/data/item/item.md)) accepts the player's class. The first candidate that matches wins, so list order in LuckyItem.xml determines which item drops when more than one entry could qualify.
{% endhint %}

{% hint style="warning" %}
**Version Requirement**: The Lucky Item system is gated on the 5.0.2 engine update. Earlier builds ignore the file.
{% endhint %}

{% hint style="warning" %}
**JoH Exclusion**: Lucky items (armor categories 7-11 with type between 62 and 72) are rejected by Jewel of Harmony. Use Jewel of Elevation ([JewelOfHarmonyOption](/docs/data/item/jewelofharmonyoption.md)) to raise their JoH-option level instead.
{% 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 rows in [ItemOptionRate](/docs/data/item/itemoptionrate.md).
{% endhint %}

{% hint style="danger" %}
**Durability Tracking**: The fractional decay counter is stored alongside main durability on each Lucky Item and is persisted to the DataServer at save time and on logout, so decay progress survives restarts and map changes.
{% endhint %}

{% hint style="warning" %}
**Equipped Items Only**: Decay only ticks for Lucky Items worn in the five armor slots (Helm, Armor, Pants, Gloves, Boots). Lucky Items held in inventory or warehouse do not decay.
{% endhint %}

{% hint style="info" %}
**Refine Mix**: A Lucky Item placed alone in the Chaos Box can be refined. The success rate uses one set of values when the item is at full durability (255) and a different set when it is below 255, both keyed by the player's account level. A successful refine consumes the chaos money and triggers the configured success effect.
{% endhint %}

## Related

* [Item](/docs/data/item/item.md) - Base item definitions and class requirements
* [ItemOptionRate](/docs/data/item/itemoptionrate.md) - Rows referenced by Option0-6
* [ItemOption](/docs/data/item/itemoption.md) - Stat values applied for the rolled options
* [JewelOfHarmonyOption](/docs/data/item/jewelofharmonyoption.md) - Jewel of Elevation target table
* [JewelOfHarmonyType](/docs/data/item/jewelofharmonytype.md) - Item-level requirements for the JoH/Elevation system
* [ItemStack](/docs/data/item/itemstack.md) - Stack rules for related consumables (Lucky Tickets, Jewels)