Reduce entities with stacking
Stack ground items, mobs and spawners into fewer entities, cap what a chunk can hold, and replace outdated items in player inventories with their fixed version.
You will have a server that ticks far fewer entities: dropped items and mobs join into one entity that shows
an amount, spawners stack into one block, and each chunk has a cap. A second tool, the item updater, swaps an
outdated item for its fixed version wherever players carry it. They are two modules in config.yml,
optimization and item-updater (Switch modules on and off).
Before you start#
Paper's own settings already cover part of this and are worth tuning first: merge-radius and
entity-activation-range in spigot.yml, and the despawn and per-chunk save limits in
paper-world-defaults.yml. ExyliaSurvivalCore stacking adds to them.
The optimization module has no commands. A stack's amount is saved on the entity or block itself, so stacks
survive a restart. A mob or item another plugin has stored data on is never stacked.
Turn stacking on and tune it#
Check the module is on
optimization is true in config.yml by default. A module switch needs a restart.
Open the settings page
Run /survivalcoreadmin, click Settings, then Optimization. The buttons are Item stacking,
Item stack size, Item lifetime, Mob stacking, Mob stack size, Stacked mobs idle,
Spawner stacking and Spawner stack size.
Edit the file for everything else
Mob types, spawn reasons and per-chunk limits are in modules/optimization/config.yml. Run
/survivalcoreadmin reload after editing.
Check that it works#
Drop 64 cobblestone and 64 more beside them: you should see one item on the ground named 128x Cobblestone.
Kill a stacked zombie: one dies, the stack drops by one and the loot is one zombie's.
Stack items on the ground#
Dropped items of the same kind join into one entity that holds more than a full stack. A new item looks for a
matching stack within items.radius blocks and joins it if the total stays within items.max-amount. Items
match on everything: type, name, lore, enchantments and data.
The entity carries up to one full stack, and its name shows the real amount from two items upwards. The name
is the item-stack-name message in lang/<code>/modules/optimization/messages.yml
({highlight}%amount%x {letters}%item% by default). Servers that had it as items.name have it moved there
when config.yml is upgraded to version 2.
Picking a stack up takes what the inventory has room for and leaves the rest on the ground. Hoppers do the same. Only ordinary items stack: never an item nobody can pick up, one that never despawns, one with a custom name, one another plugin has marked, or anything that does not stack in an inventory, such as tools and armour.
items.lifetime-seconds shortens how long a dropped item lasts, up to 300 seconds. 0 keeps the server's
own despawn time. It applies to every ordinary item, even when items.enabled is off.
Item settings
| Setting | Default | What it does |
|---|---|---|
items.enabled | true | Stack items on the ground past a full stack |
items.radius | 3.0 | How far, in blocks, a dropped item looks for a stack to join |
items.max-amount | 2048 | The most items one stack on the ground holds |
items.lifetime-seconds | 0 | Seconds a dropped item lasts, up to 300. 0 is the server's own despawn time |
The server removes an item at five minutes, so the plugin spawns the item that much older. Items that roll into each other after landing are merged by the plugin, not by the server, so the name stays correct.
Stack mobs#
Mobs of a listed type stack into one entity that stands for all of them. A mob joins a stack in two ways: when
it spawns, within mobs.radius blocks and while the total stays within mobs.max-amount; and every five
seconds, when mobs within 32 blocks of each player and within mobs.radius of each other are merged, so mobs
that walk together end up stacked.
The name shows the amount. It is the mob-stack-name message in the same messages file
({highlight}%amount%x {letters}%type% by default).
Killing a stack kills one mob. The death drops one mob's loot and counts as one kill, and a stack one
smaller spawns in its place. A farm pays what it always did from far fewer entities. Lava, the void or /kill
also take only one. The replacement is a fresh mob: only its age, a slime's size and a sheep's colour and
shearing are copied.
Mobs only stack with mobs that look alike: a baby never joins adults, a small slime never joins a big one, and
sheep share colour and shearing. A mob stacks only if it spawned for one of the listed mobs.reasons. Named,
tamed and leashed mobs, mobs with a rider or riding something, and mobs another plugin keeps data on never
stack. With mobs.disable-ai on, a stack stands still and does not attack.
Mob settings
| Setting | Default | What it does |
|---|---|---|
mobs.enabled | true | Stack mobs of a listed type |
mobs.radius | 5.0 | How far, in blocks, a mob looks for a stack to join, on spawn and in the five-second merge |
mobs.max-amount | 50 | The most mobs one stack stands for |
mobs.types | ZOMBIE, SKELETON, SPIDER, CAVE_SPIDER, BLAZE, WITCH, ENDERMAN, ZOMBIFIED_PIGLIN, IRON_GOLEM, PIG, COW, SHEEP, CHICKEN | The mob types that stack |
mobs.reasons | NATURAL, SPAWNER, SPAWNER_EGG, BREEDING | The spawn reasons a mob can stack from. A mob that is already a stack keeps stacking whatever brought it back |
mobs.disable-ai | false | Stacks stand still and do not attack. A mob back down to one gets its AI back |
Type and reason names are not case-sensitive.
Stack spawners#
When ExyliaSpawners is installed, spawner stacking here is off and the console logs "Spawner stacking is off: ExyliaSpawners handles it." Mob and item stacking and the chunk limits stay in this module. The rest of this section applies only without ExyliaSpawners.
Give the ranks that may stack spawners exyliasurvivalcore.optimization.spawners. A player then uses a
spawner item on a placed spawner of the same mob and it is added to that block instead of placed. Outside
creative, one spawner is taken from the hand. A block holds up to spawners.max-amount spawners.
A stacked spawner spawns its whole stack. Each time, with mob stacking on and the type listed, it spawns one mob standing for as many mobs as the block holds spawners; otherwise it spawns that many separate mobs. Sneaking and right-clicking a spawner with an empty hand shows how many it holds.
Breaking a stacked spawner takes one spawner off it and leaves the block. With spawners.silk-touch-returns
on and a Silk Touch tool, that spawner goes to the player; otherwise it is lost. The last spawner breaks the
way the server breaks any spawner.
Spawner settings
| Setting | Default | What it does |
|---|---|---|
spawners.enabled | true | Using a spawner on one of the same mob adds to it |
spawners.max-amount | 10 | The most spawners one block stands for |
spawners.silk-touch-returns | true | Breaking a stacked spawner with Silk Touch gives one spawner back |
optimization.spawner-broken always ends with "Silk Touch keeps it.", also when
spawners.silk-touch-returns is off and Silk Touch keeps nothing.
Cap what a chunk holds#
limits:
entities-per-chunk:
CHICKEN: 50
COW: 50
PIG: 50
SHEEP: 50
ZOMBIE: 40
SKELETON: 40
blocks-per-chunk:
HOPPER: 64entities-per-chunk, by entity type: a spawn that would pass the limit is refused. Spawns made by plugins
or commands are not limited; mobs from spawn eggs, breeding and spawners are. A stacked mob counts once, so a
chunk can hold the limit times mobs.max-amount mobs. Limits are checked before stacking, so a spawn that
would have joined a stack in a full chunk is refused as well. No permission bypasses this limit.
blocks-per-chunk, by material: placing a block past the limit is cancelled with
optimization.block-limit. Only blocks with a block entity count, such as hoppers, chests, furnaces and
spawners; a limit on stone never applies. Players with exyliasurvivalcore.optimization.bypass are not
limited.
Names are not case-sensitive and an empty map turns that limit off. Neither limit has its own switch: they run whenever the module is on.
| Permission | Who has it | What it allows |
|---|---|---|
exyliasurvivalcore.optimization.spawners | Everyone | Stacking spawners by placing one on another |
exyliasurvivalcore.optimization.bypass | Admins (op) | The entity and block limits |
Replace an outdated item#
When an item has to change, such as a reworked custom sword or a crate key with new lore, the item updater replaces every copy of the old item as players come across it. An update is a pair: the outdated item and the fixed item. Every stack that matches the outdated item exactly becomes the fixed item and keeps its amount. The match covers type, name, lore, enchantments, durability and every data component.
Open the editor
Run /itemupdater (aliases /iu, or /survivalcoreadmin itemupdater). It needs
exyliasurvivalcore.itemupdater.admin.
Create the update
Click Create ▸ Update. Type a name (64 characters at most), then hand over the outdated item, then the fixed item. Nothing is saved until both are in, so an abandoned creation leaves nothing behind.
Apply it now, or wait
Click Updates ▸ Update now, or run /itemupdater run, to check every player online on this server.
You are told how many items changed.
An update is refused when both items are the same or when another update already replaces that outdated item.
Check that it works#
Click your update, then Update ▸ Take copies. You get one of each. Hold the outdated copy or close your
inventory: it becomes the fixed item, and you are told with item-updater.updated how many changed.
When items are checked#
Nothing runs on a timer. Items are checked when a player joins (inventory and ender chest), when they switch
hotbar slot (the slot switched to), and when they close any inventory (their own, which is where an item taken
from a chest, a vault or a trade ends up). Items inside chests, vaults or on the ground are untouched until
they reach a player's inventory. The ender chest is only checked on join and by /itemupdater run.
Updates live in the database, so every server of a network sharing it applies the same ones, and an update saved on one server reaches the others without a restart.
The two screens
Item updater lists every update with its outdated and fixed item, with Updates ▸ Update now and Create ▸ Update. Opening an update shows:
| Button | What it does |
|---|---|
| Update ▸ Outdated item | Hand over a new outdated item |
| Update ▸ Fixed item | Hand over a new fixed item |
| Update ▸ Take copies | Gives you one of each |
| Update ▸ Delete | Asks for confirmation. Items stop updating, and items already updated stay as they are |
| Back ▸ Updates | Returns to the list |
Every button needs exyliasurvivalcore.itemupdater.admin.
Something missing on this page? Tell us on Discord