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

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

The command supports subcommand tab completion (Tab).

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

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 ARR license.