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

# StackMaster

What StackMaster does, which servers it runs on, the files it creates and the words used on these pages.

**StackMaster** stacks mobs, dropped items and spawners. A stack of 500 zombies is **one** real zombie in the world that counts as 500. One nametag shows the size (`Zombie ×500`). Fewer entities means less lag, while drops, XP, breeding and egg laying still count every mob in the stack.

It runs on **Paper, Folia and Canvas**, Minecraft **1.21.11 to 26.3** (`api-version: 1.21.11`, `folia-supported: true`). Java 21 or newer, Java 25 on 26.x. Nothing else is required. Vault is optional and only used to charge for spawner upgrades.

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

* Install the jar, start once, put your key in `license.key` (see [Licensing](/origin-smp/getting-started/licensing.md)), restart.
* Mobs, items and spawners stack straight away with the defaults.
* See what is stacked: `/stackmaster stats` (alias `/sm`).
* Change a setting in `plugins/StackMaster/config.yml`, then `/sm reload`.
  {% endhint %}

## What it does

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3><i class="fa-cow" style="color:$primary;">:cow:</i></h3></td><td><strong>Mob stacking</strong></td><td>Merging, natural spawns, kills, drops, breeding, eggs, splitting.</td><td><a href="/origin-smp/stackmaster/entity-stacking.md">Mob stacking</a></td></tr><tr><td><h3><i class="fa-box" style="color:$primary;">:box:</i></h3></td><td><strong>Item stacking</strong></td><td>Dropped items merge into one entity. Pickup and hoppers work like vanilla.</td><td><a href="/origin-smp/stackmaster/item-stacking.md">Item stacking</a></td></tr><tr><td><h3><i class="fa-cube" style="color:$primary;">:cube:</i></h3></td><td><strong>Spawners</strong></td><td>One block holds many spawners. Spawner items, the spawner menu and upgrades.</td><td><a href="/origin-smp/stackmaster/spawners.md">Spawners</a></td></tr><tr><td><h3><i class="fa-tag" style="color:$primary;">:tag:</i></h3></td><td><strong>Display</strong></td><td>Nametags, item labels, spawner holograms and colours.</td><td><a href="/origin-smp/stackmaster/display.md">Display</a></td></tr><tr><td><h3><i class="fa-terminal" style="color:$primary;">:terminal:</i></h3></td><td><strong>Commands and permissions</strong></td><td>Every <code>/stackmaster</code> subcommand and permission node.</td><td><a href="/origin-smp/stackmaster/commands-permissions.md">Commands and permissions</a></td></tr><tr><td><h3><i class="fa-gear" style="color:$primary;">:gear:</i></h3></td><td><strong>config.yml</strong></td><td>Every section of the config, in order.</td><td><a href="/origin-smp/stackmaster/config-yml.md">config.yml reference</a></td></tr><tr><td><h3><i class="fa-database" style="color:$primary;">:database:</i></h3></td><td><strong>Storage</strong></td><td>SQLite, MySQL, YAML or JSON, and what is saved where.</td><td><a href="/origin-smp/stackmaster/storage-and-sync.md">Storage</a></td></tr><tr><td><h3><i class="fa-puzzle-piece" style="color:$primary;">:puzzle-piece:</i></h3></td><td><strong>Compatibility</strong></td><td>Paper, Folia, Canvas, custom item and mob plugins, kill counters.</td><td><a href="/origin-smp/stackmaster/compatibility.md">Compatibility</a></td></tr><tr><td><h3><i class="fa-book-open-check" style="color:$primary;">:book-open-check:</i></h3></td><td><strong>How-to</strong></td><td>Recipes for common changes.</td><td><a href="/origin-smp/stackmaster/how-to.md">How-to</a></td></tr></tbody></table>

## The three systems

| System   | Config section      | What stacks                                           | Page                                                       |
| -------- | ------------------- | ----------------------------------------------------- | ---------------------------------------------------------- |
| Mobs     | `stacking-entities` | Living entities of the same type that match the rules | [Mob stacking](/origin-smp/stackmaster/entity-stacking.md) |
| Items    | `stacking-items`    | Dropped items with the same item data                 | [Item stacking](/origin-smp/stackmaster/item-stacking.md)  |
| Spawners | `stacking-spawners` | Spawner blocks of the same mob                        | [Spawners](/origin-smp/stackmaster/spawners.md)            |

Each system can be switched off on its own, per world, and (for mobs) per mob type. `general.disabled-worlds` turns all three off in a world. See [config.yml](/origin-smp/stackmaster/config-yml.md).

## Files it creates

```
plugins/StackMaster/
  config.yml
  data.db          (spawner stacks, with the default sqlite storage)
  License/         (created by the licence check)
```

With `storage.type: yaml` or `json` the spawner stacks are saved under `stacks/<world>/` instead of `data.db`. With MySQL they go to the table `stackmaster_stacks`. Mob and item stack sizes are not in these files: they are saved on the entity itself. See [Storage](/origin-smp/stackmaster/storage-and-sync.md).

On the first start Paper downloads the SQLite driver, the MySQL driver and Gson into the server's `libraries/` folder. The server needs internet for that start.

## Terms

| Term                    | Meaning                                                                                                                            |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Stack**               | A group of mobs, items or spawners that counts as one.                                                                             |
| **Size** (logical size) | How many mobs, items or spawners the stack counts as.                                                                              |
| **Representative**      | The one real mob or item entity in the world that carries the stack.                                                               |
| **Logical kill**        | A mob removed from a stack by a lethal hit. The hit is cancelled, the stack shrinks, loot and XP drop. No real mob dies.           |
| **Natural spawn**       | A mob that spawned on its own in the world (random spawning, chunk generation, patrols, raids ...). These do not stack by default. |
| **Spawner stack**       | One spawner block that counts as many spawners.                                                                                    |
| **Owner**               | The player who placed a spawner. Only the owner (or staff) can break, add to, change or upgrade it.                                |
| **Forced spawning**     | StackMaster runs the spawner itself and ignores light and space rules. The default for stacked spawners.                           |

## Developer API

Other plugins can read stack sizes through the StackMaster API. See [StackMaster API](/origin-smp/dev-api/stackmaster-api.md).