Optimizator

A lightweight optimization plugin for Paper / Folia servers from Minecraft 1.16.5 to 1.21.11.

A single .jar works across the whole version range: the plugin is compiled against the oldest API (1.16.5), so it also loads on newer versions thanks to Bukkit API backward compatibility. No external libraries are required.

Features

• Entities — cancels mob spawning when there are no players within a set radius; removes chunk overflow; per-chunk limit for removed entities; optional removal of distant mobs; protected type list.
• Items — removes old dropped items (with a player warning) and merges nearby identical stacks.
• Explosions — configurable cancellation of creeper, TNT and Wither explosions; world whitelist where explosions are always allowed.
• Chunks — periodic tracking of loaded chunks.
• TPS monitor — tracks TPS and memory with warnings when performance drops.
• World blacklist — fully disables optimization in selected worlds.
• Folia — safe scheduler: global tasks via GlobalRegionScheduler, chunk work in the player's region (RegionScheduler), foreign regions are never touched.
• One JAR for all versions — from 1.16.5 to 1.21.11 without rebuilding.
• Statistics and commands — counters, /optimizator with tab completion.
• Hot reload — /optimizator reload without restarting the server.

---

Gameplay-Safe

The plugin is designed to be invisible to players:

• Only abandoned hostile mobs are removed. Removal applies exclusively to Mob entities that despawn on their own (getRemoveWhenFarAway() == true). Animals, spawner mobs and persistent mobs are never touched.
• Important entities are protected. The following are never removed: players, tamed pets, named mobs, bosses (Ender Dragon, Wither), mobs listed in protected-types, and any entity that is carrying someone or being ridden (including by players).
• Safety radius. Within entity.safety-radius (32 blocks by default) around a player, nothing is removed — fights, farms and pets are unaffected.
• Spawn cancellation is unnoticeable. Only natural NATURAL spawning is cut off, and only far from all players — in places nobody sees.
• Items are not lost. Only items older than item-lifetime are removed (600 sec by default; vanilla removes them after 300 sec). Items with a name, lore or enchantments are protected (protect-valuable). Item merging removes nothing — it only combines identical stacks.
• Explosions are not cancelled by default — every cancel-* option is false.
• Everything can be turned off individually. Any part can be disabled, and worlds can be added to disabled-worlds.

---

Compatibility

Server	Versions	Task scheduler
Paper / Spigot	1.16.5 – 1.21.11	BukkitScheduler
Folia	1.19.4 – 1.21.11	GlobalRegionScheduler / RegionScheduler

Folia does not exist below version 1.19.4, so on 1.16.5 the plugin runs in normal Paper/Spigot mode and the regional mode is enabled automatically when running on Folia.

---

Requirements

• Server: Paper, Folia or Spigot of a supported version.
• Java: for building — JDK 16+; for running — the Java version matching your server (Java 16 for 1.16.5, Java 21 for 1.21+).

Installation

1. Build the plugin (see Building) or grab the ready-made Optimizator-1.0.0.jar.
2. Place Optimizator-1.0.0.jar into your server's plugins/ folder.
3. Start the server — a plugins/Optimizator/config.yml file will be created.
4. Edit config.yml to your needs.
5. Apply the changes with /optimizator reload.

Commands and Permissions

Command	Description
/optimizator reload	Reload config.yml and restart tasks
/optimizator stats	General statistics (MC version, TPS, memory, counters)
/optimizator entity	Entity statistics
/optimizator items	Item statistics
/optimizator chunk	Chunk statistics
/optimizator explosion	Explosion statistics
/optimizator tps	Current TPS and memory usage
/optimizator folia	Check whether the server is running on Folia
/optimizator reset	Reset all statistics

The command supports subcommand tab completion (Tab).

Permission	Description	Default
optimizator.admin	Access to all plugin commands	op

---

Configuration

The plugins/Optimizator/config.yml file:

# Debug messages to the console.
debug: false

# Worlds where optimization is fully disabled (by world name).
disabled-worlds: []

entity:
  optimization-enabled: true
  cancel-spawns: true        # Cancel natural spawning away from players
  mob-spawn-range: 48        # Mob spawn radius around players (blocks)
  max-entities-per-chunk: 50 # Limit of mobs removed per chunk
  max-living-per-chunk: 30   # Limit of living entities removed per chunk (0 = off)
  remove-far-mobs: false     # Remove mobs far away from players
  safety-radius: 32          # Never remove anything closer than this to a player
  protected-types:           # Types that are never removed
    - PLAYER
    - VILLAGER
    - WANDERING_TRADER
    - IRON_GOLEM
    - SNOWMAN
    - WOLF
    - CAT
    - PARROT
    - HORSE
    - DONKEY
    - MULE
    - LLAMA
    - TRADER_LLAMA
    - AXOLOTL
    - ALLAY

explosion:
  optimization-enabled: true
  cancel-creeper: false      # Cancel creeper explosions
  cancel-tnt: false          # Cancel TNT explosions
  cancel-wither: false       # Cancel Wither explosions
  allowed-worlds: []         # Worlds where explosions are always allowed

items:
  cleanup-enabled: true      # Remove old dropped items
  item-lifetime: 600         # Item lifetime (seconds)
  cleanup-interval: 60       # Check interval (seconds)
  warn-before-cleanup: true  # Warn players before removal
  warn-delay: 5              # Delay between warning and removal (seconds)
  protect-valuable: true     # Do not remove items with name/lore/enchantments
  merge-items: true          # Merge nearby identical items
  merge-radius: 1.5          # Merge radius (blocks)

chunk:
  optimization-enabled: true
  auto-save-interval: 1200   # Chunk tracking interval (ticks, 1200 = 60 sec)
  save-inactive-chunks: true

