# ItemStack

This configuration file defines which items can be stacked in inventory and their maximum stack sizes, with optional item transformation when reaching max stack.

## File Location

```
GameServer/Data/Item/ItemStack.xml
```

## Dependencies

| Depends On | Purpose          |
| ---------- | ---------------- |
| Item.xml   | Item definitions |

| Depended On By | Purpose                                |
| -------------- | -------------------------------------- |
| ItemValue.xml  | Uses stack count for price calculation |

## How It Works

1. When items are picked up or received, server checks ItemStack
2. If item is stackable, multiple items combine into one slot
3. Stack count shown in inventory (up to MaxStack)
4. Optionally, when MaxStack is reached, item transforms to another

## Structure

### New Format (Recommended)

```xml
<Item Type="14" Index="13" Level="*" MaxStack="255"
      CreateType="*" CreateIndex="*" Name="Jewel of Bless"/>
```

### Old Format (Backward Compatible)

```xml
<Item Index="7181" MaxStack="255" CreateIndex="*"/>
```

## Attributes

| Attribute     | Type   | Description                                                  |
| ------------- | ------ | ------------------------------------------------------------ |
| `Type`        | int    | Item category (0-15) - New format only                       |
| `Index`       | int    | Item type within category, or calculated index in old format |
| `Level`       | string | `*` for all levels, or 0-15 for specific level               |
| `MaxStack`    | int    | Maximum stack size (1-255)                                   |
| `CreateType`  | string | `*` for no transform, or category of created item            |
| `CreateIndex` | int    | Index of created item (when MaxStack reached)                |
| `CreateLevel` | string | `*` for same level, or specific level for created item       |
| `Name`        | string | Human-readable name (optional)                               |

### Index Calculation (Old Format)

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

### Category Reference

| Category | Item Type                    |
| -------- | ---------------------------- |
| 0-5      | Weapons (cannot stack)       |
| 6        | Shields (cannot stack)       |
| 7-11     | Armor (cannot stack)         |
| 12       | Wings, Scrolls, Orbs         |
| 13       | Rings, Pendants, Quest Items |
| 14       | Potions, Jewels, Consumables |
| 15       | Scrolls, Books               |

## Examples

{% tabs %}
{% tab title="Simple Stackable" %}

```xml
<!-- Jewels stack to 255, no transformation -->
<Item Type="14" Index="13" Level="*" MaxStack="255"
      CreateType="*" CreateIndex="*" Name="Jewel of Bless"/>

<Item Type="14" Index="14" Level="*" MaxStack="255"
      CreateType="*" CreateIndex="*" Name="Jewel of Soul"/>
```

When CreateType="\*", items simply stack without transforming.
{% endtab %}

{% tab title="Level-Specific" %}

```xml
<!-- Box of Kundun - different levels are different items -->
<Item Type="14" Index="11" Level="0" MaxStack="20"
      CreateType="*" CreateIndex="*" Name="Box of Kundun +1"/>
<Item Type="14" Index="11" Level="1" MaxStack="20"
      CreateType="*" CreateIndex="*" Name="Box of Kundun +2"/>
<Item Type="14" Index="11" Level="2" MaxStack="20"
      CreateType="*" CreateIndex="*" Name="Box of Kundun +3"/>
```

Each level stacks separately.
{% endtab %}

{% tab title="With Transformation" %}

```xml
<!-- 5 Mithril Fragments → 1 Mithril -->
<Item Type="12" Index="48" Level="*" MaxStack="5"
      CreateType="12" CreateIndex="52" Name="Mithril Fragment"/>

<!-- 5 Symbol of Kundun → 1 Lost Map -->
<Item Type="14" Index="29" Level="*" MaxStack="5"
      CreateType="14" CreateIndex="28" Name="Symbol of Kundun"/>
```

When player obtains 5th fragment, stack converts to the target item.
{% endtab %}

{% tab title="No Transform" %}

```xml
<!-- Potions stack without transformation -->
<Item Type="14" Index="0" Level="*" MaxStack="255"
      CreateType="*" CreateIndex="*" Name="Apple"/>
<Item Type="14" Index="1" Level="*" MaxStack="255"
      CreateType="*" CreateIndex="*" Name="Small Healing Potion"/>
```

When CreateType="\*", items simply stack without converting to another item.
{% endtab %}

{% tab title="Non-Stackable (Special Case)" %}

```xml
<!-- Ammunition: Config entries exist but items do NOT stack -->
<Item Type="4" Index="7" Level="*" MaxStack="255" CreateType="*" CreateIndex="*" Name="Bolt" />
<Item Type="4" Index="15" Level="*" MaxStack="255" CreateType="*" CreateIndex="*" Name="Arrow" />
```

**WARNING**: Despite having MaxStack=255, Bolts and Arrows do NOT actually stack in inventory. Type 4 is in the hardcoded non-stackable range (0-11). These entries only affect shop price calculation logic. Do not expect these to combine into stacks.
{% endtab %}
{% endtabs %}

## Important Behavior

{% hint style="info" %}
**Equipment Cannot Stack**: Categories 0-11 (weapons, shields, armor) are hardcoded to never stack regardless of configuration. While Bolts (Type 4, Index 7) and Arrows (Type 4, Index 15) are defined in ItemStack.xml with MaxStack=255, they do NOT actually stack in inventory because Type 4 is in the non-stackable range. The config entries exist only for special shop price calculation logic.
{% endhint %}

{% hint style="info" %}
**Level Matching**: When Level is specified, only items of that exact level stack together. Level="\*" allows all levels to stack together.
{% endhint %}

{% hint style="info" %}
**Price Calculation**: ItemValue.xml multiplies Value by stack count for stackable items.
{% endhint %}

{% hint style="warning" %}
**Max Stack 255**: Stack count is stored as a single byte, limiting maximum to 255.
{% endhint %}

{% hint style="warning" %}
**Transformation Timing**: Item transforms when the MaxStack is reached, not when exceeding it.
{% endhint %}

## Common Issues

{% hint style="warning" %}
**Item Not Stacking**: Verify it's in category 12-15. Equipment categories (0-11) cannot stack regardless of configuration. Note that Bolts and Arrows (Type 4) are configured with MaxStack values but do NOT actually stack - these entries only affect shop pricing logic.
{% endhint %}

{% hint style="warning" %}
**Wrong Transformation**: Check CreateType/CreateIndex calculation. The created item must exist in Item.xml.
{% endhint %}

{% hint style="danger" %}
**Old vs New Format**: Don't mix formats in the same entry. Use either Type+Index (new) or single Index (old).
{% endhint %}
