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

# 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

```
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, purchased, or moved into inventory, the server checks ItemStack
2. If the item has a matching entry and another stack of the same Index, Level, and SocketOptionBonus already exists, units are merged into that stack
3. The stack count shown in inventory grows up to MaxStack
4. When the stack reaches exactly MaxStack and a CreateIndex is configured, the merged stack is consumed and a new item of the target type/level is generated in its place
5. Stacks can be split manually with the in-game stack-split action (ctrl + right click)

## 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    | Type-relative index 0-511 (new format), or fully calculated index Type\*512+TypeOffset (old format)                       |
| `Level`       | string | `*` for all levels, or a specific level 0-15. A specific-level entry takes priority over the `*` entry for the same Index |
| `MaxStack`    | int    | Maximum stack size. Hard cap is 255 because the runtime count is stored in one byte                                       |
| `CreateType`  | string | `*` for no transformation, or the category of the item created when the stack fills                                       |
| `CreateIndex` | int    | Type-relative index of the created item. Only used when CreateType is not `*`                                             |
| `CreateLevel` | string | `*` to copy the source stack's level, or a fixed 0-15 level for the created item                                          |
| `Name`        | string | Human-readable comment (optional, not parsed)                                                                             |

### Index Calculation (Old Format)

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

### Category Reference

| Category | Item Type                                                      | Stackable                              |
| -------- | -------------------------------------------------------------- | -------------------------------------- |
| 0-5      | Weapons (Swords, Axes, Maces, Spears, Bows/Crossbows, Staves)  | No, except Bolt (4,7) and Arrow (4,15) |
| 6        | Shields                                                        | No                                     |
| 7-11     | Armor (Helm, Armor, Pants, Gloves, Boots)                      | No                                     |
| 12       | Wings, Jewel of Chaos, Orbs, Scrolls, Fragments                | Yes (per-entry)                        |
| 13       | Rings, Pendants, Quest Items, Map Fragments                    | Yes (per-entry)                        |
| 14       | Potions, Jewels (Bless/Soul/Life/Creation), Boxes, Event Items | Yes (per-entry)                        |
| 15       | Pentagram items, Errtels, Socket Seeds                         | Yes (per-entry)                        |

## 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 the player picks up or merges the 5th fragment, the stack is consumed and a single new Mithril (or Lost Map) item is produced.
{% 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="Ammunition" %}

```xml
<!-- Bolts and Arrows: explicitly exempt from the equipment non-stack rule -->
<Item Type="4" Index="7" Level="*" MaxStack="255" CreateType="*" CreateIndex="*" Name="Bolt" />
<Item Type="4" Index="15" Level="*" MaxStack="255" CreateType="*" CreateIndex="*" Name="Arrow" />
```

The engine exempts Bolts (Type 4 Index 7) and Arrows (Type 4 Index 15) from the category 0-11 equipment non-stack rule. These DO stack up to 255 in inventory.
{% endtab %}
{% endtabs %}

## Important Behavior

{% hint style="info" %}
**Equipment Cannot Stack**: Categories 0-11 (weapons, shields, armor) are hardcoded to never stack regardless of configuration. The only exceptions are Bolts (Type 4, Index 7) and Arrows (Type 4, Index 15), which the engine explicitly allows to stack up to 255.
{% endhint %}

{% hint style="info" %}
**Level Matching**: A specific-level entry is used first; if none matches, the engine falls back to the Level="\*" entry for the same Index. Items with different levels still occupy separate stacks at runtime even when both use a `*` entry, because runtime merging requires Index, Level, and SocketOptionBonus to all match.
{% endhint %}

{% hint style="info" %}
**Merge Key**: Two stacks merge only when their Index, Level, and SocketOptionBonus are all identical. Different bonus seeds keep stacks separate even for the same item.
{% endhint %}

{% hint style="info" %}
**Price Calculation**: [ItemValue](/docs/data/item/itemvalue.md) multiplies the base Value by the current stack count when the item is sold.
{% endhint %}

{% hint style="warning" %}
**Max Stack 255**: Stack count is stored as a single byte, so values above 255 are invalid.
{% endhint %}

{% hint style="warning" %}
**Transformation Timing**: Transformation fires the moment the merged stack equals MaxStack and CreateType is set. The merged stack is deleted client-side and the new item is created via the DataServer item-create flow, so the resulting item appears in the next inventory update rather than instantly in the same slot.
{% endhint %}

{% hint style="info" %}
**Created Item Level**: When CreateLevel is `*` the new item inherits the source stack's Level. When CreateLevel is a number, the new item is forced to that level regardless of the source.
{% endhint %}

## Common Issues

{% hint style="warning" %}
**Item Not Stacking**: Verify it is in category 12-15 (or the Bolt/Arrow exceptions at Type 4 Index 7/15). Equipment categories 0-11 cannot stack regardless of configuration.
{% 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 %}

## Related

* [Item](/docs/data/item/item.md) - Base item definitions referenced by Index
* [ItemValue](/docs/data/item/itemvalue.md) - Per-unit price multiplied by stack count when selling
* [ItemDrop](/docs/data/item/itemdrop.md) - Drop tables that produce stackable items
* [LuckyItem](/docs/data/item/luckyitem.md) - Lucky armor (non-stackable) and the Lucky Ticket flow