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).

Full Command Reference — click to expand

Core

Command	Description
`/px status`	One-screen server health overview
`/px monitor`	Live TPS / MSPT / heap / entity dashboard
`/px modules`	List all modules with enabled/error state
`/px enable <module>`	Enable a module live (no restart)
`/px disable <module>`	Disable a module live
`/px reload [module]`	Reload all configs or one module
`/px version`	Plugin version and platform info

Item & Mob Management

Command	Description
`/px clear [here \<r\> \| world]`	Clear ground items
`/px clearmobs [here \<r\> \| world]`	Clear mobs
`/px merge`	Trigger manual item merge sweep
`/px entities [world]`	Clear excess entities
`/px timer item <type> <seconds>`	Set despawn timer for item type
`/px timer mob <type> <seconds>`	Set despawn timer for mob type

Module Controls

Command	Description
`/px mobai <info\|stats\|shrink\|restore>`	AI throttler controls
`/px lagactions`	Lag action system status
`/px lagmachine`	Lag machine detection stats
`/px redstone`	Redstone limiter status
`/px hoppers`	Hopper limiter status
`/px chunks [world]`	Chunk manager info
`/px tickspeed`	Per-world tick settings
`/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

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
`/px update <status\|check\|apply>`	Auto-updater controls

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

Quick Start

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

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

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

Built by SneakyWrld · Discord

PerformanceX

Compatibility

Minecraft: Java Edition

Platforms

Supported environments

Tags

Creators

Details

PerformanceX

What is PerformanceX?

Module Overview

⏱ Item Despawn

💎 Item Rarity

🧹 Item Clear

⊕ Item Merge

🔄 Drop Merge

🐾 Mob Management

🕐 Mob Despawn

🗑 Mob Clear

🧠 Mob AI Throttler

🐣 Spawn Limiter

📚 Mob Stacker

🚮 Entity Culling

🐔 Mob Griefing Optimizer

🐄 Breeding Throttler

🏘 Villager Optimizer

📐 Entity & Physics Caps

📋 Entity Limiter

⏱ Entity Tick Budget

💥 Collision Limiter

🏹 Projectile Limiter

💣 Explosion Optimizer

🪨 Physics Limiter

🖼 Item Frame Optimizer

🌍 World & Tick Control

⚡ Redstone Limiter

🔄 Hopper Limiter

⚙ Farm Limiter

🔩 Piston Limiter

🌊 Fluid Flow Limiter

🍃 Leaf Decay Optimizer

🔥 Tile Entity Throttler

🌱 Spawn Tick Optimizer

🎲 Random Tick Optimizer

🗺 Chunk Manager

⚡ Async Chunk Prefetch

📊 Chunk Tick Budget

⚡ Tick Speed

📉 View Distance Adjuster

🌀 Portal Limiter

🔍 Portal Cache

🦶 Pathfinding Limiter

💽 Disk I/O Throttler

🧑 Player & Network

💤 AFK Manager

🌙 Sleep Manager

💬 Chat Throttler

⌨ Command Throttler

📡 Packet Limiter

🚨 Lag Response

🚨 Lag Actions — 3-Tier Auto-Response

🛡 Anti-Lag Machine

📊 Performance Tools

📊 Performance Monitor

🔬 Benchmark & Speed Test

🔎 Profiler

📺 Performance Display

🔬 GC Pressure Monitor

🖥 Server Health

🖥 CPU Stabilizer

🧮 GC Hint (formerly RAM Optimizer)

🗺 World Pre-Generation

💾 Auto Backup

🔁 Auto Restart

🛠 Auto Config

🔄 Auto Updater

📋 Block Logger

🔔 Webhooks

💬 Notifications

📡 Status Module