PerformanceX

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

Folia  · Forge  ·  Paper  ·  Spigot  ·  Purpur  ·  MC 1.8.8 — 26.2  ·  Java 8+

---

What is PerformanceX?

PerformanceX is a modular server performance suite — 29 independent modules that replace a dozen separate plugins with a single, zero-dependency JAR. Every module is self-contained: enable what you need, disable what you don't. No module depends on another. No restarts required to toggle anything.

It ships with smart defaults that work immediately on most servers. If a ClearLagg replacement is all you need, two modules and you're done. If you want AI throttling, lag machine detection, automatic backups, block logging, and Discord webhooks — it does all of that too. If you are genuinely struggling with LAG on your server! Just throw performancex on there and it should do the job without you needing to configure it. It does the job for most communities out there as it's designed around Survival servers by default. Configure it to your hearts content. It's powerful and does exactly what most servers NEED! Completely free!

Drop it in. Run /px status. You're done.

---

⏱ Item Despawn — The Headline Feature

Per-item-type configurable despawn timers with a floating countdown label hovering above every dropped item in real-time. The label shows item name, stack count, and time remaining.

Four rarity tiers come pre-configured:

Tier	Duration	Examples
🟣 Legendary	Never	Nether Star, Elytra, Dragon Egg, Totem of Undying
🟠 Epic	30 min	Diamond, Emerald, Trident, Ancient Debris, Netherite Ingot
🟡 Valuable	10 min	Iron Ingot, Gold Ingot, Blaze Rod, Ender Pearl
⬜ Junk	60 sec	Cobblestone, Dirt, Rotten Flesh, Gravel, Logs

Everything else uses the default 5-minute timer. Every timer is configurable per item type, per world, and per integration.

Label rendering — picks the best automatically:

• text_display — native TextDisplay entities (MC 1.19.4+, cleanest)
• armor_stand — invisible ArmorStand fallback, works back to 1.8.8
• custom_name — item entity nametag, zero extra entities
• auto — selects best option for your server version at startup

Label format is fully MiniMessage-customizable:

label_format: "<white><name> <gray>x<yellow><count> <gray>| <gold><time>"
renderer: auto   # text_display → armor_stand → custom_name

Smart integrations:

• Timer resets when RoseStacker/StackMob stack size changes
• Per-world duration overrides (resource world = 30s, End = 10m)
• Labels auto-hide when no player is in range (bandwidth savings)
• Per-custom-item keys for ItemsAdder, DropHeads, ArmoredElytra, TreeFeller, Veinminer

---

🧹 Item Clear — ClearLagg Replacement

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

schedule: "every 15m"
warnings: ["5m", "1m", "30s", "10s", "5s"]
include: ["minecraft:*"]
exclude:
  - "minecraft:nether_star"
  - "minecraft:diamond"
  - "itemsadder:*"

• Per-type include/exclude with wildcards (minecraft:netherite_*)
• Lands-claim awareness — items inside claimed land are never cleared
• Bypass-permission proximity guards — items near staff are protected
• /px clear · /px clear here 64 · /px clear world

---

⊕ Item Merge

Actively merges nearby identical ground items into stacks on a configurable sweep interval. Vanilla only merges at spawn — this catches items that land apart and wouldn't otherwise combine.

• Configurable merge radius (default: 8 blocks, cross-chunk)
• Respects max stack sizes per item type
• Blacklist specific materials (enchanted books, etc.)
• Players get every item — there are just fewer ground entities

---

🕐 Mob Despawn

Per-mob-type despawn timers with smart skip rules that protect every mob that matters:

• Named mobs (nametag or plugin), tamed animals, leashed mobs
• Mobs in vehicles, carrying passengers, or with the vanilla persistent flag
• SafariNet captures, Lands-claimed mobs

minecraft:phantom:    90     # Annoying — fast despawn
minecraft:zombie:     300    # Standard hostile
minecraft:pillager:   600    # Longer — looting opportunity

---

🗑 Mob Clear

Hard caps per chunk by mob family with intelligent culling:

Family	Default Cap/Chunk
Hostile	8
Passive	10
Ambient	4
Water	8

Shares skip rules with Mob Despawn — a protected mob is never cleared.

---

🧠 Mob AI Throttler — 30-50% TPS Savings

Mob AI accounts for 30-50% of server tick time. This module disables AI for mobs far from players using three configurable distance zones:

Zone	Range	Behavior
🟠 Full AI	0 – 32 blocks	Normal pathfinding, attacking, wandering
🟡 Reduced AI	32 – 48 blocks	Walk goals only, look/attack disabled
🔴 No AI	48 – 64 blocks	Completely frozen, zero AI overhead

Per-family overrides — tune hostile, passive, villager, and boss ranges independently.

