VexOptimise

Comprehensive Minecraft server optimization and TPS protection plugin. Designed for Spigot/Paper 1.20+ servers (Java 17).

VexOptimise bundles every essential optimization into a single, fully configurable plugin: villager AI disabling, entity stacking, hopper throttling, redstone limiting, dynamic view distance, smart autosave, memory management, an automatic emergency mode - and much more.

---

Features

Villager Optimization

• Disable Villager AI - villagers stop pathfinding and wandering while trading keeps working perfectly
• Stock Restock Timer - trade stock is refreshed on a configurable timer (in seconds)
• Per-Chunk Villager Limit - blocks new villager spawns once a chunk reaches its configured cap

Animal & Mob Optimization

• Disable Farm Animal AI - freezes cows, sheep, pigs, chickens and more (fully configurable type list)
• Entity Protection - named, tamed and leashed mobs are never touched; babies are left alone so they can grow up
• Entity Stacking - merges overlapping mobs of the same type into a single stack shown as x24 cow, with optional extra death loot so farms stay fair
• Distant Mob AI Suspension - mobs far away from any player have their AI suspended until someone comes close; the distance shrinks automatically as TPS drops, progressively throttling pathfinding under load
• Soft Mob Cap - spawn blocking ramps up probabilistically as mob density rises, keeping populations natural instead of a hard on/off wall
• Dynamic Mob Cap - when TPS drops, the natural mob spawn cap automatically halves (70 -> 35 by default)

Cleanup & World

• Ground Item Clearing - periodic cleanup with countdown warnings via chat, action bar and bossbar
• Ground Item Merging - nearby same-type ground items physically combine into single stacks, slashing entity counts around farms and grinders
• Protected Items - named items and XP orbs (optional) are handled safely
• Explosion Limiting & Batching - caps the blocks destroyed per explosion and spreads the destruction over multiple ticks so big blasts never stall a tick
• Falling Block Limit - prevents sand/gravel gravity farms from crashing the server
• Aggressive Chunk Unloading - optionally unloads chunks early in empty regions to free RAM; while players fly fast (elytra), trailing chunks unload even sooner
• Smart Autosave - saves worlds gradually one-by-one instead of freezing the server with a full save

Redstone & Hoppers

• Hopper Cooldown - hoppers pull items at a configurable interval instead of every tick; massive auto-farms stop eating your server
• Adaptive Hopper Sleep Mode - hoppers feeding nearly-full containers automatically slow down further, no wasted work
• Redstone Limiter - clock circuits firing faster than the configured rate per second are automatically halted
• Firework Limiter - caps rocket launches per second, stopping elytra/firework lag machines
• Version-safe implementation - works on every server build, no cancellable-event support required

View Distance

• Dynamic View Distance - world view distance steps down gradually under lag and climbs back to maximum once performance recovers (min/max configurable)

Memory Management

• Auto GC Trigger - safely triggers garbage collection when heap usage passes a threshold (default 85%) or on a forced interval
• Memory Leak Detection - watches the post-GC heap baseline across GC cycles and raises an alert when it keeps rising
• Dead Entity Cleanup - instantly removes corpses stuck in the world after their death animation

Diagnostics

• CPU Sampling Profiler (/vexo profile) - Spark-style main-thread hotspot analysis without NMS: samples stack traces and ranks which plugin or server class burns the most tick time
• Lag Source Scan (/vexo lag) - heaviest worlds, most common entity types and hottest chunks at a glance

Spawn Control

• Wandering Trader blocking - stop traders from getting stuck between houses
• Phantom blocking - stop phantom piles from sleep-skipping players
• Portal Spam Guard - cooldown on rapid Nether portal transitions protects the server from chunk-load storms

Packet / Visual Throttling (optional, requires ProtocolLib)

• Particle Rate Limiter - per-player particle packet cap
• Sound Culling - per-player sound packet cap stops hundreds of chickens from flooding channels
• Movement Rate Limiting - stabilizes packet-spamming clients; laggy players get a friendly action-bar notice

Discord Webhook

• Fire-and-forget webhook integration sends emergency alerts such as: ⚠ [VexOptimise] Server TPS has dropped to a critical level! Emergency protocol engaged.

---

Smart TPS Protection Shield (Emergency Mode)

When TPS drops below the critical level (default 14.0) for a sustained period, VexOptimise automatically engages its emergency protocol:

1. Freezes all mob AI
2. Clears all ground items
3. Forces minimum view distance
4. Halts all redstone circuits
5. Sends alerts to console, admins (vexoptimise.alerts), the whole server (optional) and Discord

Once TPS recovers above the recovery threshold (16.5 by default), everything is restored exactly as it was. All thresholds and individual actions are toggleable in the config.

---

Commands

Command	Description
/vexo help	Command list
/vexo info	Live RAM, TPS (5s/30s/60s), CPU, chunk/entity/player counts, packet limiter stats and uptime
/vexo lag	Lag source scan: heaviest worlds, most common entity types and hottest chunks at a glance
/vexo profile [seconds]	Samples the server thread and ranks CPU hotspots (which plugin/class eats tick time)
/vexo optimize	Manual emergency optimization: item clear + entity stacking + chunk unload + GC in one shot
/vexo report	Writes a detailed performance report to a file in plugins/VexOptimise/reports/
/vexo reload	Reloads the configuration without restarting
/vexo update	Checks for updates against Modrinth

Alias: /vexopt

Permissions

Every subcommand has its own permission node:

Permission	Grants	Default
vexoptimise.admin	Parent permission covering all of the below	OP
vexoptimise.command.help	/vexo help	Everyone
vexoptimise.command.info	/vexo info	OP
vexoptimise.command.lag	/vexo lag	OP
vexoptimise.command.optimize	/vexo optimize	OP
vexoptimise.command.report	/vexo report	OP
vexoptimise.command.reload	/vexo reload	OP
vexoptimise.command.update	/vexo update	OP
vexoptimise.command.profile	/vexo profile	OP
vexoptimise.alerts	Receives emergency mode alerts	OP
vexoptimise.notify	Receives update notifications	OP

Tab completion only suggests subcommands the sender has permission for - perfect for giving moderators just lag and info.

---

Performance Logging & Reports

Everything important gets recorded to plugins/VexOptimise/logs/performance.log: TPS dips, emergency mode activations, GC reclaims, trimmed explosions, blocked redstone violations, portal spam and more. When something goes wrong you will know when and where.

---

Update Checker

VexOptimise queries the Modrinth API on startup and warns the console and in-game admins when a new version is available. Fully configurable or disablable in the config.

Installation

1. Drop the jar into your server's plugins/ folder
2. Start the server - plugins/VexOptimise/config.yml is generated
3. Tune the settings to your liking and run /vexo reload

Optional: install ProtocolLib to unlock particle/sound/movement packet throttling. Without it, VexOptimise runs normally and simply skips those modules.

Compatibility

• Minecraft 1.20+ and Java 17+
• Paper (recommended): every module works fully
• Spigot: works out of the box as well. The only difference is that the dynamic view distance feature has no effect there, because World#setViewDistance is a Paper-only API - every other module behaves identically on both platforms.
• Folia: limited compatibility mode - event-driven modules (mob caps, spawn control, hopper/redstone/firework limiters) run normally while scheduler-based modules are skipped automatically at startup
• ProtocolLib is optional; without it VexOptimise runs normally and simply skips the packet-throttling modules