PerformanceX

---

What is PerformanceX?

PerformanceX is a never requires a restart 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.

(I'm bad with graphics forgive me please haha if you are better with them, get in touch via discord I will happily credit you for the artwork!)

---

---

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 | |:-----|:---------|:---------| | Junk | Never despawns | Nether Star, Elytra, Dragon Egg, Totem of Undying | | Junk | 30 minutes | Diamond, Emerald, Trident, Ancient Debris, Netherite | | Junk | 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: ```yaml 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: - Configurable countdown warnings with wildcard patterns (`minecraft:netherite_*`) - Configurable countdown warnings — items inside claimed areas are never cleared - Configurable countdown warnings — items near staff are protected - Configurable countdown warnings via actionbar, title, or chat

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

- Sweep interval (default: 8 blocks, cross-chunk) - Sweep interval — ender pearls cap at 16, not 64 - Sweep interval 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: ```yaml 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 | |:-------|:-----------------|:---------| | Misc | 8 | Zombies, Skeletons, Creepers | | Misc | 10 | Cows, Sheep, Pigs, Villagers | | Misc | 4 | Bats | | Misc | 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 | |:-----|:------|:---------| | No AI | 0-32 blocks | Normal — pathfinding, attacking, wandering | | No AI | 32-48 blocks | AI ticks every 4th sweep cycle (75% savings) | | No AI | 48-64 blocks | Completely frozen — zero AI overhead |

Villagers let you tune each mob type independently: - Villagers: shorter range (they're dangerous, keep AI closer) - Villagers: 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 | |:-------|:------------|:--------| | Item flood | Min interval between spawns + mob count cap near spawner | 20s, max 10 mobs | | Item flood | Random skip chance per growth tick | 85% pass rate (15% slower) | | Item flood | Tighter throttle for bamboo, cactus, sugar cane, kelp | 50-65% pass rate | | Item flood | Extended cooldown beyond vanilla's 5 minutes | 10 min cooldown | | Item flood | 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 | |:-----|:---------| | Disable | Log offending locations to console, don't interfere | | Disable | 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:

- During lag (TPS < 17.0): 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 | |:----------|:----------|:---------| | TNT chain reactions | 10/sec per location | Cancel + 30s suppression | | TNT chain reactions | 20 flow events/sec | Cancel event | | TNT chain reactions | 50/chunk/sec | Cancel entity spawn | | TNT chain reactions | 10 primed TNT/chunk | Cancel priming |

Each detection type has three response modes: break (silent, safest), break (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.

- Lag-aware mode: 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.

- Per-world chunk caps: Chunks with no nearby players (>8 chunks away) are unloaded after a 30-second grace period - Per-world chunk caps: 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:

```yaml 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: - Chunks — 1-minute, 5-minute, and 15-minute rolling averages - Chunks — milliseconds per tick (how much of each 50ms tick budget is used) - Chunks — JVM memory usage (used / max) - Chunks — 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: - Network — single-thread and multi-thread burn tests - Network — sequential write/read throughput (256 MB buffer) - Network — 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`: - Chunk generation — sequential throughput - Chunk generation — latency to external endpoints - Chunk generation — 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:

- Terra and Iris generator detection square, circle, diamond - Terra and Iris generator detection on Paper — 4 concurrent tasks by default (configurable up to your CPU cores) - Terra and Iris generator detection — `/px pregen start world` uses your vanilla world border - Terra and Iris generator detection when players join (resumes when empty), and when TPS drops - Terra and Iris generator detection — survive server restarts, resume from where they left off - Terra and Iris generator detection 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 | |:--------|:-----------|:---------| | FTP | Filesystem directory | `backups/` | | FTP | Any S3-compatible API | AWS S3, MinIO, Wasabi, Backblaze B2, IDrive e2 | | FTP | SSH-based upload | Any server with SSH access | | FTP | 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.

Restart safety: - 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 | |:---------|:-------| | Pre-gen | `server_start`, `server_stop`, `restart_warning`, `restart` | | Pre-gen | `player_join`, `player_quit`, `player_death`, `first_join`, `last_quit` | | Pre-gen | `tps_drop`, `tps_recover`, `lag_action`, `lag_machine` | | Pre-gen | `item_clear`, `mob_clear` | | Pre-gen | `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 | |:-------|:------------| | PlaceholderAPI | Resets despawn timers when stack size changes — the original bug fix | | PlaceholderAPI | Per-custom-item despawn overrides (e.g., `itemsadder:myset:myitem`) | | PlaceholderAPI | Per-player-head despawn overrides | | PlaceholderAPI | Mobs released from safari nets are protected from despawn/clear | | PlaceholderAPI | Items and mobs inside claimed areas are protected from clearing | | PlaceholderAPI | Per-world-group config scoping | | PlaceholderAPI | Exclude rotating resource worlds from monitor stats | | PlaceholderAPI | Waystone items bypass despawn tracking entirely | | PlaceholderAPI | Protected armor stands are skipped by mob clear and entity limiter | | PlaceholderAPI | Custom elytra items get their own type key for despawn overrides | | PlaceholderAPI | Tree-feller drops are tagged for separate despawn timers | | PlaceholderAPI | Veinminer drops are tagged for separate despawn timers | | PlaceholderAPI | Auto-pickup awareness (items never hit the ground = no timer) | | PlaceholderAPI | Detects Terra world generator for pre-gen progress display | | PlaceholderAPI | 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`: ```yaml 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`).

---

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. `/px reload` — master toggle for each module (`module-name: true/false`) 2. `/px reload` — 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.

```yaml

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 | |:---------|:--------|:-------| | Spigot | 1.8.8 — 1.21.x | Full support (recommended) | | Spigot | 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

bStats

---