PerformanceX

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

29 modules. 16 integrations. Zero dependencies. One plugin.

Folia | Paper | Spigot | MC 1.8.8 — 1.21.x

---

What is PerformanceX?

PerformanceX is a modular server performance suite that replaces a dozen separate plugins with a single, lightweight JAR. Every module is self-contained — enable what you need, disable what you don't. No module depends on another, and toggling any module on or off never requires a restart.

It ships with smart defaults that work out of the box on most servers, but every single value is configurable down to per-mob-type, per-item-type, and per-world granularity. If a ClearLagg-style plugin is all you need, enable two modules and you're done. If you want a full performance overhaul with AI throttling, lag machine detection, automatic backups, and Discord webhooks — it does that too.

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

---

---

Item Management

Item Despawn — The Headline Feature

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

This is the module that solves the original problem: RoseStacker stack updates no longer break despawn timers. When a stack grows, the timer resets automatically.

Four rarity tiers come pre-configured out of the box:

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

Everything else uses the default of 5 minutes. Every timer is fully configurable per item type, per world, and per plugin integration.

Label rendering options:

• text_display — cleanest look, uses TextDisplay entities (MC 1.19.4+)
• armor_stand — invisible armor stand fallback, works on 1.8.8+
• custom_name — uses the item's built-in nametag, zero extra entities
• auto — picks the best option for your server version

Label format is fully customizable with MiniMessage:

format: "<white><name> <gray>x<yellow><count> <gray>| <gold><time>"

Smart features:

• Labels auto-hide when no player is within range (saves bandwidth)
• Timer resets on stack merge (vanilla) and RoseStacker size changes
• Per-world duration overrides (e.g., resource worlds = 30s, The End = 10m)
• Bypass permission: performancex.bypass.itemdespawn
• Full integration with ItemsAdder, DropHeads, FancyWaystones, ArmoredElytra, TreeFeller, and Veinminer for per-custom-item type keys

---

Item Clear — ClearLagg Replacement

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

Unlike ClearLagg, PerformanceX's item clear has:

• Per-type include/exclude lists with wildcard patterns (minecraft:netherite_*)
• Lands-claim awareness — items inside claimed areas are never cleared
• Bypass-permission proximity guards — items near staff are protected
• Configurable countdown warnings via actionbar, title, or chat

schedule: "every 15m"          # or "at 0:00,12:00" for specific times
warnings: ["5m", "1m", "30s", "10s", "5s"]

# Items matching include AND NOT matching exclude are removed
include: ["minecraft:*"]
exclude:
  - "minecraft:nether_star"    # Legendary items never cleared
  - "minecraft:diamond"        # Rare items never cleared
  - "itemsadder:*"             # All custom items protected
  - "dropheads:*"              # Player heads protected

Commands:

• /px clear — clear all eligible items server-wide
• /px clear here 64 — clear within 64 blocks of you
• /px clear world — clear the current world only

---

Item Merge

Actively merges nearby identical dropped items on the ground into stacks. Unlike vanilla's merge event (which only fires on spawn), this module periodically scans and combines items that vanilla wouldn't merge because they spawned too far apart or at different times.

• Configurable merge radius (default: 8 blocks, cross-chunk)
• Respects natural max stack sizes — ender pearls cap at 16, not 64
• Blacklist materials that shouldn't be merged (enchanted books, etc.)
• Sweep interval tuning — 10 seconds default, adjustable

Players still get every item. There are just fewer entities on the ground.

---

Mob Management

Mob Despawn

Per-mob-type despawn timers with smart skip rules that protect the mobs players care about. Only mobs from natural spawning are tracked — spawner mobs, egg-placed mobs, and plugin-spawned mobs are left completely alone.

Skip rules guarantee permanent mobs are never removed:

• Named mobs (nametag or plugin)
• Tamed animals (wolves, cats, horses)
• Leashed mobs
• Mobs in vehicles or carrying passengers
• Mobs with the vanilla persistent flag
• SafariNet captures, Lands-claimed mobs, ArmorStandTools stands

Per-type overrides:

minecraft:phantom:    90s     # Annoying — despawn fast
minecraft:vex:        60s     # Very annoying
minecraft:zombie:     300s    # Standard hostiles
minecraft:pillager:   600s    # Raid mobs — longer for looting

---

Mob Clear

Hard mob caps per chunk or per world with intelligent culling by mob family:

