# PerformanceX **Server performance, all in one plugin.** [![Servers](https://img.shields.io/bstats/servers/30806?label=Servers&color=F97316&style=for-the-badge)](https://bstats.org/plugin/bukkit/PerformanceX/30806) [![Players](https://img.shields.io/bstats/players/30806?label=Players&color=F97316&style=for-the-badge)](https://bstats.org/plugin/bukkit/PerformanceX/30806) [![Modrinth](https://img.shields.io/modrinth/dt/performancex?label=Downloads&color=F97316&style=for-the-badge)](https://modrinth.com/plugin/performancex) **Folia · Paper · Spigot · Purpur · MC 1.8.8 — 26.1.x · Java 8+** --- ## What is PerformanceX? PerformanceX is a modular server performance suite — 65+ independent modules that replace a pile of single-purpose plugins with one zero-dependency JAR. Every module does one job. Enable what you need, ignore the rest. No module depends on another, no restarts required to toggle anything, and every config file is generated with full comments explaining every option. The defaults are tuned for survival multiplayer servers and work out of the box on most setups. If all you want is a ClearLagg replacement, two modules get you there. If you want the full stack — AI throttling, lag machine detection, automatic backups with cloud upload, block logging, Discord webhooks, world pre-generation, AFK handling, player sleep voting, and a built-in tick profiler — it does all of that too. **Drop it in. Run `/px status`. You're done.** --- ## Module Overview All Modules

