Optimizator

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

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 – 26.3	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 **ARR** license.