Family	Default Cap/Chunk	Examples
Hostile	8	Zombies, Skeletons, Creepers
Passive	10	Cows, Sheep, Pigs, Villagers
Ambient	4	Bats
Water	8	Fish, Dolphins, Squid
Misc	16	Armor Stands, Item Frames

Shares skip rules with Mob Despawn — a mob protected from despawning is also protected from clearing. Works best paired with Mob Despawn and Spawn Limiter for a complete mob lifecycle solution.

---

Mob AI Throttler — 30-50% TPS Savings

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

Zone	Range	Behavior
Full AI	0-32 blocks	Normal — pathfinding, attacking, wandering
Reduced AI	32-48 blocks	AI ticks every 4th sweep cycle (75% savings)
No AI	48-64 blocks	Completely frozen — zero AI overhead

Per-family overrides let you tune each mob type independently:

• Hostile mobs: shorter range (they're dangerous, keep AI closer)
• Passive mobs: wider range (less important, save more CPU)
• Villagers: largest range (trades need to work from further away)

Lag-aware mode: When TPS drops below 16.0, all ranges automatically shrink by 40%. Mobs need to be much closer to keep their AI — a massive automatic performance gain when the server needs it most.

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

---

Spawn Limiter

Per-chunk spawn budgets and per-world entity caps. Prevents mob accumulation before it starts instead of cleaning up after. A proactive complement to Mob Clear and Mob Despawn.

Farm Limiter

Throttles the root causes of item and entity floods from automated farms:

Target	What it does	Default
Spawner rates	Min interval between spawns + mob count cap near spawner	20s, max 10 mobs
Crop growth	Random skip chance per growth tick	85% pass rate (15% slower)
Fast crops	Tighter throttle for bamboo, cactus, sugar cane, kelp	50-65% pass rate
Breeding	Extended cooldown beyond vanilla's 5 minutes	10 min cooldown
Egg laying	Random cancel of chicken egg spawns	75% chance
Item flood	Per-chunk-per-second item spawn cap	64 items/chunk/sec

Valuable items (Diamond, Emerald, Netherite, etc.) are never affected by the item flood cap.

---

Entity Control

Entity Limiter

Per-chunk or per-world caps for every non-item, non-mob entity type:

Entity Group	Default Cap	Notes
Projectiles (arrows, tridents)	50	Only counts stuck/aged projectiles (>5s)
XP Orbs	100	Supports merge-instead-of-delete
Boats	20	All wood types
Minecarts	20	All variants (chest, hopper, TNT)
Item Frames	100	Including glow item frames
Paintings	50
Falling Blocks	30	Sand, gravel, anvils, concrete
TNT	20	Primed TNT entities
Armor Stands	50	ArmorStandTools-protected are skipped

XP Orb Merging: Instead of deleting XP orbs, merge nearby orbs into a single orb with the combined value. Players still get their XP — there are just fewer entities. Configurable merge radius (3 blocks), max value per orb (10,000), and toggle for every-sweep vs lazy-mode merging.

Per-projectile-type toggles: Disable counting for ghast fireballs (intentional gameplay) and wither skulls (boss fight) while still capping arrows and snowballs.

---

Redstone, Hoppers & Machines

Redstone Limiter

Detects and throttles redstone clocks and high-frequency circuits. Three operating modes:

Mode	Behavior
Monitor	Log offending locations to console, don't interfere
Throttle	Limit pulses per second at clock locations (default)
Disable	Cancel all redstone events in configured worlds

Clock detection: A location firing more than 15 pulses/second is identified as a clock. Detected clocks are suppressed for 30 seconds before re-evaluation.

Lag-aware escalation: Automatically steps up from monitor to throttle to disable when TPS drops below 16.0 — and reverts when TPS recovers.

Hopper Limiter

Throttles hopper transfer rates. Runs at vanilla speed by default — the lag-aware mode only kicks in when TPS drops:

• Normal: 8-tick transfer interval (vanilla)
• During lag (TPS < 17.0): 24-tick interval (one-third speed)
• Sorting systems still work — they just temporarily back up
• Per-chunk hopper caps available for extreme networks
• Per-world overrides for skyblock/creative servers

Anti-Lag Machine

Detects and stops four types of lag machines:

Detection	Threshold	Response
Piston spam	10/sec per location	Cancel + 30s suppression
Fluid cascades	20 flow events/sec	Cancel event
Falling block avalanches	50/chunk/sec	Cancel entity spawn
TNT chain reactions	10 primed TNT/chunk	Cancel priming

Each detection type has three response modes: cancel (silent, safest), log (monitor only), or break (remove source block — aggressive). Admin notifications via the Notifications module when a lag machine is detected.

---

Performance & Monitoring

Collision Limiter

Disables entity-entity collisions for configurable types. Collision checks scale O(n^2) with nearby entities — reducing them helps crowded areas dramatically.

• Always disabled: Armor stands, item frames, dropped items, projectiles
• Lag-aware mode: When TPS < 16.0, disables ALL mob-to-mob collisions

Tile Entity Throttler

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

• Beacons and conduits also throttled when distant
• Empty containers auto-skipped (nothing to process)
• Hoppers and spawners excluded (handled by their own modules)

Chunk Manager

Controls the chunk lifecycle — fewer loaded chunks means fewer entities to tick, fewer tile entities to process, and less memory usage.

• Stale chunk unloading: Chunks with no nearby players (>8 chunks away) are unloaded after a 30-second grace period
• Chunk load rate limiting: Max 4 loads/tick, 40 loads/second — prevents lag spikes from fast travel and teleportation
• Per-world chunk caps: Hard limits on loaded chunks per world (optional, for memory-constrained servers)
• Spawn chunks and Lands-claimed chunks can be protected from unloading

Tick Speed

Per-world overrides for random tick speed, view distance, simulation distance, and spawn limits. Apply different tuning to different worlds:

defaults:
  random_tick_speed: 3
  view_distance: 10
  simulation_distance: 8

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

Changes take effect on /px reload — no restart.

---

Lag Actions — Automatic Response System

Multi-tier automatic lag response that escalates from gentle to aggressive. Define TPS thresholds and the actions to take when the server crosses them:

Tier 1: Mild Lag (TPS < 18.0)

Broadcast a warning to players. No gameplay interference.

Tier 2: Moderate Lag (TPS < 16.0)

Clear ground items, reduce mob spawn rates by 50%, and warn players. Spawn throttle reverts after 60 seconds.

Tier 3: Severe Lag (TPS < 12.0)

Full emergency response: clear items, mobs, and excess entities. Throttle redstone and hoppers. Force JVM garbage collection. Broadcast severity warning.

Tier 4: Critical (TPS < 8.0) — Optional

Run custom console commands, kill all phantoms, unload stale chunks.

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

Spike protection: Requires 3 consecutive failed checks before triggering (configurable). Prevents one-tick lag spikes from causing unnecessary cleanup.

Auto-recovery: When TPS recovers above all thresholds (3 consecutive passing checks), broadcasts a recovery message and reverts all throttles.

---

Monitoring & Diagnostics

Performance Monitor

Live dashboard via /px monitor showing:

• TPS — 1-minute, 5-minute, and 15-minute rolling averages
• MSPT — milliseconds per tick (how much of each 50ms tick budget is used)
• Heap — JVM memory usage (used / max)
• Entities — total loaded entity count across all worlds
• Chunks — total loaded chunk count

Uses Paper's native tick APIs when available. On legacy Spigot, the built-in tick sampler provides equivalent data with configurable window size and cadence — zero overhead on Paper.

Benchmark

Hardware stress test that measures your server's actual capacity:

• CPU — single-thread and multi-thread burn tests
• RAM — sequential write/read throughput (256 MB buffer)
• Disk — read/write speed (128 MB test file)
• Network — download/upload speed via Cloudflare speed test

Produces an analysis with estimated max concurrent players, identified bottleneck, and hardware upgrade recommendations. All tests run async — the main tick is never blocked.

Speed Test

Four diagnostic probes via /px speedtest:

• Disk I/O — sequential throughput
• Network — latency to external endpoints
• TPS under load — synthetic tick stress
• Chunk generation — measures gen speed for your world generator

---

World Pre-Generation

Chunky-style chunk pre-generation so players never hit generation lag:

• Shapes: square, circle, diamond
• Parallel async generation on Paper — 4 concurrent tasks by default (configurable up to your CPU cores)
• World border auto-detection — /px pregen start world uses your vanilla world border
• Auto-pause when players join (resumes when empty), and when TPS drops
• Persistent jobs — survive server restarts, resume from where they left off
• Progress saved every 100 chunks to disk
• Terra and Iris generator detection — displays generator name in progress output

/px pregen start survival 5000 circle    # 5000-block radius circle
/px pregen start survival               # auto-detect from world border
/px pregen pause | resume | cancel | status

---

Auto Backup

Scheduled ZIP backups to five storage backends simultaneously:

Backend	Description	Examples
Local	Filesystem directory	backups/
S3	Any S3-compatible API	AWS S3, MinIO, Wasabi, Backblaze B2, IDrive e2
SFTP	SSH-based upload	Any server with SSH access
rclone	40+ cloud providers	Google Drive, Dropbox, OneDrive, Mega
FTP	Standard FTP	Any FTP server

What's included: All loaded worlds, the entire plugins/ directory, server.properties, ops.json, whitelist.json, ban lists, and any custom extras you configure.

Smart exclusions: *.log, *.tmp, cache directories, dynmap tiles, crash reports, .git/ — all excluded by default.

Key features:

• Schedule: "every 24h" or "at 2:00,14:00" for specific times
• Compression level 0-9 (default: 6)
• Retention: keep last N backups per backend (default: 7)
• Pre-backup /save-all with configurable wait time
• Restart safety: delays scheduled restarts until backup finishes
• In-game notifications on start, complete, and failure
• Discord webhook integration for remote monitoring
• Manual trigger: /px backup anytime

---

Block Logger

CoreProtect-style activity logging with zero external dependencies — uses an embedded SQLite database by default (MySQL also supported).

What's tracked:

• Block breaks and placements (who, what, where, when)
• Container interactions — chest, hopper, furnace, barrel opens
• Chat messages (optional)
• Commands (optional, for audit trails)

Commands:

/px log lookup Steve r:10 t:1h          # Steve's changes, 10 blocks, 1 hour
/px log lookup Steve r:20 t:7d a:break  # Only breaks, 7 days
/px log rollback Steve r:20 t:7d        # Undo Steve's changes
/px log restore Steve r:20 t:7d         # Re-apply rolled back changes
/px log purge 90                         # Delete entries older than 90 days
/px log status                           # DB size, entry count, backend type

Performance: Events are queued in memory and flushed in batches (500 entries every 2 seconds). Auto-purges entries older than 30 days. World blacklist to exclude 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
Players	player_join, player_quit, player_death, first_join, last_quit
Performance	tps_drop, tps_recover, lag_action, lag_machine
Cleanup	item_clear, mob_clear
Backups	backup_start, backup_complete, backup_failed
Pre-gen	pregen_start, pregen_complete, pregen_pause

Per-event customization: Each event has its own title, description, color, and @mention override. Use @here, @everyone, or <@ROLE_ID> to ping specific roles on critical events (TPS drops, lag machines, backup failures).

Delivery: Rate-limited (1 req/sec default for Discord compliance), automatic retries (3 attempts, 5s delay), and per-endpoint enable/disable.

Quick setup (Discord):

1. Channel Settings > Integrations > Webhooks > New
2. Copy the URL into webhooks.yml
3. Set enabled: true
4. /px reload — done

---

Geyser Support — Bedrock Compatibility

Bedrock players connecting via GeyserMC crash on entities and effects that Java clients handle fine. This module fixes that — without affecting Java players at all.

Problem	Solution
TextDisplay entities crash Bedrock	Hidden from all Bedrock players on spawn
Invisible ArmorStands render as T-posing models	Hidden (only invisible ones — decorative stands unaffected)
Too many entities freeze the renderer	Per-player entity cap (200 default, furthest hidden first)
TNT chains crash the client	Rate-limited: max 3 explosions/sec near Bedrock, 10 primed TNT cap
Firework shows freeze the client	Firework bursts cancelled within 48 blocks of Bedrock players
Large view distance wastes bandwidth	Per-player view (8) and simulation (6) distance reduction

Detection chain: Geyser API > Floodgate API > UUID heuristic (no hard dependency on either plugin).

---

Auto Restart

Scheduled server restarts with countdown warnings routed through the Notifications module:

• Schedule: "at 4:00" (daily), "every 12h", or multiple times
• Warnings at: 30m, 15m, 5m, 1m, 30s, 10s, 5s (all configurable)
• Safety: minimum 5 minutes uptime before first restart (prevents boot loops)
• Optional: cancel if admin is online
• PerformanceX Launcher integration — writes a .restart marker so the launcher knows it's a clean restart, not a crash

---

Integrations

PerformanceX auto-detects installed plugins and activates matching hooks. No configuration required — if the plugin is present, the integration just works.

Plugin	What it does
RoseStacker	Resets despawn timers when stack size changes — the original bug fix
ItemsAdder	Per-custom-item despawn overrides (e.g., itemsadder:myset:myitem)
DropHeads	Per-player-head despawn overrides
SafariNet	Mobs released from safari nets are protected from despawn/clear
Lands	Items and mobs inside claimed areas are protected from clearing
Multiverse-Core	Per-world-group config scoping
ResourceWorld	Exclude rotating resource worlds from monitor stats
FancyWaystones	Waystone items bypass despawn tracking entirely
ArmorStandTools	Protected armor stands are skipped by mob clear and entity limiter
ArmoredElytra	Custom elytra items get their own type key for despawn overrides
TreeFeller	Tree-feller drops are tagged for separate despawn timers
Veinminer	Veinminer drops are tagged for separate despawn timers
xPickup	Auto-pickup awareness (items never hit the ground = no timer)
Terra	Detects Terra world generator for pre-gen progress display
Iris	Detects Iris world generator for pre-gen progress display
PlaceholderAPI	Exposes 14+ placeholders for scoreboards, TAB, and other plugins

Any integration can be force-disabled via config.yml:

integrations:
  disabled:
    - rosestacker    # Disable even if RoseStacker is installed

---

PlaceholderAPI Placeholders

Placeholder	Value
%performancex_tps%	Current TPS
%performancex_tps_1m%	1-minute TPS average
%performancex_tps_5m%	5-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_spawns_blocked%	Spawns blocked this cycle
%performancex_ai_disabled%	Mobs with AI fully disabled
%performancex_ai_reduced%	Mobs with reduced AI
%performancex_lag_machines%	Total lag machine detections
%performancex_pregen_progress%	Pre-gen progress percentage
%performancex_pregen_world%	Pre-gen active world name

---

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 and their enabled/disabled/error state
/px enable <module>	Enable a module at runtime
/px disable <module>	Disable a module at runtime
/px reload	Reload all configs and reconcile module states
/px version	Plugin version and platform info
/px debug	Debug diagnostics

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 pass
/px despawn	Trigger item despawn check
/px mobdespawn	Trigger mob despawn check
/px entities	Clear excess non-mob entities
/px timer <item|mob> <type> <seconds>	Set despawn timer for a specific type

Module Controls

Command	Description
/px mobai <info|stats|shrink|restore>	Mob AI throttler controls
/px spawns	Spawn limiter stats and budgets
/px farm	Farm limiter stats
/px redstone	Redstone limiter status and detections
/px hoppers	Hopper limiter status
/px collision	Collision limiter status
/px tiles	Tile entity throttler stats
/px chunks	Chunk manager info
/px lagmachine	Lag machine detection stats
/px lagactions	Lag action system status
/px tickspeed	Per-world tick settings

World & Server

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

Logging & Diagnostics

Command	Description
/px log <lookup|rollback|restore|purge|status>	Block logger commands
/px benchmark <run|quick|results>	Hardware benchmark
/px speedtest <probe>	Diagnostic speed tests
/px logs	View recent server warnings
/px webhook <test|list>	Webhook management
/px notify [on|off]	Toggle personal notifications

---

Permissions

Permission	Description	Default
performancex.admin	All PerformanceX commands	op
performancex.notifications	Receive cleanup warnings	everyone
performancex.bypass.itemdespawn	Your items skip despawn timers	false
performancex.bypass.itemclear	Items near you skip scheduled clears	false

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

---

Configuration

PerformanceX follows a simple pattern:

1. config.yml — master toggle for each module (module-name: true/false)
2. modules/<name>.yml — detailed config for that module (only loaded if enabled)
3. /px reload — apply changes without restart

Every module's config file is pre-extracted on first run with full comments explaining every option. You always see every available setting, even for modules you haven't enabled yet.

# config.yml — just 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
  # ... 22 more modules

---

Platform Support

Platform	Version	Status
Paper	1.8.8 — 1.21.x	Full support (recommended)
Folia	1.19.4+	Full support with region-aware scheduling
Spigot	1.8.8 — 1.21.x	Full support with built-in tick sampler

PerformanceX detects your platform at startup and automatically uses the best available APIs — Paper's async chunk loading, Folia's region scheduler, or Spigot's fallback implementations. Java 8+ bytecode — runs on any Java version from 8 to 21+.

---

Quick Start

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

Every module ships with smart defaults tuned for survival servers. Most servers won't need to change anything.

---

Statistics

---

Built by ProtectCord