PerformanceX

The all-in-one performance suite for Minecraft servers.

Folia  · Forge  ·  Paper  ·  Spigot  ·  Purpur  ·  MC 1.8.8 — 26.1.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. If you are genuinely struggling with LAG on your server! Just throw performancex on there and it should do the job without you needing to configure it. It does the job for most communities out there as it's designed around Survival servers by default. Configure it to your hearts content. It's powerful and does exactly what most servers NEED! Completely free!

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.8
• custom_name — item entity nametag, zero extra entities
• auto — 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 world reads 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).

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:

1. config.yml — master module toggles
2. modules/<name>.yml — per-module settings (generated with full comments)
3. worlds/<world>.yml — per-world overrides (any module setting)
4. /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

1. Drop PerformanceX.jar into your plugins/ folder
2. Start the server
3. Run /px status — verify all modules loaded
4. Edit any module in plugins/PerformanceX/modules/<name>.yml
5. Run /px reload — changes apply instantly

Smart defaults tuned for survival multiplayer — most servers need zero configuration changes.

Statistics

Built by ProtectCord