Server Optimiser

Paper server monitoring, configurable limits and practical tools for investigating lag hotspots.

Server Optimiser gives server owners one place to monitor server health, manage protective limits, and inspect suspicious activity in loaded chunks. Configure it in config.yml or use the in-game menus. Its settings are designed to be understandable and adjustable, while the defaults avoid deleting items or changing your server's view and simulation distances.

Compatibility: Paper 26.1–26.3 · Java 25 · Paper only (not Folia)

What it does

Monitor server health

Check current TPS, MSPT and the plugin's overload state with /so status or the dashboard. The plugin can notify staff when performance stays unhealthy and when it recovers. Notifications are rate-limited so they do not flood chat.

By default, overload mode begins after 15 seconds when average tick time reaches 50 ms or TPS falls below 18. Recovery requires both tick time at or below 40 ms and TPS at or above 19.5 to remain healthy for 60 seconds. These sustained thresholds help avoid reacting to a brief spike.

Review Lag Watch reports

Use /so lagwatch or open Lag Watch from the dashboard to review loaded chunks that meet configured warning thresholds. Browse categories such as redstone and pistons, armor stands, minecarts and boats, frames and displays, dropped items, mobs, lit TNT, projectiles, hoppers and block entities.

Each report can show a world's name, chunk and block coordinates, measured counts, the matching threshold and when the chunk was sampled. Reports can be filtered and paginated. Staff with the extra teleport permission can inspect a safe surface position in a loaded chunk.

Lag Watch is an investigation aid. A warning means a configured count or activity threshold was reached; it does not measure CPU use, prove a crash attempt, identify who caused it, or mean the area is malicious. A busy farm, storage room, decoration area or minigame may be legitimate. Lag Watch does not remove entities, punish players or force-load chunks.

Default warning examples include 40 armor stands, 30 minecarts, 100 item frames, 250 dropped stacks, 100 living non-player entities, 20 primed TNT, 128 hoppers, and 500 block entities per chunk. Redstone, piston and hopper activity defaults are measured over a 30-second observation window. These reporting thresholds are separate from the protection limits described below.

Apply configurable activity limits

When automatic mode is enabled, the plugin can limit selected activity per chunk. The shipped defaults are intended as starting points; busy farms or custom gameplay may need different values.

Module	Shipped default
Redstone	Enabled; 1,500 signal-change events per second per chunk, then a 10-second cooldown on further power increases. Power-off changes are allowed.
Pistons	Enabled; 200 movement events per second per chunk, then a 5-second cooldown. Blocks and pistons are not deleted.
TNT	Enabled; 20 priming attempts per second and up to 40 primed TNT per chunk, then a 5-second cooldown. Existing lit TNT is not removed.
Projectiles	Enabled; 60 launches per second and up to 120 projectiles per launch chunk, then a 2-second cooldown. Existing projectiles are not removed.
Mob spawning	Enabled during sustained overload; limits selected new spawn reasons when a chunk already has 80 living non-player entities. Existing mobs are never culled.
Hopper transfers	Disabled; optional cap of 600 reported transfer attempts per second per chunk, then a 2-second cooldown.
Dropped-item manager	Enabled, but deletion is disabled. Cleanup is an optional feature and must be explicitly enabled.

Rate limits use one-second windows and cooldowns. Entity limits regulate new admissions; moving mobs and projectiles can cross chunk boundaries, so these are not hard occupancy guarantees. Cancelled activity can affect gameplay, and a redstone clock stopped by a limit may need to be restarted manually.

The mob module limits only the configured spawn reasons (by default natural spawns, patrols and reinforcements). Spawner mobs, breeding and plugin-created mobs are not included by default. Named and tamed mobs, villagers, wandering traders, major bosses, and entities carrying persistent data or scoreboard tags are exempt from mob-spawn blocking by default. Existing entities are not removed.

Optional dropped-item cleanup—with a warning period

Item deletion is off by default. Turning on the item manager alone does not enable deletion: the separate modules.items.cleanup option must also be set to true. By default, cleanup also requires sustained overload.

When enabled, cleanup only considers eligible old drops above the configured per-chunk stack count. Shipped thresholds are more than 150 separate dropped stacks in a chunk, at least 240 seconds old, with no more than 4 stacks removed per server tick. One dropped stack of 64 items counts as one stack. Cleanup processes a bounded number of chunks and observes the scanner's per-tick budget.

Players receive a configurable warning and grace period before cleanup starts (30 seconds by default), with reminder messages at 10 and 5 seconds. Start, completion and cancellation notices can be sent to the affected world or the whole server and can also be written to console. A 5-minute per-world cooldown helps prevent repeated countdowns.

The cleaner does not touch player inventories or containers. It preserves protected player and death drops, owned or marked items, custom-named or otherwise marked entities, and configured valuable materials. Custom-item protection also skips stacks with metadata such as names, lore or enchantments. Cleanup is permanent for the stacks it removes; restoring an older configuration does not restore deleted drops.