tps:
  monitor-enabled: true      # Track TPS
  warn-threshold: 15.0       # TPS warning threshold
  check-interval: 60         # Check interval (seconds)

Settings Reference

Setting	Type	Default	Description
debug	bool	false	Print debug messages
disabled-worlds	list	[]	Worlds where optimization is fully disabled
entity.optimization-enabled	bool	true	Entity optimization
entity.cancel-spawns	bool	true	Cancel natural spawning away from players
entity.mob-spawn-range	int	48	Mob spawn radius around players (blocks)
entity.max-entities-per-chunk	int	50	Limit of mobs removed per chunk
entity.max-living-per-chunk	int	30	Limit of living entities removed (0 = off)
entity.remove-far-mobs	bool	false	Remove mobs far from players
entity.safety-radius	int	32	Never remove entities closer to a player (blocks)
entity.protected-types	list	see above	Types that are never removed
explosion.optimization-enabled	bool	true	Explosion optimization
explosion.cancel-creeper	bool	false	Cancel creeper explosions
explosion.cancel-tnt	bool	false	Cancel TNT explosions
explosion.cancel-wither	bool	false	Cancel Wither explosions
explosion.allowed-worlds	list	[]	Worlds where explosions are always allowed
items.cleanup-enabled	bool	true	Remove old items
items.item-lifetime	int	600	Item lifetime (seconds)
items.cleanup-interval	int	60	Check interval (seconds)
items.warn-before-cleanup	bool	true	Warn before removal
items.warn-delay	int	5	Delay before removal (seconds)
items.protect-valuable	bool	true	Do not remove items with name/lore/enchantments
items.merge-items	bool	true	Merge nearby items
items.merge-radius	double	1.5	Merge radius (blocks)
chunk.optimization-enabled	bool	true	Chunk tracking
chunk.auto-save-interval	int	1200	Chunk tracking interval (ticks)
chunk.save-inactive-chunks	bool	true	Track inactive chunks
tps.monitor-enabled	bool	true	TPS and memory monitor
tps.warn-threshold	double	15.0	TPS warning threshold
tps.check-interval	int	60	TPS check interval (seconds)

---

How It Works

• OptimizatorPlugin — entry point: reads the config, wires up the managers and the command, starts the tasks, and supports a full reload.
• FoliaOptimizer — the central scheduler. Detects Folia and dispatches tasks through the Folia schedulers or BukkitScheduler. Returns a TaskHandle for clean task cancellation on reload.
• EntityOptimizer — every 10 seconds walks chunks and removes only "abandoned" hostile mobs above the limit: it never touches pets, named mobs, bosses, persistent mobs, or anything within safety-radius of players. On Folia it only walks player regions.
• OptimizatorListener — listens to CreatureSpawnEvent and cancels natural mob spawning far from players.
• ExplosionOptimizer — listens to ExplosionPrimeEvent and cancels the chosen explosions, honoring the world whitelist.
• ItemOptimizer — cleans up old items (with a warning) and merges nearby identical stacks.
• ChunkOptimizer — periodically tracks loaded chunks.
• TPSMonitor — measures TPS (via Paper getTPS() or its own sampling) and memory, logging a warning when performance drops.
• ConfigManager — loads, saves and reloads the settings.
• ServerVersion — detects and compares the Minecraft version.

All heavy passes run on a timer and never block the main tick.

---

Folia Support

Folia is a separate build (a Paper fork) with regional multithreading, available since 1.19.4.

The plugin detects Folia by the io.papermc.paper.threadedregions.RegionizedServer class — it exists only in Folia. Detecting by RegionScheduler is not reliable: since Paper 1.20 that class is also present in regular Paper as a main-thread wrapper, which would give a false result.

• Global tasks (timers) — via GlobalRegionScheduler.
• Chunk and entity work — in the player's region via RegionScheduler.
• Foreign regions are skipped (Bukkit.isOwnedByCurrentRegion), so entity access is always thread-safe.
• On regular Paper/Spigot everything runs via BukkitScheduler.

---

Troubleshooting

The plugin does not load; the log shows Unsupported class file major version. The server is running on an older Java. Use Java 21 for 1.20.5+, Java 16/17 for 1.16.5–1.17. The plugin works with all of them; the server's own Java version is what matters.

Tasks are not running. Enable debug: true, check the console and make sure the relevant section (entity / items / chunk / tps) is enabled and the world is not listed in disabled-worlds.

Mobs keep spawning nearby. Natural spawning is only cancelled for the NATURAL reason and only when the nearest player is farther than mob-spawn-range. Lower the value to strengthen the effect.

Necessary items/entities are being removed. Increase item-lifetime or remove the type from entity.protected-types. For items, disable items.cleanup-enabled.

Item removal messages are spamming. Disable items.warn-before-cleanup or increase items.cleanup-interval.

I want to apply changes. After editing config.yml, run /optimizator reload — the tasks will restart.

---

Changelog

1.0.0

• A single JAR for Minecraft 1.16.5 – 1.21.11.
• Folia-safe scheduler: global tasks, regional tasks and task cancellation without a server restart.
• Gameplay safety: only abandoned hostile mobs are removed; protection for pets, named mobs, bosses and persistent mobs; a safety radius around players (entity.safety-radius).
• Item optimization: cleanup of old items and merging of nearby stacks; protection for valuable items (items.protect-valuable).
• TPS and memory monitor with warnings.
• World blacklist and a world whitelist for explosions.
• Protected entity type list.
• Per-chunk limit of removed entities.
• Command tab completion, items, tps, reset subcommands.
• Full config reload via /optimizator reload.

---

License

This project is distributed under the MIT license.