> For the complete documentation index, see [llms.txt](https://lethium.gitbook.io/origin-smp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lethium.gitbook.io/origin-smp/stackmaster/item-stacking.md).

# Item stacking

How dropped items merge into one entity, when two items count as the same, and how pickup, hoppers and despawning work.

Dropped items of the same kind that lie close together merge into **one item entity**. A pile of 2048 cobblestone is one entity on the ground instead of 32. Players and hoppers still take it out one normal stack at a time.

Config section: `stacking-items` in `config.yml`.

{% hint style="success" %}
**Quick start**

* Most items in one pile: `stacking-items.max-stack-size` (default `2048`).
* Show the count above piles: `entity.display-stack-size: true`.
* Never merge an item: add it to `stacking-items.blacklist`.
* Reload: `/sm reload`.
  {% endhint %}

## What a player sees

* Drops within **4 blocks** of each other merge, four times a second.
* Walking over a pile picks up **one normal stack** (64, or 16 for ender pearls and so on). The rest stays on the ground and is picked up on the next pickup.
* Hoppers and hopper minecarts pull from a pile one stack at a time.
* Mobs that pick up items (zombies, allays, foxes ...) cannot pick up a merged pile. They would only take the visible part and the rest would be lost, so the pickup is blocked.
* Vanilla's own item merging is switched off wherever item stacking is on. StackMaster does all merging with its own, stricter rules.

## Main settings

| Key                    | Default                                                                      | What it does                                                                                            |
| ---------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `enabled`              | `true`                                                                       | Item stacking on or off.                                                                                |
| `max-stack-size`       | `2048`                                                                       | Most items in one pile (2048 = 32 stacks of 64). Never above `general.global-max-stack-size` (`10000`). |
| `merge-radius`         | `4.0`                                                                        | Distance in blocks two drops must be within to merge.                                                   |
| `merge-interval-ticks` | `5`                                                                          | How often items try to merge. 20 ticks = 1 second.                                                      |
| `whitelist-mode`       | `false`                                                                      | `false`: everything merges except the `blacklist`. `true`: only the `whitelist` merges.                 |
| `whitelist`            | `[]`                                                                         | Material names, used in whitelist mode.                                                                 |
| `blacklist`            | `BEDROCK`, `COMMAND_BLOCK`, `CHAIN_COMMAND_BLOCK`, `REPEATING_COMMAND_BLOCK` | Materials that never merge.                                                                             |

{% hint style="info" %}
**Origin SMP:** `max-stack-size` is set to `204800`, but `general.global-max-stack-size` stays `10000`, so piles stop at **10000** items.
{% endhint %}

## When two items count as the same

Section `compatibility`. Items are compared by their full **item data** (data components): enchantments, name, lore, custom model data, durability, potion, custom data from other plugins and so on.

| Key                       | Default | What it does                                                    |
| ------------------------- | ------- | --------------------------------------------------------------- |
| `same-material`           | `true`  | Same material.                                                  |
| `compare-data-components` | `true`  | The whole item data must be identical. This is the main switch. |
| `same-enchantments`       | `true`  | Same enchantments.                                              |
| `same-custom-model-data`  | `true`  | Same custom model data.                                         |
| `same-display-name`       | `true`  | Same custom name.                                               |
| `same-lore`               | `true`  | Same lore lines.                                                |
| `same-attributes`         | `true`  | Same attribute modifiers.                                       |
| `same-durability`         | `true`  | Same damage.                                                    |
| `same-potion-data`        | `true`  | Same potion type and effects.                                   |
| `same-item-flags`         | `true`  | Same item flags.                                                |
| `same-persistent-data`    | `true`  | Same plugin data (persistent data keys outside `minecraft:`).   |

{% hint style="warning" %}
`compare-data-components: true` already requires **everything** to match. Setting one of the other rules to `false` has no effect while it is on. To let, for example, items with different durability merge, set `compare-data-components: false` and `same-durability: false`.
{% endhint %}

Custom items from ItemsAdder, Nexo, Oraxen and similar plugins keep their identity in the item data, so identical custom items merge with each other, different custom items never merge, and a custom item never merges with a vanilla one.

## When items may merge

Section `merging`.

| Key                         | Default | What it does                                 |
| --------------------------- | ------- | -------------------------------------------- |
| `require-same-pickup-delay` | `false` | Only items with the same pickup delay merge. |
| `require-same-age`          | `false` | Only items of exactly the same age merge.    |
| `allow-in-water`            | `true`  | Items in water may merge.                    |
| `allow-burning`             | `false` | Burning items may merge.                     |
| `allow-fire`                | `false` | Items lying in a fire block may merge.       |
| `require-compatible-owner`  | `false` | No effect.                                   |

## Despawning

| Key                            | Default | What it does                                                                                                                              |
| ------------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `lifetime.preserve-oldest-age` | `true`  | A merged pile takes the age of its oldest item. Merging never makes items live longer: the pile despawns when its oldest item would have. |

Despawning itself is vanilla (5 minutes). `lifetime.vanilla-despawn`, `never-reset-age-on-merge` and `reset-age-on-recreate` are in the file but have no effect.

## Hoppers

Section `containers`.

| Key                          | Default | What it does                                                                                   |
| ---------------------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `enable-hopper-pickup`       | `true`  | Hoppers pull from piles. `false`: a hopper cannot pick up a pile bigger than one normal stack. |
| `enable-minecart-hoppers`    | `true`  | Hopper minecarts pull from piles. `false`: same block as above, for hopper minecarts.          |
| `max-transfer-per-operation` | `64`    | Most items a hopper takes from a pile at once.                                                 |
| `respect-vanilla-stack-size` | `true`  | Never take more than the item's normal stack size at once (16 for ender pearls).               |

`enable-hopper-output` and `enable-water-streams` are in the file but have no effect. Water streams move piles like any item.

## Label above a pile

| Key                         | Default     | What it does                             |
| --------------------------- | ----------- | ---------------------------------------- |
| `entity.display-stack-size` | `false`     | Show a label with the count above piles. |
| `entity.display-format`     | `&b×{size}` | Label text. `{size}` is the item count.  |

The label is only set on piles StackMaster merged. An item that already has a name from another plugin keeps it. See [Display](/origin-smp/stackmaster/display.md).

`entity.use-single-entity` and `entity.max-rendered-count` are in the file but have no effect.

## After a restart

The physical item never holds more than its normal stack size, because vanilla cannot save an item entity with more than 99 items. The real count is stored in the item entity's persistent data (`stackmaster:stack_size`) and survives restarts and chunk unloads. Nothing about item piles is written to the storage database.

## Per-world settings

Every key except `merge-interval-ticks` can be set for one world under `worlds.<world>.stacking-items`. The merge timer is shared by all worlds.

```yaml
worlds:
  world_the_end:
    stacking-items:
      enabled: false
```