Configure globally or per world

The generated plugins/ServerOptimiser/config.yml includes plain-language comments and examples. Use it for detailed setup, or run /so settings to edit settings in-game. The menus support toggles, numbers, lists, messages and presets. GUI changes are saved to disk and persist through restarts.

By default, the same module settings apply across all worlds. Enable worlds.per-world-settings to create overrides for selected worlds. Any value without an override continues to inherit the global value. You can also exclude worlds from scanning and enforcement.

Three presets are included:

• Conservative: twice the Balanced numeric caps.
• Balanced: the shipped caps.
• Aggressive: half the Balanced numeric caps.

Presets change global numeric module caps; they do not enable item deletion, change server distances, erase world overrides, or turn modules on and off. If you adjust the values yourself, the selected profile becomes custom.

Inspect hotspots and history

Hotspots rank sampled, loaded chunks using entity, block-entity and recent activity counts. Use the rankings to decide where to investigate, then use Lag Watch details or a profiling tool such as spark to measure actual server work. A hotspot score is not a CPU measurement.

Scanning is gradual and budgeted. The default is at most one chunk per tick, with scanning stopping when the 0.5 ms per-tick budget is reached and waiting at least 30 seconds before rescanning a chunk. Only loaded chunks are inspected; the plugin does not load chunks just to scan them. A single very crowded chunk snapshot cannot be interrupted midway, so it can exceed the configured budget. Counts may be stale until the next sample.

History records recent interventions and groups repeated actions to keep the log readable. It is useful for seeing where and when the plugin applied a limit, but it does not prove that the recorded action caused a performance issue.

In-game commands

Command	Purpose
/so	Open the dashboard
/so status	View TPS, MSPT, overload state and mode
/so settings	Open global settings
/so worlds	Open world settings
/so hotspots	View sampled loaded-chunk rankings
/so lagwatch	View filtered suspicious-area reports
/so history	View recent intervention history
/so set <key> <value>	Change a global setting
/so world <name> set <key> <value>	Set a world override
/so world <name> set <key> inherit	Remove a world override
/so reload	Validate and reload this plugin's config
/so restore confirm	Restore the previous saved config
/so release	Clear active rate-limit cooldowns
/so profile	Start a 120-second spark profiler, if spark is installed and permitted
/so cancel	Cancel pending chat input in a settings menu

/serveroptimiser is the long command and /optimiser is an alias. /so reload reloads this plugin's settings; it is not a server-wide reload.

Permissions

All permissions default to server operators. Permissions are also listed in the generated config header.

Permission	What it allows
serveroptimiser.admin	Dashboard, settings, diagnostics, config reload/restore and cooldown release
serveroptimiser.teleport	Safe surface teleport from a hotspot or Lag Watch report; also requires admin access
serveroptimiser.profile	Spark profiling shortcut; also requires admin access and spark's own permission
serveroptimiser.notify	Receive rate-limited overload and recovery notices

Configuration examples

Want a shared setup for all worlds? Leave worlds.per-world-settings set to false, then edit the global values under modules.

Want different limits in a resource world? Enable worlds.per-world-settings, open /so worlds, select that world, and change only the settings that should differ. Other settings inherit the global values.

Want Lag Watch without automatic interventions? Keep automatic: false to stop enforcement and removals while retaining diagnostics and sampled reports.

Want cleanup countdowns but no item deletion? Leave modules.items.cleanup: false. Cleanup announcements do not enable deletion by themselves.

Want stricter redstone protection? Lower modules.redstone.events-per-second, or increase the cooldown. Be aware that legitimate clocks and farms can also reach the limit.

Privacy-conscious bStats metrics

The plugin includes bStats plugin ID 34659, enabled by default. It reports standard aggregate plugin/server statistics and optional custom charts for settings, health bands, scanner counts and intervention totals. Custom charts do not send player names, world names, chat or coordinates. Disable metrics.enabled in the config, or use the shared bStats opt-out, to opt out.

What Server Optimiser does not change

Server Optimiser does not modify server.properties, view distance or simulation distance. It does not force garbage collection, unload arbitrary chunks, disable other plugins, or run world scans asynchronously. It is Paper-only, not Folia-compatible. Actual performance gains depend on your server's workload; limits may change gameplay, and the plugin cannot prevent every source of lag or crashes.

Install

1. Stop your Paper server.
2. Place ServerOptimiser-3.1.1.jar in the server's plugins folder.
3. Start Paper and let the plugin create its config.
4. Run /so as an operator to open the dashboard, then review plugins/ServerOptimiser/config.yml before enabling optional behavior.

Use a full server restart when replacing the JAR. When upgrading within, keep your existing plugin folder so your settings are preserved. Do not leave multiple Server Optimiser JAR versions in plugins at the same time.