--- ### ⏱ Item Despawn Per-item-type configurable despawn timers with a floating countdown label hovering above every dropped item. The label shows item name, stack count, and time remaining — updated live. **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 | | 🟡 **Valuable** | 10 min | Iron Ingot, Gold Ingot, Blaze Rod, Ender Pearl | | ⬜ **Junk** | 60 sec | Cobblestone, Dirt, Rotten Flesh, Gravel, Logs | Everything else defaults to 5 minutes. 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+) - `armor_stand` — invisible ArmorStand fallback, works back to 1.8.8 - `custom_name` — item entity nametag, zero extra entities - `auto` — selects best renderer at startup **Label format is fully MiniMessage-customizable:** ```yaml label_format: " x | " renderer: auto ``` Smart integrations: timer resets when RoseStacker/StackMob stack size changes, per-world duration overrides, labels auto-hide when no player is in range, per-custom-item keys for ItemsAdder, DropHeads, ArmoredElytra, TreeFeller, Veinminer. --- ### 💎 Item Rarity Assigns dropped items to rarity tiers with animated floating labels, particles, and sounds. Works alongside Item Despawn — rarity tiers override the default label style while keeping the same despawn timers. Each tier is independently configurable: - **Animated label frames** — multiple MiniMessage strings cycled at a set rate (e.g., shimmering gradient for Legendary) - **Particles** — any particle type, count, spread, and emit interval - **Drop sound** — plays when the item hits the ground - **Merge sound** — plays when two items of this tier stack together Ships with five tiers pre-configured: Legendary (gold shimmer + END_ROD particles), Epic (purple gradient + witch particles), Rare (aqua), Uncommon (green), Common (no special styling — falls back to item-despawn.yml format). Items not explicitly assigned fall to the `default_tier`. ```yaml tiers: legendary: label_frames: - "◆ x │ " particle: type: "END_ROD" interval_ticks: 3 ``` --- ### 🧹 Item Clear Scheduled and on-demand item removal that won't touch your valuables. ```yaml schedule: "every 15m" warnings: ["5m", "1m", "30s", "10s", "5s"] include: ["minecraft:*"] exclude: - "minecraft:diamond" - "itemsadder:*" ``` - Per-type include/exclude with wildcards (`minecraft:netherite_*`) - Lands claim awareness — items inside protected land are never cleared - Bypass-permission proximity guard — items near staff are skipped - `/px clear` · `/px clear here 64` · `/px clear world` --- ### ⊕ Item Merge Actively merges nearby identical ground items on a configurable sweep interval. Vanilla only merges at the moment items spawn — this catches items that land apart and drift over time. - Configurable merge radius (default 8 blocks, works cross-chunk) - Respects max stack sizes per item type - Blacklist specific materials (enchanted books, etc.) - Players receive every item — there are just fewer ground entities --- ### 🔄 Drop Merge Instantly merges item drops at the moment they appear — on mob death, block break, or any drop event — rather than waiting for a sweep interval. Reduces peak entity count at high-loot moments (mob farms, ore mining, tree felling). - Merge radius configurable per drop source type - Skips merging for items on the exclude list - Works alongside Item Merge — Drop Merge handles the spike, Item Merge catches stragglers --- ## 🐾 Mob Management ### 🕐 Mob Despawn Per-mob-type despawn timers with smart skip rules that protect every mob that matters. Protected from despawn: named mobs (nametag or plugin-set), tamed animals, leashed mobs, mobs in vehicles or carrying passengers, mobs with the vanilla persistent flag, SafariNet captures, and mobs in Lands-claimed areas. ```yaml minecraft:phantom: 90 minecraft:zombie: 300 minecraft:pillager: 600 ``` --- ### 🗑 Mob Clear Hard caps per chunk by mob family. Culls the oldest mobs first. Shares skip rules with Mob Despawn — a protected mob is never cleared. | Family | Default Cap/Chunk | |:-------|:-----------------| | Hostile | 8 | | Passive | 10 | | Ambient | 4 | | Water | 8 | --- ### 🧠 Mob AI Throttler On servers with high mob counts, mob AI pathfinding and goal evaluation can be a significant part of tick time. This module reduces AI processing for mobs that are 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 | Fully frozen, zero AI overhead | Per-family overrides — tune hostile, passive, villager, and boss zones independently. Lag-aware: when TPS drops below 16.0, all ranges automatically shrink so more mobs freeze and the server can recover. Zones restore when TPS comes back up. Always exempt: named mobs, tamed animals, leashed mobs, and boss mobs (Wither, Ender Dragon) always run full AI regardless of distance. --- ### 🐣 Spawn Limiter Per-chunk spawn budgets that stop mob accumulation before it starts, rather than cleaning up after. Works best paired with Mob Clear and Mob Despawn for a complete mob lifecycle. Configurable caps per mob family per chunk. Lag-aware: tightens caps automatically when TPS drops. --- ### 📚 Mob Stacker Merges nearby mobs of the same type into a single entity with a count. Dramatically reduces entity count on mob farms without removing any mobs — players still get full drops scaled to the stack size. - Configurable stack radius and max stack size per mob type - Displays stack size above the entity with MiniMessage formatting - Stacks split on damage — partial kills distribute correctly - Integrates with StackMob and RoseStacker where present --- ### 🚮 Entity Culling Removes stuck or abandoned entities that have been sitting in the same position for too long without interacting with anything. Targets entities that are effectively leaking — items clipped into blocks, projectiles buried in terrain, abandoned item entities in unloaded areas. - Configurable staleness timer per entity type - Always skips named, tamed, leashed, and plugin-flagged entities - Logs removals to console (optional) so you can see what's being cleaned up --- ### 🐔 Mob Griefing Optimizer Per-mob-type control over griefing behavior, with a lag-aware mode that disables all mob griefing globally when TPS is low. - Block all griefing under lag threshold with a single toggle - Per-mob-type overrides: Creepers, Endermen, Zombies, Silverfish, etc. - Ghast fireball block damage, Wither explosion damage, etc. — each configurable - Does not touch game rules — runs as an event handler so it can be toggled live --- ### 🐄 Breeding Throttler Limits breeding events per world per tick to prevent players from causing entity count spikes by mass-breeding on farms. - Per-world configurable rate limit (default: max 5 breeding events per tick per world) - Cooldown per parent pair — prevents re-triggering immediately - Logs excessive breeding attempts (optional) --- ### 🏘 Villager Optimizer Villagers are some of the most tick-heavy mobs in the game. This module addresses that across several axes: - **Per-world caps** — hard limit on total villagers per world - **AI throttle** — villagers beyond a configurable distance from players have their AI reduced (same zone system as Mob AI Throttler) - **Trade limiting** — optional limit on trades per villager per session to reduce restocking churn - **Breeding limit** — per-world cap on how many villagers can breed per tick --- ## 📐 Entity & Physics Caps ### 📋 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 (merges nearby orbs instead of deleting) | | 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 combine into one with the full value. Players get all XP — there are just fewer entities. --- ### ⏱ Entity Tick Budget Circuit breaker for entity ticking. Monitors how long entities are taking to tick each server tick. If entity MSPT exceeds the configured budget, it triggers Mob AI Throttler to temporarily tighten its zones, buying the server time to recover. - Configurable MSPT budget threshold (default: 25ms) - Integrates with Mob AI Throttler — tightens zones when over budget, relaxes when under - Separate thresholds for warning (log only) and action (trigger throttle) --- ### 💥 Collision Limiter Disables entity-entity collision checks for types where collisions don't matter gameplay-wise. Always disabled: Armor Stands, Item Frames, Dropped Items, Projectiles. Lag-aware: when TPS drops below 16.0, disables all mob-to-mob collisions automatically and restores them when TPS recovers. --- ### 🏹 Projectile Limiter Per-player and per-world caps on active projectiles: - Per-player arrow cap (default: 20) — excess arrows removed oldest-first - Stuck arrow cleanup — arrows embedded in blocks longer than a configurable duration are removed - Per-world total projectile cap across all types - Trident return detection — only removes stuck arrows, not lodged tridents being retrieved --- ### 💣 Explosion Optimizer Caps concurrent explosions and optionally reduces explosion radii under lag. - Max explosions per tick (default: 10) — excess queued or cancelled - Radius reduction under lag: when TPS < threshold, explosion radius scales down by a configurable percentage - Block break cancellation mode: keep explosion damage to entities but prevent block destruction entirely (configurable per-world) - Fire spread from explosions configurable independently --- ### 🪨 Physics Limiter Rate-limits block physics events (block updates propagating to neighbors) per chunk per tick. Useful for servers where players run large-scale machinery that triggers cascading block updates. - Configurable max physics events per chunk per tick - Lag-aware: tightens cap automatically when TPS drops - Separate limits for update types (falling blocks, sand physics, etc.) --- ### 🖼 Item Frame Optimizer Freezes item frames that are far from any player. Item frames tick every 5 ticks by default — on servers with hundreds of decorative frames, this adds up. - Distance threshold: item frames beyond this range are frozen (rotation checks skipped) - Always unfreezes when a player approaches - Glow item frames handled separately (configurable) --- ## 🌍 World & Tick Control ### ⚡ 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 | | **Disable** | Cancel all events in configured worlds | Lag-aware escalation: steps automatically from monitor → throttle → disable as TPS drops, 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 minimum interval | 20s, max 10 mobs near spawner | | Crop growth | 15% slower | | 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) | --- ### 🔩 Piston Limiter Caps piston extension and retraction events per chunk per tick. Detects piston clocks and suppresses them when they exceed the configured threshold. Separate from Anti-Lag Machine's piston clock detection — this is a steady-rate cap, not a spike detector. - Configurable max piston events per chunk per tick - Lag-aware: lowers cap when TPS drops - Exempt list for specific chunk coordinates (for piston art, etc.) --- ### 🌊 Fluid Flow Limiter Rate-limits water and lava flow events per chunk per tick. Prevents server-wide lag from fluid cascades — a very common source of sudden TPS drops on survival servers when players dam rivers or create lava waterfalls. - Separate limits for water vs lava - Configurable freeze behavior: cancel excess flow events or queue them - Lag-aware: tightens limits when TPS drops --- ### 🍃 Leaf Decay Optimizer Rate-limits leaf decay events per chunk per tick. When large tree structures are cut or die, vanilla processes every leaf block in rapid succession. On servers with many players cutting forests simultaneously, this can spike tick time noticeably. - Configurable max leaf decays per chunk per tick - Decay is deferred, not cancelled — every leaf still decays, just spread across more ticks - Works with custom trees from structure generators --- ### 🔥 Tile Entity Throttler Pauses furnace, smoker, and blast furnace ticking for blocks that are far from any player. Saves the burn state, pauses progress, and resumes automatically when a player approaches. No items are lost. - Beacons and conduits also throttled when no player is nearby - Empty containers auto-skipped (nothing to process anyway) - Configurable distance threshold and check interval --- ### 🌱 Spawn Tick Optimizer Reduces how often the server attempts mob spawning when mob counts are already near the cap. Vanilla runs spawn attempts every tick regardless of how many mobs are already loaded. This module dynamically reduces spawn attempt frequency under load. - Dynamic tick interval based on current TPS and loaded mob count - Separate frequency reduction per world - Lag-aware: reduces attempts further when TPS is low --- ### 🎲 Random Tick Optimizer Dynamically lowers `randomTickSpeed` when TPS drops, then restores it when the server recovers. Random ticks drive crop growth, leaf decay, fire spread, and similar processes — reducing them under load cuts tick time without players noticing anything in normal gameplay. - Configurable TPS thresholds and corresponding randomTickSpeed values - Per-world overrides - Restores to original value on unload / plugin disable --- ### 🗺 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 per 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 --- ### ⚡ Async Chunk Prefetch Predicts player movement and pre-loads chunks ahead of them asynchronously, so chunks are ready before the player arrives. Prevents the hitches that occur when players sprint into unloaded terrain. - Configurable look-ahead distance and direction prediction window - Only prefetches on Paper/Folia where async chunk loading is safe - Pauses prefetch when TPS is low (configurable threshold) to avoid making lag worse --- ### 📊 Chunk Tick Budget Per-tick time budget for chunk processing. If chunk ticking (random ticks, tile entity updates, entity processing) exceeds the configured budget for the tick, lower-priority chunk processing is deferred to the next tick. - Configurable millisecond budget per tick - Prioritizes chunks with players in them - Tracks budget overage and logs when consistently exceeded --- ### ⚡ Tick Speed Per-world overrides for random tick speed, view distance, simulation distance, and spawn limits — no restart required: ```yaml worlds: resource_world: random_tick_speed: 1 view_distance: 6 spawn_limits: monster: 25 ``` --- ### 📉 View Distance Adjuster Dynamically adjusts per-player view and simulation distance based on current TPS. When the server is healthy, players get their full configured view distance. When TPS drops, it shrinks — less to render, less to tick. - Configurable TPS thresholds → view distance tiers - Per-player adjustment (high-view-distance players are reduced first) - Restores to normal distance when TPS recovers - Permission bypass for staff --- ### 🌀 Portal Limiter Per-player cooldown on portal use. Prevents players from spamming portals to force repeated portal search/creation cycles, which are expensive. - Configurable cooldown per portal type (Nether, End) - Per-permission bypass - Message shown to player when on cooldown --- ### 🔍 Portal Cache Caches portal destination lookups. Vanilla scans a radius around the portal every time a player teleports to find or create the exit portal — an O(radius³) operation on large portals. This module caches the result so subsequent uses skip the scan. - Per-portal-location cache with configurable expiry - Cache invalidated automatically when blocks change in the search area - Works for both Nether and End portals --- ### 🦶 Pathfinding Limiter Tiered distance-based budget for mob pathfinding calculations. Mobs far from players get shorter pathfinding range and simplified goal evaluation, reducing the CPU time spent on mobs that players aren't interacting with. - Three tiers matching Mob AI Throttler's zones (Full / Reduced / Minimal) - Pathfinding node limit per tier (configurable) - Separate settings for hostile vs passive mobs - Works alongside Mob AI Throttler — both can be active at once --- ### 💽 Disk I/O Throttler Rate-limits chunk save operations per tick. When many chunks are dirty simultaneously (after a large explosion, server restart prep, or mass block edits), vanilla can flood the I/O queue and block the main thread. This module spreads saves across ticks. - Configurable max chunk saves per tick - Queue length monitoring — warns to console if queue backs up significantly - Does not delay saves from `/save-all` (treated as high-priority) --- ## 🧑 Player & Network ### 💤 AFK Manager Detects and manages AFK players. - Configurable detection timeout (default: 5 minutes without movement) - Actions on AFK: broadcast message, switch to spectator mode, or kick after extended idle time - Kick timeout separate from AFK detection timeout - Permission bypass (`performancex.bypass.afk`) - EssentialsX AFK API integration — respects Essentials' own AFK state --- ### 🌙 Sleep Manager Configurable sleep voting — players can skip the night without requiring 100% of players to be in bed. - Configurable percentage required (default: 50%) - MiniMessage vote announcement with player count progress - Optional force-skip when a single player is online - `/px sleep vote` — players can vote to skip without getting in bed --- ### 💬 Chat Throttler Sliding-window rate limiter for chat messages and commands. - Separate limits for chat and commands - Configurable window (e.g. max 3 messages per 5 seconds) - Commands can be individually excluded from throttling (e.g. `/msg`, `/r`) - Auto-mute after repeated violations (configurable) - Permission bypass for staff --- ### ⌨ Command Throttler Per-command cooldowns and pattern-based blocking. - Per-command configurable cooldown (e.g. `/home` cooldown 3s, `/warp` cooldown 2s) - Pattern blocking: block commands matching a regex during lag events - Lag-aware: can activate additional cooldowns only when TPS is low - Per-permission bypass --- ### 📡 Packet Limiter Netty-level rate limiter that caps packets per second per connection before they reach the server logic. Protects against clients sending floods of packets (inventory spam, movement spam, etc.) that would otherwise consume main-thread time. - Configurable PPS limit per packet type (movement, inventory, chat, etc.) - Automatic temporary disconnect after sustained violation - Whitelist for trusted IP ranges - All Bukkit API calls dispatched off the Netty thread — no race conditions --- ## 🚨 Lag Response ### 🚨 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, GC hint (advisory) | | 🔴 **Tier 3** | < 10 TPS | Emergency AI freeze, suspend redstone, broadcast warning, optional auto-restart | **Hysteresis guard:** requires sustained lag before triggering — no flapping on a single spike. **Auto-recovery:** all throttles revert when TPS holds above the threshold for 3 consecutive checks. **14 available actions per tier:** `clear_items`, `clear_mobs`, `clear_entities`, `gc` (advisory JVM hint), `throttle_spawns`, `throttle_redstone`, `throttle_hoppers`, `throttle_mob_ai`, `disable_collisions`, `unload_stale_chunks`, `broadcast`, `run_command`, `kill_phantoms`, `schedule_restart` --- ### 🛡 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`, `throttle`, `freeze`, `remove_and_warn`, or `kick`. Admin alert and Discord webhook on every detection. --- ## 📊 Performance Tools ### 📊 Performance Monitor Live 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 - **Chunk gen** — how many chunks per second your hardware can generate Produces a report with bottleneck identification and estimated concurrent player capacity. Runs fully async — main tick is never blocked. `/px benchmark` · `/px speedtest disk` · `/px speedtest network` · `/px speedtest tps` · `/px speedtest chunkgen` --- ### 🔎 Profiler Built-in tick timing profiler. Samples each plugin's event listener and task contribution to tick time over a configurable window, then produces a ranked report. - `/px profiler start [seconds]` — run a timed sample - `/px profiler report` — view ranked results - Identifies which plugins are consuming the most tick time without requiring external tools - Safe to run live — adds minimal overhead during sampling --- ### 📺 Performance Display Holographic server stats display that can be placed anywhere in the world. Shows live TPS, MSPT, RAM, player count, entities, and chunks — updated every second. - MiniMessage formatting with per-line color coding (green/yellow/red based on health) - Supports TextDisplay entities on 1.19.4+ and ArmorStands on older versions - FancyHolograms integration — uses it as the render backend automatically if installed - `/px display place` · `/px display remove` · `/px display list` - Multiple displays supported — place one in your lobby, one in your hub, etc. --- ### 🔬 GC Pressure Monitor Monitors JVM garbage collection activity and logs or alerts when GC pause time is excessive. Separate from the GC Hint module — this one only watches, it does not trigger collection. - Tracks GC pause duration and frequency via JMX GarbageCollectorMXBean - Configurable warning threshold (e.g. warn if GC pauses exceed 500ms in a 10s window) - Discord webhook alert on sustained GC pressure - Logs to console with GC type (minor/major) and duration --- ## 🖥 Server Health ### 🖥 CPU Stabilizer Crash guardian and watchdog for servers experiencing plugin crashes or tick hangs. - Detects crash-looping plugins and auto-disables them before they halt the server - Main-thread watchdog monitors tick latency and logs a full thread dump before a freeze becomes an unresponsive server - Optional advisory GC hint on sustained CPU load — see GC Hint module note below, the same advisory applies --- ### 🧮 GC Hint (formerly RAM Optimizer) Sends an advisory `System.gc()` hint to the JVM when heap usage exceeds a configured threshold (default: 85%), or on a fixed schedule. > **Advisory only:** `System.gc()` is a hint — the JVM is free to ignore it entirely. Modern GC implementations (G1GC, ZGC, Shenandoah) already manage garbage collection without hints. This module may help on servers where long-lived garbage accumulates slowly, but has no effect on servers running `-XX:+DisableExplicitGC` (common on shared hosts). For G1GC, pair with `-XX:+ExplicitGCInvokesConcurrent` to avoid stop-the-world pauses. **Disabled by default.** --- ## 🗺 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 and display ``` /px pregen start survival 5000 circle /px pregen pause | resume | cancel | status ``` --- ## 💾 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, 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 (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 --- ## 🔁 Auto Restart Scheduled server restarts with countdown warnings: - Schedule: `"at 4:00"` · `"every 12h"` · multiple times per day - 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 any active backup finishes --- ## 🛠 Auto Config Server category wizard that generates an optimized config on first install. On startup, if no config exists, it asks through console (or runs silently with a default profile) and generates module settings appropriate for your server type. **Categories:** Survival SMP, Creative, Minigame, Factions/PvP, Skyblock, Network Hub Pre-configured tuning per category — mob caps, AI throttle zones, item timers, farm limits, and chunk settings all adjusted to match what each server type actually needs. You can still override everything after. --- ## 🔄 Auto Updater Checks Modrinth for new PerformanceX releases and stages updates automatically. How it works: 1. Every configurable interval (default: 1 hour), Modrinth API is queried asynchronously 2. If a newer version is found and `auto_download` is enabled, the JAR is downloaded, SHA-1 verified, and placed in `plugins/update/` 3. Bukkit/Paper moves `plugins/update/` files to `plugins/` on restart — no manual file management The running JAR is never touched while the server is live. Updates only take effect after a restart. Operators get notified on join when an update is staged. `/px update status` · `/px update check` · `/px update apply` --- ## 📋 Block Logger

