Description

PerformanceX

Server performance, all in one plugin.

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

⏱ 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:

label_format: "<white><name> <gray>x<yellow><count> <gray>| <gold><time>" 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.

tiers: legendary: label_frames: - "<gradient:#FFD700:#FF6B00>◆</gradient> <white><name> x<count> │ <gold><time>" particle: type: "END_ROD" interval_ticks: 3

🧹 Item Clear

Scheduled and on-demand item removal that won't touch your valuables.

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.

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:

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 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:

Every configurable interval (default: 1 hour), Modrinth API is queried asynchronously
If a newer version is found and auto_download is enabled, the JAR is downloaded, SHA-1 verified, and placed in plugins/update/
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).

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 /px profiler <start|report|stop> Tick profiler /px display <place|remove|list> Performance Display hologram /px sleep vote Vote to skip the night /px afk View AFK players

World & Server

Diagnostics & Logging

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.<name> (default: op).

Configuration

PerformanceX uses a simple three-file pattern:

config.yml — master module toggles
modules/<name>.yml — per-module settings, generated with full comments
worlds/<world>.yml — per-world overrides for any module setting
/px reload [module] — apply changes instantly, no restart

# 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+.