Lag-aware mode: When TPS drops below 16.0, all ranges automatically shrink — more mobs freeze, server recovers. Zones restore when TPS recovers.

Always exempt: Named, tamed, leashed, and boss mobs (Wither, Ender Dragon) always have full AI regardless of distance.

---

🐾 Spawn Limiter

Per-chunk spawn budgets — prevents mob accumulation before it starts instead of cleaning up after. Works best paired with Mob Clear and Mob Despawn for a complete mob lifecycle.

---

📦 Entity Limiter

Per-chunk or per-world caps for non-mob entities:

Type	Default Cap
Projectiles (arrows, tridents)	50 (stuck/aged > 5s only)
XP Orbs	100 (supports merge-instead-of-delete)
Boats / Minecarts	20 each
Item Frames / Paintings	100 / 50
Falling Blocks	30
Primed TNT	20
Armor Stands	50 (ArmorStandTools-protected skipped)

XP Orb Merging: Nearby orbs merge into one with the combined value. Players get all XP — there are just fewer entities.

---

💥 Collision Limiter

Disables entity-entity collision checks for configurable types. Collision scales O(n²) — reducing it dramatically helps crowded areas.

• Always disabled: Armor Stands, Item Frames, Dropped Items, Projectiles
• Lag-aware: When TPS < 16.0, disables ALL mob-to-mob collisions automatically

---

⚡ Redstone Limiter

Detects and throttles redstone clocks and high-frequency circuits in three modes:

Mode	Behavior
Monitor	Log to console only, no interference
Throttle	Limit pulses per second (default)
Disable	Cancel all events in configured worlds

Lag-aware escalation: automatically steps from monitor → throttle → disable as TPS drops, and reverts when it recovers.

---

🔄 Hopper Limiter

Runs at vanilla speed by default — only activates under lag:

• Normal: 8-tick transfer interval (vanilla)
• During lag (TPS < 17.0): 24-tick interval
• Sorting systems still work — they just temporarily back up

---

⚙ Farm Limiter

Throttles the root causes of item and entity floods:

Target	Default
Spawner min interval	20s, max 10 mobs near spawner
Crop growth	15% slower (85% pass rate)
Fast crops (bamboo, cactus, kelp)	35-50% slower
Breeding cooldown	10 minutes
Chicken egg laying	25% chance
Item spawn cap	64 items/chunk/sec (valuables exempt)

---

🛡 Anti-Lag Machine

Detects and stops four types of lag machines before they crash your server:

Detection	Threshold	Default Response
Piston Clock	> 20 fires/sec per location	Throttle + 30s suppression
Fluid Cascade	> 500 flow events/tick	Freeze fluid spread in chunk
Falling Block Launcher	> 50 entities/chunk/sec	Cancel entity spawns
TNT Duper	> 20 primed TNT/chunk	Remove entities + warn player

Per-detection response modes: log (monitor only), throttle, freeze, remove_and_warn, or kick. Admin alert + Discord webhook on every detection.

---

🔥 Tile Entity Throttler

Pauses furnace/smoker/blast furnace ticking for blocks far from players. Saves burn state, pauses progress, resumes automatically when a player approaches. No items are lost.

• Beacons and conduits also throttled when distant
• Empty containers auto-skipped (nothing to process)

---

🌍 Chunk Manager

Fewer loaded chunks = fewer entities to tick, fewer tile entities, less memory.

• Stale unloading: Chunks 8+ chunks from any player unloaded after a 30s grace period
• Load rate limiting: Max 4 loads/tick — prevents lag spikes from fast travel
• Hard per-world caps — optional, for memory-constrained servers
• Spawn chunks and Lands-claimed chunks protected from unloading

---

⚡ Tick Speed

Per-world overrides for random tick speed, view distance, simulation distance, and spawn limits — no restart required:

worlds:
  resource_world:
    random_tick_speed: 1    # Slower growth = less lag
    view_distance: 6
    spawn_limits:
      monster: 25

---

🚨 Lag Actions — 3-Tier Auto-Response

Multi-tier automatic lag response that escalates as TPS drops — and fully reverts when it recovers.

Tier	TPS Threshold	Actions
🟡 Tier 1	< 18 TPS	Notify players, shrink AI zones by 25%, throttle hoppers
🟠 Tier 2	< 15 TPS	Clear items, cull mobs, suspend farms, force GC
🔴 Tier 3	< 10 TPS	Emergency AI freeze, suspend redstone, broadcast warning, optional auto-restart

Hysteresis guard: Requires sustained lag (configurable window) before triggering — no flapping on one-tick spikes. Auto-recovery: All throttles revert when TPS recovers above the threshold for 3 consecutive checks.

14 available actions per tier: clear_items, clear_mobs, clear_entities, gc, throttle_spawns, throttle_redstone, throttle_hoppers, throttle_mob_ai, disable_collisions, unload_stale_chunks, broadcast, run_command, kill_phantoms, schedule_restart