CoreProtect-style activity logging with no external dependencies. Built-in SQLite database. MySQL supported. CoreProtect database passthrough when both are present — share one DB and 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 ``` 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 on failure. Multi-endpoint support — send different events to different channels. **Discord setup:** Paste your webhook URL → `/px reload` → done. --- ## 💬 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 handles this 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 | | **StackMob** | Stack counts fed to mob limiter and AI throttler | | **ItemsAdder** | Per-custom-item despawn keys | | **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 | | **FancyHolograms** | Used as render backend for Performance Display | --- ## 📊 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 ` | Enable a module live (no restart) | | `/px disable ` | 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 \ \| world]` | Clear ground items | | `/px clearmobs [here \ \| world]` | Clear mobs | | `/px merge` | Trigger manual item merge sweep | | `/px entities [world]` | Clear excess entities | | `/px timer item ` | Set despawn timer for item type | | `/px timer mob ` | Set despawn timer for mob type | ### Module Controls | Command | Description | |:--------|:------------| | `/px mobai ` | 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 | | `/px profiler ` | Tick profiler | | `/px display ` | Performance Display hologram | | `/px sleep vote` | Vote to skip the night | | `/px afk` | View AFK players | ### World & Server | Command | Description | |:--------|:------------| | `/px pregen ` | World pre-generation | | `/px backup [now]` | Trigger manual backup | | `/px restart [cancel]` | Trigger or cancel restart | | `/px geyser ` | Geyser support and Bedrock player list | | `/px update ` | Auto-updater controls | ### Diagnostics & Logging | Command | Description | |:--------|:------------| | `/px log ` | Block logger queries | | `/px benchmark [run\|quick\|results]` | Hardware benchmark | | `/px speedtest ` | Diagnostic speed probes | | `/px webhook ` | 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 | | `performancex.bypass.afk` | false | | `performancex.bypass.chat` | false | Every subcommand also has `performancex.command.` (default: op). --- ## Configuration

PerformanceX uses a simple three-file pattern: 1. **`config.yml`** — master module toggles 2. **`modules/.yml`** — per-module settings, generated with full comments 3. **`worlds/.yml`** — per-world overrides for any module setting 4. **`/px reload [module]`** — apply changes instantly, no restart ```yaml # config.yml — enable/disable modules 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 # ... 57 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 are 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/.yml` 5. Run `/px reload` — changes apply instantly Defaults are tuned for survival multiplayer. Most servers need zero configuration changes to get started. --- ## Discord **Join our Discord for support, feedback, and plugin integration requests.** **[protectcord.com/discord](https://protectcord.com/discord)** - Need help configuring something? Ask in support - Want an integration we don't have yet? Request it - Found a bug or have a suggestion? Let us know --- ## Statistics [![bStats](https://bstats.org/signatures/bukkit/PerformanceX.svg)](https://bstats.org/plugin/bukkit/PerformanceX/30806) --- **Built by [SneakyWrld](https://protectcord.com) · [Discord](https://protectcord.com/discord)**

PerformanceX

Compatibility

Minecraft: Java Edition

Platforms

Supported environments

Tags

Creators

Details