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

# Spawners

Spawner stacks (one block that counts as many spawners), spawner items, breaking and adding, spawning, the spawner menu and upgrades.

A **spawner stack** is one spawner block that counts as many spawners. Adding spawners never leaves extra blocks behind: they all go into one block, and one hologram shows the size (`Zombie Spawner ×10`). The stack spawns for its whole size.

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

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

* Biggest stack: `stacking-spawners.max-stack-size` (default `64`).
* Give a player spawners: `/sm give <player> <mob> spawner [amount]`.
* Need Silk Touch to mine spawners: `dropping.require-silk-touch: true`.
* Change upgrade prices: `upgrades.<upgrade>.cost-per-level`.
* Players open the menu with **sneak + right-click** on the spawner.
  {% endhint %}

## What a player sees

| Action                                                     | Result                                                                                                                                                                            |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Place a spawner                                            | Starts a new stack, owned by the player. If one of **their** stacks of the same mob is within 5 blocks and has room, the spawner joins that stack instead and no block is placed. |
| Sneak while placing                                        | Always starts a new, separate stack.                                                                                                                                              |
| Right-click a stack holding a spawner item of the same mob | Adds one item to the stack. Sneak to add the whole hand.                                                                                                                          |
| Right-click with an empty hand                             | Action bar: mob, size and time to the next spawn.                                                                                                                                 |
| Sneak + right-click                                        | Opens the [spawner menu](#the-spawner-menu).                                                                                                                                      |
| Break                                                      | Takes the **whole stack**. You get it back as spawner items (`Zombie Spawner x10`).                                                                                               |
| Sneak + break                                              | Takes **one** spawner off. The block stays with the rest.                                                                                                                         |
| Spawn egg on a stack                                       | Blocked (it would change every spawner in the stack for one egg). Single spawners can still be changed.                                                                           |

Messages for adding, removing, a full stack and a blocked egg appear in the action bar.

## Size and merging

| Key                        | Default | What it does                                                                                                                         |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled`                  | `true`  | Spawner stacking on or off.                                                                                                          |
| `max-stack-size`           | `64`    | Most spawners in one stack. Never above `general.global-max-stack-size` (`10000`).                                                   |
| `merge-radius`             | `5.0`   | A placed spawner joins the nearest stack of the same mob within this many blocks. `0`: spawners only join by right-clicking a stack. |
| `merging.enabled`          | `true`  | `false`: placed spawners never join a stack, and right-click adding is off.                                                          |
| `location.same-chunk-only` | `false` | A placed spawner only joins stacks in the same chunk.                                                                                |

A placed spawner only joins a stack that is the **same mob**, has room for the whole item (`size + item size <= max-stack-size`), is in a loaded chunk, and that the player is allowed to manage (see [Owners](#owners)). Otherwise it is placed as its own stack.

When a stack is full, right-click adding shows `This stack is full`. If only part of a stacked item fits, the rest comes back as a new item.

{% hint style="info" %}
**Origin SMP:** `max-stack-size` is `328`.
{% endhint %}

## Owners

The player who places a spawner becomes its **owner**. With `upgrades.owner-protection: true` (the default) only the owner can break it, add to it, use a spawn egg on it, change its settings in the menu, upgrade it or take spawners off with `/sm unstack`. Others can look at the menu.

Staff with `stackmaster.upgrade.admin` can manage every spawner. A spawner without an owner (world-generated, or placed while owner protection was off) can be managed by anyone.

The owner is not stored on the spawner item. Whoever places the item next owns the new stack.

## Breaking and spawner items

Section `interaction` and `dropping`.

| Key                                     | Default | What it does                                                                                                                 |
| --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `interaction.enabled`                   | `true`  | The interaction features below on or off.                                                                                    |
| `interaction.default-mode`              | `stack` | What a normal break takes: `stack` the whole stack, `single` one spawner.                                                    |
| `interaction.sneak-break-one`           | `true`  | Sneaking does the opposite of `default-mode`.                                                                                |
| `interaction.right-click-info`          | `true`  | Empty-hand right-click shows the action bar info.                                                                            |
| `interaction.sneak-right-click-menu`    | `true`  | Sneak + right-click opens the menu.                                                                                          |
| `interaction.add-with-right-click`      | `true`  | Right-click a stack with spawner items to add them.                                                                          |
| `interaction.sneak-place-separate`      | `true`  | Sneak while placing to start a separate stack.                                                                               |
| `interaction.allow-spawn-egg-on-stacks` | `false` | Let a spawn egg change the mob of a stack bigger than one.                                                                   |
| `dropping.enabled`                      | `true`  | Breaking gives spawner items.                                                                                                |
| `dropping.drop-single-stack-item`       | `true`  | One item holds many spawners (`Zombie Spawner x10`). `false`: one item per spawner.                                          |
| `dropping.store-stack-size-in-item`     | `true`  | Needed for the single item above.                                                                                            |
| `dropping.max-item-stack-size`          | `64`    | Most spawners in one dropped item. A bigger stack drops several items.                                                       |
| `dropping.preserve-data`                | `true`  | Keep upgrades, spawn mode and custom delays on the item when the whole stack is picked up.                                   |
| `dropping.require-silk-touch`           | `false` | Only a Silk Touch tool picks spawners up. Without one the break is **cancelled**, so a stack is never destroyed by accident. |
| `dropping.to-inventory`                 | `false` | Put picked-up spawners straight into the inventory. What does not fit drops.                                                 |
| `dropping.natural-spawners-drop`        | `false` | Let world-generated spawners drop as items too.                                                                              |

Creative players break spawners without getting items.

The break is decided at `HIGHEST` priority and applied at `MONITOR`. A protection plugin that cancels the break (a claim, a region) wins, and the player gets nothing.

### World-generated spawners

Dungeon and other world-generated spawners are vanilla until someone interacts with them:

* Breaking one gives nothing (vanilla), unless `natural-spawners-drop: true`.
* Right-clicking one with spawner items of the same mob turns it into a stack. Its own block is marked natural and still never drops; only the spawners added to it come back when it is broken.
* Changing its settings in the menu also turns it into a tracked stack.

### Explosions

| Key                      | Default | What it does                                                                                                                                                                                    |
| ------------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `explosions.mode`        | `one`   | `protect`: stacks are immune. `one`: an explosion destroys one spawner of the stack, the block stays. `all`: the whole stack is destroyed. A stack of one is always destroyed unless `protect`. |
| `explosions.drop-chance` | `0.0`   | Chance (0.0 to 1.0) that each destroyed spawner drops as an item. At `0.0` destroyed spawners are lost.                                                                                         |

### Spawner item look

Section `item`. The same look is used in every world.

| Key                        | Default                                                      |
| -------------------------- | ------------------------------------------------------------ |
| `item.name`                | `&e{entity} Spawner`                                         |
| `item.name-stacked`        | `&e{entity} Spawner &7x&f{size}` (items worth more than one) |
| `item.lore`                | Mob, stack size, `{upgrades}`, and two hint lines            |
| `item.upgrade-line`        | `&7{name}: &b{level}&7/&b{max}`                              |
| `item.glint-when-upgraded` | `true`                                                       |

Placeholders: `{entity}`, `{size}`. A lore line containing `{upgrades}` turns into one `upgrade-line` per upgrade that has a level, and disappears when there are none. `upgrade-line` has `{name}`, `{level}`, `{max}`.

The item stores its mob type and size in its own data. A spawner item can be placed by any player, also without operator rights, and it still spawns the right mob.

{% hint style="info" %}
**Origin SMP** uses its own item look: a gold `&#E5B95F{entity} Spawner` name and a lore with a `ꜱᴘᴀᴡɴᴇʀ` tag line, a short how-to and a Stats block.
{% endhint %}

## Spawning

Section `spawning` and `activation`. A stacked spawner spawns for every spawner in it. There are two modes.

{% tabs %}
{% tab title="Always spawn (default)" %}
With `spawning.spawn-no-matter-the-spawn-conditions: true` StackMaster runs the spawner itself:

* Its own timer waits a random time between the spawner's minimum and maximum delay.
* When a player (not in spectator) is within the spawner's required player range, it spawns. Light level and the blocks around do **not** matter. Mobs never spawn inside solid blocks or lava.
* Vanilla's own spawns from that block are cancelled, so nothing doubles.
* A few flame particles show each spawn.
  {% endtab %}

{% tab title="Vanilla rules" %}
With `spawn-no-matter-the-spawn-conditions: false` vanilla decides when and where to spawn, with its light and space rules. Each mob vanilla spawns brings extra copies at the same spot, so a stack of 10 spawns about 10 times as many mobs.
{% endtab %}
{% endtabs %}

Each spawner can choose its own mode in the [menu](#the-spawner-menu): **Server Default**, **Always Spawn** or **Vanilla Rules**.

### How many mobs

| Key                                             | Default             | What it does                                                                                                                                                          |
| ----------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spawning.enabled`                              | `true`              | Stack-aware spawning on or off.                                                                                                                                       |
| `spawning.spawn-count-mode`                     | `capped-multiplied` | `single`: like one spawner. `multiplied`: spawn count × stack size. `capped-multiplied`: multiplied, at most `max-spawns-per-cycle`.                                  |
| `spawning.multiplier-per-spawner`               | `1.0`               | Rate per spawner in the stack. `0.5` = half.                                                                                                                          |
| `spawning.max-spawns-per-cycle`                 | `32`                | Most mobs one stack spawns at once in `capped-multiplied` mode.                                                                                                       |
| `spawning.delay-mode`                           | `shared`            | `shared`: one timer for the stack. `scaled`: the wait is divided by the stack size, at most by `delay-scaling-cap`. `individual` is accepted and works like `shared`. |
| `spawning.delay-scaling-cap`                    | `10.0`              | `scaled` only: at most this many times faster.                                                                                                                        |
| `spawning.respect-max-nearby-entities`          | `true`              | Respect the spawner's own "max nearby entities" limit.                                                                                                                |
| `spawning.stack-aware-nearby-limit`             | `true`              | Multiply that limit by the stack size.                                                                                                                                |
| `spawning.hard-mob-cap-per-spawner-stack`       | `100`               | Never more than this many mobs of the spawner's type around it (plus the Chunk Limit upgrade).                                                                        |
| `spawning.spawn-no-matter-the-spawn-conditions` | `true`              | The server default spawn mode, see the tabs above.                                                                                                                    |
| `activation.enabled`                            | `true`              | `false`: spawners spawn without a player nearby.                                                                                                                      |
| `activation.respect-required-player-range`      | `true`              | A player must be within the spawner's required player range.                                                                                                          |

Example: 20 spawners with a spawn count of 4 would be 80 mobs. `capped-multiplied` stops at 32, plus any Spawn Count upgrade, and never above the caps.

**Mob caps.** Mobs of the spawner's type within its spawn range + 4 blocks are counted, and a stacked mob counts as its full size. The stack spawns no more than `hard-mob-cap-per-spawner-stack` minus that count, and no more than the spawner's max nearby entities × stack size minus that count.

Spawned mobs have the spawn reason `SPAWNER`. They stack with each other through [mob stacking](/origin-smp/stackmaster/entity-stacking.md).

`activation.closest-player-only` and `activation.max-activating-players` are in the file but have no effect.

## The spawner menu

Sneak + right-click a spawner (permission `stackmaster.spawner.gui`, everyone by default). Anyone can look. Only the [owner](#owners) or staff can change things.

| Screen             | Shows                                                                                                                   |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **Overview**       | Mob, size, owner, spawn mode, delay, next spawn, mobs per spawn. Buttons to Spawn Settings and Upgrades.                |
| **Spawn Settings** | The three spawn modes, the minimum and maximum delay editor, a next-spawn readout and Reset Delays.                     |
| **Upgrades**       | One button per enabled upgrade with level bar, current and next effect, and cost. Your balance when Vault is installed. |

### Spawn delay editor

Changing the delay needs `stackmaster.spawner.delay.edit` (operators by default). Without it the delays are shown with "Spawn delays can only be changed by staff".

* `-` and `+` buttons per step. Default steps `1`, `20` and `100` ticks (20 ticks = 1 second).
* Click the value to type an exact number in chat: ticks (`300`) or seconds (`15s`). Type `cancel` to go back. The prompt waits 30 seconds.
* Allowed range: `delay-editor.lowest` to `delay-editor.highest` (200 to 2400 ticks). With `stackmaster.spawner.delay.bypass`: 1 to 72000.
* **Reset Delays** sets the vanilla 200 to 800 ticks.
* The new delay starts at once. The Speed upgrade still applies on top.

### Menu settings

Section `gui`.

| Key                                               | Default                                                                             | What it does                                 |
| ------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------- |
| `gui.enabled`                                     | `true`                                                                              | The menu on or off.                          |
| `gui.sounds`                                      | `true`                                                                              | Click and upgrade sounds.                    |
| `gui.border`                                      | `BLACK_STAINED_GLASS_PANE`                                                          | Pane around the edge. `AIR` leaves it empty. |
| `gui.filler`                                      | `GRAY_STAINED_GLASS_PANE`                                                           | Pane in empty slots. `AIR` leaves it empty.  |
| `gui.titles.main`, `.settings`, `.upgrades`       | `&8{entity} Spawner &7×{size}`, `&8Spawn Settings`, `&8Upgrades · {entity} Spawner` | Menu titles.                                 |
| `gui.delay-editor.steps`                          | `[1, 20, 100]`                                                                      | Up to three step sizes in ticks.             |
| `gui.delay-editor.lowest`                         | `200`                                                                               | Lowest delay players may choose.             |
| `gui.delay-editor.highest`                        | `2400`                                                                              | Highest delay players may choose.            |
| `gui.upgrades.lore`                               | see config                                                                          | Lore of every upgrade button.                |
| `gui.upgrades.<upgrade>.material`, `.description` | see config                                                                          | Icon and description per upgrade.            |

Every button can be restyled with `material`, `name` and `lore` under its key: `main.info`, `main.settings`, `main.upgrades`, `settings.mode-default`, `settings.mode-always`, `settings.mode-vanilla`, `settings.min-delay`, `settings.max-delay`, `settings.increase`, `settings.decrease`, `settings.next-spawn`, `settings.reset`, `upgrades.<upgrade>`, `upgrades.balance`, `buttons.back`, `buttons.close`. Missing keys use the built-in look.

Placeholders: `{entity}` `{size}` `{max_size}` `{owner}` `{mode}` `{min}` `{max}` `{min_s}` `{max_s}` (delay with upgrades, ticks and seconds), `{base_min}` `{base_max}` (delay before the Speed upgrade), `{next}` `{per_spawn}` `{upgraded}` `{upgrade_count}`. Upgrade buttons add `{name}` `{description}` `{level}` `{max_level}` `{bar}` `{current}` `{next}` `{cost}` `{cost_line}` `{action}`. Colours: `&a` codes and `&#RRGGBB`.

## Upgrades

Section `upgrades`. Upgrade levels belong to the stack (its block) and survive restarts. Buy them in the menu, or while looking at the spawner with `/sm upgrade <name>` and `/sm upgrades`.

| Upgrade            | Effect per level                                                          | Max level | Cost per level | On by default |
| ------------------ | ------------------------------------------------------------------------- | --------- | -------------- | ------------- |
| `speed`            | `delay-reduction-percent-per-level: 10.0`: min and max delay 10% shorter  | 10        | 1000           | yes           |
| `spawn-count`      | `bonus-spawns-per-level: 1`: one more mob per spawn                       | 5         | 2000           | yes           |
| `chunk-limit`      | `bonus-cap-per-level: 10`: the hard mob cap +10                           | 10        | 1500           | yes           |
| `activation-range` | `bonus-blocks-per-level: 2`: required player range +2 blocks              | 5         | 800            | yes           |
| `xp`               | `xp-percent-per-level: 10.0`: mobs from this spawner give 10% more XP     | 10        | 1200           | yes           |
| `drops`            | `drop-percent-per-level: 20.0`: mobs from this spawner drop 20% more loot | 5         | 3000           | **no**        |

Each upgrade has `enabled`, `max-level`, `cost-per-level` and its effect key.

**Price.** Level N costs `cost-per-level × N`. With the default Speed price, level 1 costs 1000, level 2 costs 2000, and all ten levels cost 55,000. Money is taken through **Vault**. With every `cost-per-level` at `0`, upgrades are free and Vault is not needed. Staff with `stackmaster.upgrade.admin` set any level for free.

At Speed level 10 with 10% per level the delay drops to 1 tick. Mob caps still limit how many mobs exist.

The XP and Drops boosts are stored on each mob the spawner spawns. They are paid when that mob is killed out of a stack.

### Module switches

| Key                          | Default | What it does                                                                                       |
| ---------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `upgrades.enabled`           | `true`  | The whole upgrade module. Owner protection also depends on it.                                     |
| `upgrades.transfer-on-break` | `true`  | Breaking the whole stack moves its levels onto the first dropped item.                             |
| `upgrades.transfer-on-split` | `true`  | Kept for older configs. Single spawners taken off a stack are always plain.                        |
| `upgrades.owner-protection`  | `true`  | Only the owner (or `stackmaster.upgrade.admin`) can break, add to, configure or upgrade a spawner. |

### Upgrades can never be copied

* One stack has one set of levels, paid once.
* Adding an upgraded spawner item to a stack keeps the **higher** level of each upgrade.
* Taking single spawners off (sneak-break, `/sm unstack`) gives **plain** items. The levels stay on the block.
* Breaking the **whole** stack puts the levels, spawn mode and custom delays on the **first** item only.

## Other keys in this section

These keys are in the file but have no effect in the current version: `storage.*` (the `simple` / `snapshot` / `hybrid` modes, validation and recovery), `merging.representative`, `merging.preserve-custom-data`, `merging.reject-incompatible-spawners`, `compatibility.require-perfect-match`, `line-of-sight.*`, and the `location` keys other than `same-chunk-only`.

The other `compatibility` keys are only used by `/sm stack`, which merges spawner stacks of the same owner that stand within 16 blocks of the player.

## Stacks from older versions

Older versions kept one block per spawner. When such a stack loads, the extra blocks are removed and counted into the main block. The size does not change.