---

📊 Performance Monitor

Live dashboard via /px monitor:

• TPS — 1m, 5m, 15m rolling averages
• MSPT — milliseconds per tick (out of 50ms budget)
• Heap — JVM memory (used / max)
• Entities — total loaded across all worlds
• Chunks — total loaded chunk count
• Per-world breakdown — chunks, entities, players, MSPT per world

Uses Paper's native tick APIs. On Spigot: built-in tick sampler provides equivalent data.

---

🔬 Benchmark & Speed Test

Hardware stress test measuring your server's real capacity:

• CPU — single-thread and multi-thread burn
• RAM — sequential write/read throughput
• Disk — read/write speed
• Network — download/upload via Cloudflare

Produces analysis with estimated max concurrent players, bottleneck identification, and hardware recommendations. Runs fully async — main tick never blocked.

/px benchmark · /px speedtest disk · /px speedtest network · /px speedtest tps

---

🗺 World Pre-Generation

Async chunk pre-generation so players never hit generation lag:

• Shapes: square, circle, diamond
• Parallel async generation on Paper — up to your CPU core count
• World border auto-detection — /px pregen start world reads your vanilla border
• Auto-pause when players join, auto-resume when empty or TPS recovers
• Restart-persistent — jobs survive restarts, resume from checkpoint
• Terra and Iris generator detection + display

/px pregen start survival 5000 circle
/px pregen pause | resume | cancel | status

---

🧮 RAM Optimizer

Threshold-based and scheduled JVM garbage collection:

• Trigger GC when heap exceeds a configured percentage (default: 80%)
• Scheduled GC at quiet times (e.g., "at 4:00")
• Lag Actions integration — GC fires automatically at T2+

---

🖥 CPU Stabilizer

Crash guardian + watchdog:

• Detects runaway threads and unresponsive tick loops
• Configurable restart on sustained CPU overload
• Watchdog thread monitors main-tick latency, alerts before a freeze becomes a crash

---

💾 Auto Backup

Scheduled world backups to 5 storage backends simultaneously:

Backend	Examples
AWS S3	S3, Backblaze B2, Cloudflare R2, MinIO, Wasabi
SFTP	Any SSH server with key or password auth
rclone	Google Drive, Dropbox, OneDrive, Mega, 70+ more
WebDAV	Nextcloud, ownCloud, any WebDAV server
Local	Filesystem path or NFS mount

Compression: ZIP · GZIP · ZSTD (configurable level 0-9) Retention: Keep last N backups per backend Schedule: "every 6h" · "at 2:00,14:00" · manual /px backup now Safety: Pre-backup /save-all, async upload (zero main-thread impact), restart-safe coordination Notifications: Discord webhook on start, complete, and failure

---

📋 Block Logger

CoreProtect-style activity logging — zero external dependencies. Built-in SQLite database. MySQL supported. CoreProtect database passthrough when present (share one DB, one query tool).

Tracked events: Block Place · Block Break · Container Interaction · Explosion · Piston Push · Fluid Flow · Sign Edit · Entity Kill

/px log lookup x:100 y:64 z:200 r:10 t:1h
/px log lookup player:Steve t:7d a:break
/px log rollback player:Steve r:20 t:7d
/px log restore player:Steve r:20 t:7d
/px log purge 90
/px log status

Performance: All writes are async-queued and batch-flushed every 2 seconds. Auto-purges entries older than 30 days (configurable). World blacklist for creative/minigame worlds.

---

🔔 Webhooks

Real-time notifications for 20 event types to Discord, Slack, or any HTTP endpoint:

Category	Events
Server	server_start, server_stop, restart_warning, restart
Performance	tps_drop, tps_recover, lag_action_tier_change, lag_machine_detected
Backups	backup_started, backup_complete, backup_failed
Cleanup	item_clear, mob_clear
Players	player_join, player_quit, player_death, first_join
World	pregen_start, pregen_complete, pregen_pause, log_shipped

Per-event title, color, description, and @mention override. Rate-limited for Discord compliance. Automatic retries (3 attempts, 5s delay). Multi-endpoint support.

Discord setup: Paste your webhook URL → /px reload → done.

---

🔁 Auto Restart

Scheduled server restarts with countdown warnings:

• Schedule: "at 4:00" (daily) · "every 12h" · multiple times
• Configurable warning intervals: 30m, 15m, 5m, 1m, 30s, 10s, 5s
• Minimum uptime guard prevents boot loops
• Cancel if admin is online (optional)
• Backup coordination — delays restart until active backup finishes

---

💬 Notifications

Unified notification routing for player-facing messages:

• Channels: Chat · Actionbar · Title · Boss Bar · Discord webhook
• Events: Item clear countdown · Mob clear · Restart countdown · Lag alerts
• Per-player opt-out: /px notify off
• MiniMessage formatting throughout — full RGB, gradients, click/hover

---

📡 Status Module

One-screen server health overview at /px status — TPS, MSPT, heap, entity counts, loaded chunks, module states, active lag actions, next backup, next restart. Everything you need to assess server health at a glance.

---

📤 Log Shipping

Ships health snapshots and performance logs to a remote HTTP endpoint on a configurable schedule. Useful for off-site monitoring dashboards or centralized multi-server observability.

---

📱 Geyser Support — Bedrock Compatibility

Bedrock players on GeyserMC crash on entities that Java handles fine. PerformanceX fixes that — without affecting Java players at all.

Problem	Fix
TextDisplay entities crash Bedrock	Auto-fallback to ArmorStand renderer for Bedrock players
Label Y-offset wrong on Bedrock	+0.4y correction applied per-player
MiniMessage components unsupported	Stripped to legacy format for Bedrock targets
Actionbar clears too fast on Bedrock	Send rate doubled to maintain persistence
Too many entities freeze Bedrock renderer	Per-player entity cap (200, furthest hidden first)

Detection chain: Geyser API → Floodgate API → UUID heuristic. No hard dependency on either.

---

🌐 16 Integrations

Auto-detected at startup — no configuration required:

Plugin	Integration
RoseStacker	Timer resets on stack size change — the original bug fix
StackMob	Stack counts fed to mob limiter and AI throttler
ItemsAdder	Per-custom-item despawn keys (itemsadder:myset:myitem)
DropHeads	Per-player-head despawn overrides
SafariNet	Released mobs protected from despawn and clear
Lands	Items/mobs inside claims protected from clearing
WorldGuard	Region-aware item/mob clear — protected zones skipped
PlaceholderAPI	14+ placeholders for scoreboards, TAB, etc.
LuckPerms	Per-world/per-group bypass for timers and clear
Vault	Economy-aware clear exemptions for premium ranks
EssentialsX	AFK detection — extended timers near AFK players
MythicMobs	Boss mobs excluded from AI throttle and despawn
Citizens	NPCs bypass all mob management modules
Dynmap / BlueMap	Lag event markers and chunk MSPT heatmaps
Folia	Full region-aware scheduler support — all modules
ProtocolLib	Enhanced packet-level label renderer (optional)

---

📊 PlaceholderAPI Placeholders

Placeholder	Value
%performancex_tps%	Current TPS
%performancex_tps_1m%	1-minute TPS average
%performancex_mspt%	Milliseconds per tick
%performancex_entities%	Total loaded entities
%performancex_chunks%	Total loaded chunks
%performancex_tracked_items%	Items with active despawn timers
%performancex_next_clear%	Time until next scheduled clear
%performancex_ai_disabled%	Mobs with AI fully disabled
%performancex_lag_machines%	Total lag machine detections
%performancex_pregen_progress%	Pre-gen progress percentage

---

Commands

All commands use /px (aliases: /performancex, /perfx).

Full Command Reference — click to expand

Core

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

Item & Mob Management

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

Module Controls

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

World & Server

Command	Description
/px pregen <start|pause|resume|cancel|status>	World pre-generation
/px backup [now]	Trigger manual backup
/px restart [cancel]	Trigger or cancel restart
/px geyser <info|list>	Geyser support and Bedrock player list

Diagnostics & Logging

Command	Description
/px log <lookup|rollback|restore|purge|status>	Block logger queries
/px benchmark [run|quick|results]	Hardware benchmark
/px speedtest <disk|network|tps|chunkgen>	Diagnostic speed probes
/px webhook <test|list>	Webhook management
/px notify [on|off]	Toggle personal notifications

---

Permissions

Permission	Default
performancex.admin	op
performancex.notifications	everyone
performancex.bypass.itemdespawn	false
performancex.bypass.itemclear	false

Every subcommand also has performancex.command.<name> (default: op).

---

Configuration

PerformanceX uses a simple three-file pattern:

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

# config.yml — flip the switches
modules:
  item-despawn: true
  item-clear: true
  mob-ai-throttler: true
  lag-actions: true
  auto-backup: true
  webhooks: true
  geyser-support: true
  block-logger: false   # disabled by default
  # ... 21 more

---

Platform Support

Platform	Versions	Notes
Paper	1.8.8 — 1.21.x	Full support — recommended
Folia	1.19.4+	Full region-aware scheduling
Purpur	1.16+	Full support
Spigot	1.8.8 — 1.21.x	Full support with built-in tick sampler

Platform-specific APIs auto-selected at startup. Java 8+ bytecode — compatible with Java 8 through 21+.

---

Quick Start

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

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

---

Statistics

---

Built by ProtectCord