> 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/entity-stacking.md). # Mob stacking How mobs merge into stacks, which mobs stay single, what happens on a kill, and how breeding, eggs and transformations count the whole stack. Mobs of the same type that stand close together merge into one **stack**. One real mob stays in the world and carries the size. A nametag such as `Zombie ×36` shows it. Config section: `stacking-entities` in `config.yml`. Display settings are on [Display](/origin-smp/stackmaster/display.md). {% hint style="success" %} **Quick start** * Biggest stack: `stacking-entities.max-stack-size` (default `100`). * Stop one mob type stacking: add it to `stacking-entities.blacklist`. * Mobs that spawn on their own do not stack. Change it with `natural-spawns.stack`. * More mobs per hit: `behavior.damage.max-kills-per-hit` and `kill-scaling`. * Reload: `/sm reload`. {% endhint %} ## What a player sees * Mobs of one type that gather within **8 blocks** of each other merge, every half second. * The stack has one nametag with the mob name and the size. * A hit that would kill the mob in front does **not** kill it. The stack loses one mob (or more, see [Killing a stack](#killing-a-stack)), loot and XP drop, and the next mob takes over at full health. * The last mob of a stack dies like a normal mob. * Sneak + right-click a stack to pull mobs out of it. ## How mobs merge Every `general.merge-interval-ticks` (default `10`, half a second) each tracked mob looks for others of the **same type** nearby. Two mobs merge when **all** of these hold: 1. Both are allowed to stack: the type is enabled and not blacklisted, and neither mob is marked as a natural spawn. 2. They are within `merge-radius` blocks. 3. The location rules pass (same world, chunk and region rules, see below). 4. Line of sight, when it is required. 5. The matching rules pass (names, variants, age, effects ...). 6. The stack has room: it never grows past `max-stack-size`. A mob that just came out of a split cannot merge again for **5 seconds**. | Key | Default | What it does | | -------------------- | ------- | ------------------------------------------------------------------------------------ | | `enabled` | `true` | Mob stacking on or off. | | `max-stack-size` | `100` | Most mobs one stack can hold. Never above `general.global-max-stack-size` (`10000`). | | `merge-radius` | `8.0` | Distance in blocks two mobs must be within to merge. | | `minimum-separation` | `0.0` | Two stacks closer than this do not merge with each other. `0` turns the check off. | {% hint style="info" %} **Origin SMP:** `max-stack-size` is `10000`. The per-mob overrides from the default file still apply: zombies stop at 200, skeletons at 150, creepers at 50, and iron golems do not stack. {% endhint %} ## Which mobs can stack | Key | Default | What it does | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | `whitelist-mode` | `false` | `false`: every type stacks except the `blacklist`. `true`: only the `whitelist` stacks. | | `whitelist` | `[]` | Entity type names, used in whitelist mode. | | `blacklist` | `PLAYER`, `ARMOR_STAND`, `ITEM_FRAME`, `GLOW_ITEM_FRAME`, `VILLAGER`, `WANDERING_TRADER`, `ENDER_DRAGON`, `WITHER`, `ELDER_GUARDIAN` | Types that never stack. | Use the names from Paper's `EntityType` list in capitals (`ZOMBIE`, `CAVE_SPIDER`). You can also turn one type off with `entities..enabled: false`, see [Overrides](#per-mob-and-per-world-overrides). ## Natural spawns Mobs that spawn **on their own** in the world stay normal single mobs. Mobs from spawners, breeding, eggs, commands, other plugins and splits stack as usual. ```yaml stacking-entities: natural-spawns: stack: false reasons: - NATURAL - CHUNK_GEN - PATROL - RAID - VILLAGE_INVASION - REINFORCEMENTS - TRAP - JOCKEY - MOUNT - NETHER_PORTAL ``` | Key | Default | What it does | | ------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `natural-spawns.stack` | `false` | `false`: mobs that spawn with one of the `reasons` never stack. `true`: they stack like any other mob. | | `natural-spawns.reasons` | the list above | Spawn reasons that count as "spawned on its own". These are Bukkit `CreatureSpawnEvent.SpawnReason` names. An unknown name is skipped. | How it works: when such a mob spawns, StackMaster marks it with `stackmaster:no_stack` in its persistent data. A marked mob is never indexed and never merges, neither as the front mob nor as a member. The mark stays on the mob through restarts and chunk unloads. `stack` can be set per world and per mob type. `reasons` is one global list. ```yaml worlds: world_nether: stacking-entities: natural-spawns: stack: true stacking-entities: entities: ZOMBIE: natural-spawns: stack: true ``` {% hint style="warning" %} The mark is set when the mob spawns. Mobs that spawned while `stack` was `false` keep their mark and stay single after you switch it to `true`. Only mobs that spawn afterwards stack. {% endhint %} ## Baby zombies Babies and adults never share a stack. So by default a **baby zombie** grows up the moment it spawns and joins the adult stack. This covers every zombie kind: zombies, husks, drowned, zombie villagers and zombified piglins. | Key | Default | What it does | | ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- | | `grow-baby-zombies` | `true` | Turn baby zombies into adults when they spawn. `false` keeps them small; they then only stack with other babies. | This key is not in the shipped `config.yml`. Add it under `stacking-entities:` to change it. It can be set per world and per mob type, like `natural-spawns.stack`. Baby zombies that count as a natural spawn (see above) are left alone. ## When two mobs count as the same Section `compatibility`. A rule set to `true` must match before two mobs merge. | Key | Default | What it does | | -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------- | | `require-same-custom-name` | `false` | Custom names must match. | | `require-same-variant` | `true` | Variant must match: cat type, sheep colour, axolotl, frog, parrot and llama variant, horse colour and markings. | | `require-same-age` | `true` | Babies only with babies, adults only with adults. | | `require-same-effects` | `true` | Same active potion effects and levels. | | `require-same-equipment` | `false` | Same armour and held items. | | `require-same-health` | `false` | Exactly the same health. | | `require-same-persistence` | `true` | Persistent mobs (for example name-tagged) only with persistent mobs. | | `block-passengers` | `true` | Mobs with a passenger never stack. | | `block-vehicles` | `true` | Mobs riding something never stack. | {% hint style="info" %} **Names always protect a mob.** Whatever the rules say, a mob with a custom name only merges with a mob of the same type and the **exact same name**. A named mob never merges with an unnamed one. This keeps name-tagged pets and custom mobs from other plugins out of plain stacks. The stack's own `Zombie ×10` nametag does not count as a name. {% endhint %} ### Merge conditions Section `conditions`. | Key | Default | What it does | | ---------------------- | ------- | -------------------------------------------------------------------- | | `same-owner` | `true` | Tamed mobs must have the same owner. | | `same-tamed-state` | `true` | Tamed and wild animals never stack together. | | `same-team` | `false` | Mobs on different scoreboard teams never stack. | | `allow-targeting-mobs` | `true` | Mobs that are chasing someone may merge. | | `allow-damaged-mobs` | `false` | Mobs that were just hurt (still in their damage cooldown) may merge. | | `allow-burning-mobs` | `false` | Burning mobs may merge. | | `allow-frozen-mobs` | `false` | Mobs frozen in powder snow may merge. | | `allow-fluid-mobs` | `true` | Mobs standing in water or lava may merge. | | `allow-leashed-mobs` | `false` | Leashed mobs may merge. | | `allow-named-mobs` | `true` | `false` stops every mob with a custom name from stacking. | ### Location and line of sight | Key | Default | What it does | | -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- | | `location.same-world-only` | `true` | Only mobs in the same world merge. | | `location.same-chunk-only` | `false` | Only mobs in the same chunk merge. | | `location.allow-cross-chunk-merging` | `true` | `false` stops merges across chunk borders. | | `location.same-region-only` | `true` | Only mobs on the same Folia/Canvas region merge. On Paper the whole server is one region, so this never blocks a merge. | | `location.allow-cross-region-merging` | `false` | Allow merges across Folia/Canvas region borders. Keep `false`. | | `location.respect-simulation-distance` | `true` | Skip mobs in chunks whose entities are not loaded. | | `line-of-sight.require` | `false` | Mobs must see each other to merge (stops merges through walls). | | `line-of-sight.max-distance` | `16.0` | With line of sight on, mobs further apart than this do not merge. | ## Killing a stack Section `behavior.damage`. This is what makes a stack feel like many mobs. When a hit (from anything: a player, an arrow, fall damage, fire, lava, a cactus, suffocation) would kill the mob in front: 1. The hit is **cancelled**. The mob plays no hurt or death animation and has no invulnerability frames, so the next hit lands at once. 2. The mob is healed to full health. It is now "the next mob in line". 3. The stack loses a number of mobs: the **kills per hit**. The death sound and a puff of smoke play. 4. Loot and XP for those mobs drop (see [Drops and XP](#drops-and-xp)). A hit never removes the last mob this way. When the stack is down to one, that mob dies normally. **Kills per hit** = `max-kills-per-hit` + (level of `kill-scaling.enchantment` on the attacker's main-hand item × `kills-per-level`), at most `kill-scaling.max-kills`. For arrows the shooter's main-hand item counts. Example with the defaults: Sweeping Edge III gives 1 + 3 × 2 = **7** mobs per hit. `/kill`, the void, the world border and the suicide damage cause skip all of this. They kill the front mob at once, and the rest of the stack goes with it. | Key | Default | What it does | | ------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `damage.enabled` | `true` | Stack-aware damage on or off. | | `damage.distribution` | `one_entity` | `one_entity`: the behaviour above. `proportional`: each hit's damage is divided by the stack size, and the whole stack dies with the front mob. `leader_only`: vanilla damage, the whole stack dies with the front mob. | | `damage.max-kills-per-hit` | `1` | Base mobs removed by one lethal hit. | | `damage.kill-scaling.enabled` | `true` | Extra kills from an enchantment. | | `damage.kill-scaling.enchantment` | `SWEEPING_EDGE` | Any vanilla enchantment name (`LOOTING`, `SHARPNESS`, `POWER` ...). An unknown name turns the scaling off. | | `damage.kill-scaling.kills-per-level` | `2` | Extra kills per enchantment level. | | `damage.kill-scaling.max-kills` | `16` | Ceiling on kills per hit. | | `damage.death-effects` | `true` | Death sound and smoke for every logical kill. | | `damage.charge-weapon` | `true` | A cancelled hit skips vanilla tool wear, so a player's melee kill costs the weapon 1 durability (Unbreaking applies). Not in creative or spectator. | {% hint style="warning" %} With `proportional` or `leader_only`, killing the front mob loses the whole stack, and only one mob's loot drops. Keep `one_entity` unless you want that. {% endhint %} ## Drops and XP Section `drops`. | Key | Default | What it does | | -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | | `multiply-by-stack-size` | `true` | Mobs killed out of a stack drop loot. `false`: they drop nothing; only the last mob drops its normal loot. | | `max-item-drops-per-death` | `64` | Most items of one kind dropped by one hit. | | `multiply-xp` | `true` | Mobs killed out of a stack give XP. | | `max-xp-per-death` | `500` | Most XP from one hit. | | `use-logical-kills` | `true` | `true`: loot and XP are paid on every hit. `false`: kills are counted and paid all at once when the last mob dies. | With `use-logical-kills: true`, loot comes from the mob's **vanilla loot table**, rolled once per mob killed (at most 200 rolls per hit). The player who hit is passed as the killer. XP is the mob's normal XP × mobs killed, dropped as one orb. With `use-logical-kills: false`, nothing drops on each hit. When the last mob dies, its drops and XP are multiplied by the number of mobs killed out of the stack plus one, each item capped by `max-item-drops-per-death`. Mobs from an upgraded spawner add the spawner's XP and Drops boosts. See [Spawners](/origin-smp/stackmaster/spawners.md#upgrades). ## Breeding Section `behavior.stack-aware`. Feed two stacks of animals and they breed for the whole stack. When the **mother and father are both stacks**: * Babies in total = the smaller of the two stack sizes (the number of pairs), at most `max-babies-per-breed`. * Vanilla makes the first baby. StackMaster spawns the rest within one block of it, as babies, with spawn reason `BREEDING`. They then stack with each other like any baby. * The parents get the normal vanilla love cooldown. If one parent is a single mob that never stacked, vanilla breeding happens with one baby. The settings are read for the mother's world and type. | Key | Default | What it does | | ---------------------------------- | ------- | ------------------------------ | | `stack-aware.breeding` | `true` | Breeding for the whole stack. | | `stack-aware.max-babies-per-breed` | `16` | Most babies from one breeding. | ## Egg laying | Key | Default | What it does | | ------------------------------ | ------- | ----------------------------------------------------- | | `stack-aware.egg-laying` | `true` | A stacked chicken or turtle lays for the whole stack. | | `stack-aware.max-eggs-per-lay` | `64` | Most eggs from one laying. | * **Chickens:** the laid egg becomes a stack of eggs equal to the stack size, capped at `max-eggs-per-lay`. A stack of 20 chickens lays 20 eggs at a time. * **Turtles:** the number of eggs laid × the stack size, capped at `max-eggs-per-lay`. ## Transformation | Key | Default | What it does | | ---------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | | `stack-aware.preserve-size-on-transform` | `true` | When the front mob turns into another mob (zombie to drowned, for example), the new mob keeps the full stack size. | If the new type cannot stack (disabled or blacklisted), or this key is `false`, only one mob remains. ## Splitting Section `splitting`. | Key | Default | What it does | | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | `true` | Splitting on or off. | | `allow-player-split` | `true` | Sneak + right-click a stack to split it. Any player can do this. | | `max-split-size` | `50` | Most mobs one sneak + right-click pulls out. | | `triggers.*` | | No effect on mobs. Sneak + right-click is controlled by `allow-player-split`, and `/sm unstack` always works for staff with the permission. `damage` and `death` are obsolete and kept so older configs load. | Split mobs pop out as single mobs around the stack. Neither they nor the stack can merge again for **5 seconds**. After that they merge again if the rules allow it. Staff can also split with `/sm unstack `. See [Commands](/origin-smp/stackmaster/commands-permissions.md). ## Per-mob and per-world overrides Any key under `stacking-entities` can be changed for **one mob type** under `stacking-entities.entities.`, and for **one world** under `worlds..stacking-entities`. Use the same path as in the main section. Order: **per mob type**, then **per world**, then the main section. The first one that sets a key wins. ```yaml stacking-entities: entities: SKELETON: max-stack-size: 150 line-of-sight: require: true CREEPER: max-stack-size: 50 behavior: damage: max-kills-per-hit: 1 IRON_GOLEM: enabled: false ``` {% hint style="warning" %} The path must match the main section exactly. The default file has `drops: multiply: true` and `ai: mode: leader` under `ZOMBIE`, `SKELETON` and `CREEPER`. Those keys do not exist in the main section and do nothing. To change drops for one mob use `drops.multiply-by-stack-size`. {% endhint %} ## After a restart The size of a mob stack is saved on the mob itself (persistent data `stackmaster:stack_size`). When its chunk loads again the stack comes back with its size and nametag, and it keeps merging. Nothing about mob stacks is written to the [storage](/origin-smp/stackmaster/storage-and-sync.md) database. ## Other keys in this section These keys are in the file but are not used by the current version: `compatibility.default-mode`, `conditions.same-ai-state`, `line-of-sight.mode`, `merge-interval-ticks` (mobs use `general.merge-interval-ticks`), `behavior.representative`, `behavior.replace-leader`, `behavior.scale-entity`, `behavior.attacks.*` and `behavior.ai.*`. A stack always attacks like one mob and moves with the front mob's own AI.