/
PerformanceX
The all-in-one performance suite for Minecraft servers.
Folia · Paper · Spigot · Purpur · MC 1.8.8 — 1.21.x · Java 8+
What is PerformanceX?
PerformanceX is a modular server performance suite — 29 independent modules that replace a dozen separate plugins with a single, zero-dependency JAR. Every module is self-contained: enable what you need, disable what you don't. No module depends on another. No restarts required to toggle anything.
It ships with smart defaults that work immediately on most servers. If a ClearLagg replacement is all you need, two modules and you're done. If you want AI throttling, lag machine detection, automatic backups, block logging, and Discord webhooks — it does all of that too.
Drop it in. Run /px status. You're done.
⏱ Item Despawn — The Headline Feature
Per-item-type configurable despawn timers with a floating countdown label hovering above every dropped item in real-time. The label shows item name, stack count, and time remaining.
Four rarity tiers come pre-configured:
| Tier | Duration | Examples |
|---|---|---|
| 🟣 Legendary | Never | Nether Star, Elytra, Dragon Egg, Totem of Undying |
| 🟠 Epic | 30 min | Diamond, Emerald, Trident, Ancient Debris, Netherite Ingot |
| 🟡 Valuable | 10 min | Iron Ingot, Gold Ingot, Blaze Rod, Ender Pearl |
| ⬜ Junk | 60 sec | Cobblestone, Dirt, Rotten Flesh, Gravel, Logs |
Everything else uses the default 5-minute timer. Every timer is configurable per item type, per world, and per integration.
Label rendering — picks the best automatically:
text_display— native TextDisplay entities (MC 1.19.4+, cleanest)armor_stand— invisible ArmorStand fallback, works back to 1.8.8custom_name— item entity nametag, zero extra entitiesauto— selects best option for your server version at startup
Label format is fully MiniMessage-customizable:
label_format: "<white><name> <gray>x<yellow><count> <gray>| <gold><time>"
renderer: auto # text_display → armor_stand → custom_name
Smart integrations:
- Timer resets when RoseStacker/StackMob stack size changes
- Per-world duration overrides (resource world = 30s, End = 10m)
- Labels auto-hide when no player is in range (bandwidth savings)
- Per-custom-item keys for ItemsAdder, DropHeads, ArmoredElytra, TreeFeller, Veinminer
🧹 Item Clear — ClearLagg Replacement
Scheduled and on-demand ground item removal that won't eat your valuables.
schedule: "every 15m"
warnings: ["5m", "1m", "30s", "10s", "5s"]
include: ["minecraft:*"]
exclude:
- "minecraft:nether_star"
- "minecraft:diamond"
- "itemsadder:*"
- Per-type include/exclude with wildcards (
minecraft:netherite_*) - Lands-claim awareness — items inside claimed land are never cleared
- Bypass-permission proximity guards — items near staff are protected
/px clear·/px clear here 64·/px clear world
⊕ Item Merge
Actively merges nearby identical ground items into stacks on a configurable sweep interval. Vanilla only merges at spawn — this catches items that land apart and wouldn't otherwise combine.
- Configurable merge radius (default: 8 blocks, cross-chunk)
- Respects max stack sizes per item type
- Blacklist specific materials (enchanted books, etc.)
- Players get every item — there are just fewer ground entities
🕐 Mob Despawn
Per-mob-type despawn timers with smart skip rules that protect every mob that matters:
- Named mobs (nametag or plugin), tamed animals, leashed mobs
- Mobs in vehicles, carrying passengers, or with the vanilla persistent flag
- SafariNet captures, Lands-claimed mobs
minecraft:phantom: 90 # Annoying — fast despawn
minecraft:zombie: 300 # Standard hostile
minecraft:pillager: 600 # Longer — looting opportunity
🗑 Mob Clear
Hard caps per chunk by mob family with intelligent culling:
| Family | Default Cap/Chunk |
|---|---|
| Hostile | 8 |
| Passive | 10 |
| Ambient | 4 |
| Water | 8 |
Shares skip rules with Mob Despawn — a protected mob is never cleared.
🧠 Mob AI Throttler — 30-50% TPS Savings
Mob AI accounts for 30-50% of server tick time. This module disables AI for mobs far from players using three configurable distance zones:
| Zone | Range | Behavior |
|---|---|---|
| 🟠 Full AI | 0 – 32 blocks | Normal pathfinding, attacking, wandering |
| 🟡 Reduced AI | 32 – 48 blocks | Walk goals only, look/attack disabled |
| 🔴 No AI | 48 – 64 blocks | Completely frozen, zero AI overhead |
Per-family overrides — tune hostile, passive, villager, and boss ranges independently.
Lag-aware mode: When TPS drops below 16.0, all ranges automatically shrink — more mobs freeze, server recovers. Zones restore when TPS recovers.
Always exempt: Named, tamed, leashed, and boss mobs (Wither, Ender Dragon) always have full AI regardless of distance.
🐾 Spawn Limiter
Per-chunk spawn budgets — prevents mob accumulation before it starts instead of cleaning up after. Works best paired with Mob Clear and Mob Despawn for a complete mob lifecycle.
📦 Entity Limiter
Per-chunk or per-world caps for non-mob entities:
| Type | Default Cap |
|---|---|
| Projectiles (arrows, tridents) | 50 (stuck/aged > 5s only) |
| XP Orbs | 100 (supports merge-instead-of-delete) |
| Boats / Minecarts | 20 each |
| Item Frames / Paintings | 100 / 50 |
| Falling Blocks | 30 |
| Primed TNT | 20 |
| Armor Stands | 50 (ArmorStandTools-protected skipped) |
XP Orb Merging: Nearby orbs merge into one with the combined value. Players get all XP — there are just fewer entities.
💥 Collision Limiter
Disables entity-entity collision checks for configurable types. Collision scales O(n²) — reducing it dramatically helps crowded areas.
- Always disabled: Armor Stands, Item Frames, Dropped Items, Projectiles
- Lag-aware: When TPS < 16.0, disables ALL mob-to-mob collisions automatically
⚡ Redstone Limiter
Detects and throttles redstone clocks and high-frequency circuits in three modes:
| Mode | Behavior |
|---|---|
| Monitor | Log to console only, no interference |
| Throttle | Limit pulses per second (default) |
| Disable | Cancel all events in configured worlds |
Lag-aware escalation: automatically steps from monitor → throttle → disable as TPS drops, and reverts when it recovers.
🔄 Hopper Limiter
Runs at vanilla speed by default — only activates under lag:
- Normal: 8-tick transfer interval (vanilla)
- During lag (TPS < 17.0): 24-tick interval
- Sorting systems still work — they just temporarily back up
⚙ Farm Limiter
Throttles the root causes of item and entity floods:
| Target | Default |
|---|---|
| Spawner min interval | 20s, max 10 mobs near spawner |
| Crop growth | 15% slower (85% pass rate) |
| Fast crops (bamboo, cactus, kelp) | 35-50% slower |
| Breeding cooldown | 10 minutes |
| Chicken egg laying | 25% chance |
| Item spawn cap | 64 items/chunk/sec (valuables exempt) |
🛡 Anti-Lag Machine
Detects and stops four types of lag machines before they crash your server:
| Detection | Threshold | Default Response |
|---|---|---|
| Piston Clock | > 20 fires/sec per location | Throttle + 30s suppression |
| Fluid Cascade | > 500 flow events/tick | Freeze fluid spread in chunk |
| Falling Block Launcher | > 50 entities/chunk/sec | Cancel entity spawns |
| TNT Duper | > 20 primed TNT/chunk | Remove entities + warn player |
Per-detection response modes: log (monitor only), throttle, freeze, remove_and_warn, or kick. Admin alert + Discord webhook on every detection.
🔥 Tile Entity Throttler
Pauses furnace/smoker/blast furnace ticking for blocks far from players. Saves burn state, pauses progress, resumes automatically when a player approaches. No items are lost.
- Beacons and conduits also throttled when distant
- Empty containers auto-skipped (nothing to process)
🌍 Chunk Manager
Fewer loaded chunks = fewer entities to tick, fewer tile entities, less memory.
- Stale unloading: Chunks 8+ chunks from any player unloaded after a 30s grace period
- Load rate limiting: Max 4 loads/tick — prevents lag spikes from fast travel
- Hard per-world caps — optional, for memory-constrained servers
- Spawn chunks and Lands-claimed chunks protected from unloading
⚡ Tick Speed
Per-world overrides for random tick speed, view distance, simulation distance, and spawn limits — no restart required:
worlds:
resource_world:
random_tick_speed: 1 # Slower growth = less lag
view_distance: 6
spawn_limits:
monster: 25
🚨 Lag Actions — 3-Tier Auto-Response
Multi-tier automatic lag response that escalates as TPS drops — and fully reverts when it recovers.
| Tier | TPS Threshold | Actions |
|---|---|---|
| 🟡 Tier 1 | < 18 TPS | Notify players, shrink AI zones by 25%, throttle hoppers |
| 🟠 Tier 2 | < 15 TPS | Clear items, cull mobs, suspend farms, force GC |
| 🔴 Tier 3 | < 10 TPS | Emergency AI freeze, suspend redstone, broadcast warning, optional auto-restart |
Hysteresis guard: Requires sustained lag (configurable window) before triggering — no flapping on one-tick spikes. Auto-recovery: All throttles revert when TPS recovers above the threshold for 3 consecutive checks.
14 available actions per tier: clear_items, clear_mobs, clear_entities, gc, throttle_spawns, throttle_redstone, throttle_hoppers, throttle_mob_ai, disable_collisions, unload_stale_chunks, broadcast, run_command, kill_phantoms, schedule_restart
📊 Performance Monitor
Live dashboard via /px monitor:
- TPS — 1m, 5m, 15m rolling averages
- MSPT — milliseconds per tick (out of 50ms budget)
- Heap — JVM memory (used / max)
- Entities — total loaded across all worlds
- Chunks — total loaded chunk count
- Per-world breakdown — chunks, entities, players, MSPT per world
Uses Paper's native tick APIs. On Spigot: built-in tick sampler provides equivalent data.
🔬 Benchmark & Speed Test
Hardware stress test measuring your server's real capacity:
- CPU — single-thread and multi-thread burn
- RAM — sequential write/read throughput
- Disk — read/write speed
- Network — download/upload via Cloudflare
Produces analysis with estimated max concurrent players, bottleneck identification, and hardware recommendations. Runs fully async — main tick never blocked.
/px benchmark · /px speedtest disk · /px speedtest network · /px speedtest tps
🗺 World Pre-Generation
Async chunk pre-generation so players never hit generation lag:
- Shapes: square, circle, diamond
- Parallel async generation on Paper — up to your CPU core count
- World border auto-detection —
/px pregen start worldreads your vanilla border - Auto-pause when players join, auto-resume when empty or TPS recovers
- Restart-persistent — jobs survive restarts, resume from checkpoint
- Terra and Iris generator detection + display
/px pregen start survival 5000 circle
/px pregen pause | resume | cancel | status
🧮 RAM Optimizer
Threshold-based and scheduled JVM garbage collection:
- Trigger GC when heap exceeds a configured percentage (default: 80%)
- Scheduled GC at quiet times (e.g.,
"at 4:00") - Lag Actions integration — GC fires automatically at T2+
🖥 CPU Stabilizer
Crash guardian + watchdog:
- Detects runaway threads and unresponsive tick loops
- Configurable restart on sustained CPU overload
- Watchdog thread monitors main-tick latency, alerts before a freeze becomes a crash
💾 Auto Backup
Scheduled world backups to 5 storage backends simultaneously:
| Backend | Examples |
|---|---|
| AWS S3 | S3, Backblaze B2, Cloudflare R2, MinIO, Wasabi |
| SFTP | Any SSH server with key or password auth |
| rclone | Google Drive, Dropbox, OneDrive, Mega, 70+ more |
| WebDAV | Nextcloud, ownCloud, any WebDAV server |
| Local | Filesystem path or NFS mount |
Compression: ZIP · GZIP · ZSTD (configurable level 0-9)
Retention: Keep last N backups per backend
Schedule: "every 6h" · "at 2:00,14:00" · manual /px backup now
Safety: Pre-backup /save-all, async upload (zero main-thread impact), restart-safe coordination
Notifications: Discord webhook on start, complete, and failure
📋 Block Logger
CoreProtect-style activity logging — zero external dependencies. Built-in SQLite database. MySQL supported. CoreProtect database passthrough when present (share one DB, one query tool).
Tracked events: Block Place · Block Break · Container Interaction · Explosion · Piston Push · Fluid Flow · Sign Edit · Entity Kill
/px log lookup x:100 y:64 z:200 r:10 t:1h
/px log lookup player:Steve t:7d a:break
/px log rollback player:Steve r:20 t:7d
/px log restore player:Steve r:20 t:7d
/px log purge 90
/px log status
Performance: All writes are async-queued and batch-flushed every 2 seconds. Auto-purges entries older than 30 days (configurable). World blacklist for creative/minigame worlds.
🔔 Webhooks
Real-time notifications for 20 event types to Discord, Slack, or any HTTP endpoint:
| Category | Events |
|---|---|
| Server | server_start, server_stop, restart_warning, restart |
| Performance | tps_drop, tps_recover, lag_action_tier_change, lag_machine_detected |
| Backups | backup_started, backup_complete, backup_failed |
| Cleanup | item_clear, mob_clear |
| Players | player_join, player_quit, player_death, first_join |
| World | pregen_start, pregen_complete, pregen_pause, log_shipped |
Per-event title, color, description, and @mention override. Rate-limited for Discord compliance. Automatic retries (3 attempts, 5s delay). Multi-endpoint support.
Discord setup: Paste your webhook URL → /px reload → done.
🔁 Auto Restart
Scheduled server restarts with countdown warnings:
- Schedule:
"at 4:00"(daily) ·"every 12h"· multiple times - Configurable warning intervals: 30m, 15m, 5m, 1m, 30s, 10s, 5s
- Minimum uptime guard prevents boot loops
- Cancel if admin is online (optional)
- Backup coordination — delays restart until active backup finishes
💬 Notifications
Unified notification routing for player-facing messages:
- Channels: Chat · Actionbar · Title · Boss Bar · Discord webhook
- Events: Item clear countdown · Mob clear · Restart countdown · Lag alerts
- Per-player opt-out:
/px notify off - MiniMessage formatting throughout — full RGB, gradients, click/hover
📡 Status Module
One-screen server health overview at /px status — TPS, MSPT, heap, entity counts, loaded chunks, module states, active lag actions, next backup, next restart. Everything you need to assess server health at a glance.
📤 Log Shipping
Ships health snapshots and performance logs to a remote HTTP endpoint on a configurable schedule. Useful for off-site monitoring dashboards or centralized multi-server observability.
📱 Geyser Support — Bedrock Compatibility
Bedrock players on GeyserMC crash on entities that Java handles fine. PerformanceX fixes that — without affecting Java players at all.
| Problem | Fix |
|---|---|
| TextDisplay entities crash Bedrock | Auto-fallback to ArmorStand renderer for Bedrock players |
| Label Y-offset wrong on Bedrock | +0.4y correction applied per-player |
| MiniMessage components unsupported | Stripped to legacy format for Bedrock targets |
| Actionbar clears too fast on Bedrock | Send rate doubled to maintain persistence |
| Too many entities freeze Bedrock renderer | Per-player entity cap (200, furthest hidden first) |
Detection chain: Geyser API → Floodgate API → UUID heuristic. No hard dependency on either.
🌐 16 Integrations
Auto-detected at startup — no configuration required:
| Plugin | Integration |
|---|---|
| RoseStacker | Timer resets on stack size change — the original bug fix |
| StackMob | Stack counts fed to mob limiter and AI throttler |
| ItemsAdder | Per-custom-item despawn keys (itemsadder:myset:myitem) |
| DropHeads | Per-player-head despawn overrides |
| SafariNet | Released mobs protected from despawn and clear |
| Lands | Items/mobs inside claims protected from clearing |
| WorldGuard | Region-aware item/mob clear — protected zones skipped |
| PlaceholderAPI | 14+ placeholders for scoreboards, TAB, etc. |
| LuckPerms | Per-world/per-group bypass for timers and clear |
| Vault | Economy-aware clear exemptions for premium ranks |
| EssentialsX | AFK detection — extended timers near AFK players |
| MythicMobs | Boss mobs excluded from AI throttle and despawn |
| Citizens | NPCs bypass all mob management modules |
| Dynmap / BlueMap | Lag event markers and chunk MSPT heatmaps |
| Folia | Full region-aware scheduler support — all modules |
| ProtocolLib | Enhanced packet-level label renderer (optional) |
📊 PlaceholderAPI Placeholders
| Placeholder | Value |
|---|---|
%performancex_tps% | Current TPS |
%performancex_tps_1m% | 1-minute TPS average |
%performancex_mspt% | Milliseconds per tick |
%performancex_entities% | Total loaded entities |
%performancex_chunks% | Total loaded chunks |
%performancex_tracked_items% | Items with active despawn timers |
%performancex_next_clear% | Time until next scheduled clear |
%performancex_ai_disabled% | Mobs with AI fully disabled |
%performancex_lag_machines% | Total lag machine detections |
%performancex_pregen_progress% | Pre-gen progress percentage |
Commands
All commands use /px (aliases: /performancex, /perfx).
Full Command Reference — click to expand
Core
| Command | Description |
|---|---|
/px status | One-screen server health overview |
/px monitor | Live TPS / MSPT / heap / entity dashboard |
/px modules | List all modules with enabled/error state |
/px enable <module> | Enable a module live (no restart) |
/px disable <module> | Disable a module live |
/px reload [module] | Reload all configs or one module |
/px version | Plugin version and platform info |
Item & Mob Management
| Command | Description |
|---|---|
/px clear [here \<r\> | world] | Clear ground items |
/px clearmobs [here \<r\> | world] | Clear mobs |
/px merge | Trigger manual item merge sweep |
/px entities [world] | Clear excess entities |
/px timer item <type> <seconds> | Set despawn timer for item type |
/px timer mob <type> <seconds> | Set despawn timer for mob type |
Module Controls
| Command | Description |
|---|---|
/px mobai <info|stats|shrink|restore> | AI throttler controls |
/px lagactions | Lag action system status |
/px lagmachine | Lag machine detection stats |
/px redstone | Redstone limiter status |
/px hoppers | Hopper limiter status |
/px chunks [world] | Chunk manager info |
/px tickspeed | Per-world tick settings |
World & Server
| Command | Description |
|---|---|
/px pregen <start|pause|resume|cancel|status> | World pre-generation |
/px backup [now] | Trigger manual backup |
/px restart [cancel] | Trigger or cancel restart |
/px geyser <info|list> | Geyser support and Bedrock player list |
Diagnostics & Logging
| Command | Description |
|---|---|
/px log <lookup|rollback|restore|purge|status> | Block logger queries |
/px benchmark [run|quick|results] | Hardware benchmark |
/px speedtest <disk|network|tps|chunkgen> | Diagnostic speed probes |
/px webhook <test|list> | Webhook management |
/px notify [on|off] | Toggle personal notifications |
Permissions
| Permission | Default |
|---|---|
performancex.admin | op |
performancex.notifications | everyone |
performancex.bypass.itemdespawn | false |
performancex.bypass.itemclear | false |
Every subcommand also has performancex.command.<name> (default: op).
Configuration
PerformanceX uses a simple three-file pattern:
config.yml— master module togglesmodules/<name>.yml— per-module settings (generated with full comments)worlds/<world>.yml— per-world overrides (any module setting)/px reload [module]— apply changes instantly, no restart
# config.yml — flip the switches
modules:
item-despawn: true
item-clear: true
mob-ai-throttler: true
lag-actions: true
auto-backup: true
webhooks: true
geyser-support: true
block-logger: false # disabled by default
# ... 21 more
Platform Support
| Platform | Versions | Notes |
|---|---|---|
| Paper | 1.8.8 — 1.21.x | Full support — recommended |
| Folia | 1.19.4+ | Full region-aware scheduling |
| Purpur | 1.16+ | Full support |
| Spigot | 1.8.8 — 1.21.x | Full support with built-in tick sampler |
Platform-specific APIs auto-selected at startup. Java 8+ bytecode — compatible with Java 8 through 21+.
Quick Start
- Drop
PerformanceX.jarinto yourplugins/folder - Start the server
- Run
/px status— verify all modules loaded - Edit any module in
plugins/PerformanceX/modules/<name>.yml - Run
/px reload— changes apply instantly
Smart defaults tuned for survival multiplayer — most servers need zero configuration changes.
Statistics
Built by ProtectCord
