PerformanceAnalyzer v2.0.0 (Paper 1.21.x / Java 21)

A comprehensive performance monitoring and lag diagnosis plugin for Minecraft Paper servers with database logging, alert system, interactive multi-page GUI, AntiCheat functionality, and intelligent lag source detection.

Features

Multi-Language Support

English and German fully supported
Language files in plugins/PerformanceAnalyzer/lang/
Easily customizable translations
Language switchable via config and /perfreload

Performance Monitoring

TPS Tracking: Approximate ticks per second
MSPT Analysis: Average, P95 percentile, and historical data
Heap Monitoring: Memory usage in percent
Thread-Safe Sampling: Reliable data collection without race conditions

Database Support

SQLite (Default): No external DB required, perfect for small servers
MySQL: For larger servers with centralized database
HikariCP Connection Pooling: Optimal performance
Async Batch Writes: No performance impact from DB writes
Historical Queries: Retrieve performance data over time ranges

Alert System

Automatic Notifications when thresholds are exceeded
Admin Notifications: In-game messages + console logs
Cooldown System: Prevents alert spam (5 minutes per type)
Alert types:
- High MSPT (> 50ms)
- TPS drops (< 19 TPS)
- Heap usage (> 80%)
- Packet flood (> 1000 packets/tick)

ProtocolLib Integration

Packet Analysis: Counts received/sent packets
Flood Detection: Warns on unusually high packet load
DB Logging: Stores packet statistics for analysis
1.21.x Compatible: Automatically filters only supported packet types

AntiCheat Module (BETA)

Movement Checks: Detects impossible movements with movement type awareness
- Detects: Walking, Sprinting, Sneaking, Swimming, Climbing
- Vehicle awareness: Horses, Pigs, Striders, Boats, Minecarts
- Flight modes: Elytra, Riptide, Creative Flight
- Automatic bypass for legitimate movement types
Fly Detection: Checks for illegal vertical movement
Speed Detection: Detects too fast horizontal movement
- Configurable thresholds for walk, sprint, fly, vertical, teleport
- Consecutive violation system to reduce false positives
- Improved detection: Now properly distinguishes walking vs sprinting
Movement Alerts: Bundled alerts via /movealerts command
XRay Detection: Analyzes mining patterns for rare ores
- Frequency analysis (too many ores in short time)
- Ore/stone ratio (unnaturally high ore percentage)
- Rare ore tracking (diamonds, emeralds, ancient debris)
- Per-ore thresholds: Different thresholds for each ore type
- Ore exclusions: Exclude specific ores from detection
- Bundled alerts: Only one summary in chat, details via command
- Coordinates & World: Shows where mining occurred (Multiverse compatible)
🆕 Restricted World Zones: Instant alerts for specific worlds
- Configure worlds where ANY ore mining triggers immediate alerts
- Optional: Only monitor specific ores (diamonds, emeralds, etc.)
- Perfect for protected areas, creative worlds, or suspect player monitoring
- No thresholds needed - instant notification with exact coordinates
Whitelist System: Exclude players and LuckPerms groups
Violation Tracking: Counts violations per player
Admin Alerts: Notifies admins of suspicious behavior

NOTE: The AntiCheat module is experimental and may produce false positives. For production servers, we recommend specialized plugins like Matrix, Vulcan, or Spartan.

Analysis Tools

Per-World Statistics (/worldstats): Entity counts, chunk stats, density per world
Entity Analysis (/entitystats): Entity breakdown by category, hotspot detection
Chunk Tracking (/chunkstats): Load/unload tracking, problematic chunks, thrashing detection
Hotspot Detection: Identifies chunks with too many entities or tile entities
Chunk Thrashing: Detects chunks that load/unload frequently (performance issue indicator)
🆕 Lag Source Detection (/perfdrops): Automatically identifies what's causing lag
- Player Activity Tracking: Monitors block breaks, placements, movements, commands
- Plugin Performance Analysis: Identifies suspect plugins by listener count and tasks
- Weighted Scoring: Block interactions weighted higher than walking
- Top 5 Lists: Shows most active players and suspect plugins during drops
- Heavy Plugin Detection: Automatically flags WorldEdit, FAWE, CoreProtect, etc.
Performance Drop Analysis (/perfdrops): Automatic detection and analysis of performance drops
- Records TPS drops and MSPT spikes automatically
- Captures detailed server state at time of drop (chunks, entities, players, memory)
- Shows which entity types are most common per world
- Displays player locations during the drop
- 🆕 Shows lag sources: Players and plugins responsible for lag
- Stores last 20 drops for analysis
- Detailed reports help quickly identify and fix lag causes

Interactive GUI System

Performance Dashboard: Live TPS, MSPT, and heap usage with updates
Config GUI: Toggle all settings (AntiCheat, XRay, Discord, packets)
AntiCheat GUI: Status overview, whitelist info, XRay settings
🆕 Lag-Analyse GUI: Interactive page showing top active players and suspect plugins
- Top 5 most active players with detailed activity breakdown
- Top 5 suspect plugins with risk scores and listener counts
- Refresh and clear data buttons
- Shows "Heavy Plugin" badges (WorldEdit, FAWE, CoreProtect)
🆕 Performance Drops GUI: Browse and analyze recent performance drops
- Visual list of up to 21 recent drops (color-coded by severity)
- Click any drop for detailed report in chat
- Shows lag sources preview (players & plugins)
- Clear all or refresh buttons
🆕 Database Info: Quick database status overview
🆕 World Stats Quick-Link: Direct access to world statistics
Multi-page navigation with back buttons
All options changeable via GUI or command
Intuitive operation with colored items

Discord Webhook Integration

Automatic Notifications for critical events
Color-coded Embeds for different alert types
Configurable Alerts: Choose which events to report
XRay Alerts: Suspicious players reported to Discord
Async HTTP Requests: No performance impact
Simple setup via config

LuckPerms Integration

Group-based Whitelist for AntiCheat
Automatic group detection
Primary & inherited groups are considered

Commands

`/perfstatus`

Shows live performance data:

TPS (approximate)
MSPT (average and P95)
Heap usage in percent
Title warning on high load (for players)

Permission: performance.status (Default: true)

`/perfhistory [minutes]`

Shows historical performance data as ASCII sparkline:

MSPT history from database (real data!)
Live statistics
DB average over selected time range
Number of performance spikes
Optional: Specify time range in minutes (Default: 60)

Permission: performance.history (Default: true)

Examples:

/perfhistory - Last 60 minutes
/perfhistory 180 - Last 3 hours
/perfhistory 1440 - Last 24 hours

`/perfgui`

Opens the interactive performance GUI:

Performance dashboard with live data
Change config settings with clicks
AntiCheat status and whitelist
Reload button for config

Permission: performance.gui (Default: true)

`/perfreload`

Reloads the plugin configuration without server restart:

Config file is re-read
All settings are updated
XRay ore exclusions are reloaded
No interruption of operation

Permission: performance.admin (Default: op)

`/acwhitelist` (Alias: `/acwl`)

Manages the AntiCheat whitelist:

/acwhitelist add <player> - Add player to whitelist
/acwhitelist add group:<groupname> - Add LuckPerms group
/acwhitelist remove <player> - Remove player from whitelist
/acwhitelist remove group:<groupname> - Remove group
/acwhitelist list - Show all whitelisted players/groups

Permission: performance.anticheat.manage (Default: op)

Examples:

# Individual players
/acwhitelist add Notch
/acwhitelist remove Notch

# LuckPerms groups
/acwhitelist add group:admin
/acwhitelist add group:moderator
/acwhitelist remove group:builder

# Show list
/acwhitelist list

`/xrayalerts` (Alias: `/xra`)

Shows and manages XRay suspicion alerts:

/xrayalerts - Show all suspicious players
/xrayalerts <player> - Details for a player (incl. which ores were mined)
/xrayalerts clear <player> - Clear alerts for a player
/xrayalerts clearall - Clear all alerts

Permission: performance.admin (Default: op)

How it works:

Alerts are collected and bundled
Only one summary appears in chat per player (every 5 min)
Details via /xrayalerts <player> (also shows exactly which ores were mined)
Alerts are automatically deleted after 30 minutes
Suspicious players are also reported to Discord (incl. ore breakdown)

`/movealerts` (Alias: `/mva`)

Shows and manages Movement/Speed/Fly suspicion alerts:

/movealerts - Show all suspicious players
/movealerts <player> - Details for a player (incl. violation type and location)
/movealerts clear <player> - Clear alerts for a player
/movealerts clearall - Clear all alerts

Permission: performance.admin (Default: op)

How it works:

Movement alerts are collected and bundled (similar to XRay)
Detects Speed, Fly, and Teleport-like movement violations
Automatically accounts for movement type (walking, sprinting, swimming, etc.)
Only one summary appears in chat per player (every 5 min)
Alerts are automatically deleted after 30 minutes
Suspicious players are also reported to Discord

`/xrayores` (Alias: `/xro`)

Manages XRay ore exclusions:

/xrayores list - Show excluded ores
/xrayores available - Show all available ores
/xrayores add <ore> - Exclude ore from XRay detection
/xrayores remove <ore> - Track ore again

Permission: performance.anticheat.manage (Default: op)

Examples:

# Exclude coal and iron
/xrayores add COAL_ORE
/xrayores add IRON_ORE

# Show available ores
/xrayores available

# Track ore again
/xrayores remove COAL_ORE

`/worldstats` (Alias: `/ws`)

Shows per-world statistics:

/worldstats - Overview of all worlds (entities, chunks, density)
/worldstats <world> - Detailed view for specific world

Permission: performance.admin (Default: op)

Shows:

Total entities, players, loaded chunks, tile entities
Entity density per chunk
Top entity types in the world
Entity hotspots (high-density chunks)

`/entitystats` (Alias: `/es`)

Analyzes entity distribution:

/entitystats - Server-wide entity analysis
/entitystats <world> - Analysis for specific world
/entitystats hotspots - Show entity hotspots

Permission: performance.admin (Default: op)

Shows:

Total entity count
Breakdown by category (Hostile, Passive, Items, Vehicles, etc.)
Top entity types
Hotspot locations with dominant entity type
Health status per world (Healthy/Warning/Critical)

`/chunkstats` (Alias: `/cs`)

Shows chunk loading statistics:

/chunkstats - Chunk overview (loaded, force-loaded, per-world)
/chunkstats problems - Show problematic chunks (high entity/tile count)
/chunkstats frequent - Show chunk thrashing (frequently loaded chunks)
/chunkstats clear - Clear tracking history

Permission: performance.admin (Default: op)

Shows:

Total loaded and force-loaded chunks
Loads/minute, total loads/unloads this session
Per-world breakdown with new chunk generation count
Problematic chunks with entity/tile entity counts
Chunk thrashing detection (chunks loading too often)

`/perfdrops` (Alias: `/pd`, `/drops`)

Shows and analyzes recent performance drops:

/perfdrops - List of recent performance drops (last 20)
/perfdrops <number> - Detailed analysis of a specific drop

Permission: performance.admin (Default: op)

How it works:

Automatically detects TPS drops (>5 TPS drop or below threshold)
Automatically detects MSPT spikes (>30ms spike or above threshold)
Records detailed server state at time of drop:
- Loaded chunks and total entities per world
- Top 5 entity types per world
- All player locations
- Memory usage
Stores last 20 drops in memory
Logs drops to database for historical analysis

Example:

# Show list of recent drops
/perfdrops

# View detailed analysis of drop #3
/perfdrops 3

The detailed report shows exactly what was happening on the server when the lag occurred, helping you identify the cause (e.g., too many mobs in a specific world, chunk overload, etc.).

Configuration

# Language: en (English), de (German)
language: en

database:
  type: sqlite                    # or 'mysql'
  sqlite_file: "plugins/PerformanceAnalyzer/perf.db"

performance:
  log_interval_seconds: 60        # Logging interval
  packet_analysis: true           # ProtocolLib hook
  anticheat_enabled: false        # AntiCheat module (BETA, default: off)
  debug_mode: false               # Debug output in console

lag_analysis:
  player_tracking: true           # Player activity tracking (with sampling)
  plugin_analysis: true           # Plugin performance analysis
  chunk_analysis_timeout_ms: 5000 # Timeout for chunk analysis (prevents lag)

  # Chunk thresholds (adjust based on your server hardware)
  chunk_tile_entities_threshold: 10   # Tile entities per chunk
                                      # Standard: 10 | Powerful: 20-30 | Weak: 5-8
  chunk_redstone_threshold: 30        # Redstone components per chunk
                                      # Standard: 30 | Powerful: 50-100 | Weak: 15-20
  chunk_entity_warning: 50            # Entities per chunk (Warning level)
                                      # Standard: 50 | Powerful: 80-100 | Weak: 30-40
  chunk_entity_critical: 100          # Entities per chunk (Critical level)
                                      # Standard: 100 | Powerful: 150-200 | Weak: 60-80

  # World health thresholds
  world_entity_warning: 5000          # Total entities per world (Warning)
                                      # Standard: 5000 | Large: 10000+ | Small: 2000-3000
  world_entity_critical: 10000        # Total entities per world (Critical)
                                      # Standard: 10000 | Large: 20000+ | Small: 5000-7000

  # Plugin risk score interpretation
  # Risk Score = (Event Listeners * 2) + (Scheduled Tasks * 3)
  # Heavy plugins (WorldEdit, FAWE) are multiplied by 2
  plugin_risk_low: 50                 # Low risk plugins (0-50)
  plugin_risk_medium: 100             # Medium risk plugins (51-100)
                                      # High risk: 101+ (everything above medium)

anticheat:
  xray_detection: true            # XRay detection
  xray_timewindow_seconds: 60     # Time window
  ops_bypass: false               # Should OPs bypass AntiCheat? (default: false)
  xray_excluded_ores: []          # Exclude ores, e.g. ["COAL_ORE", "IRON_ORE"]
  xray_thresholds:                # Per-ore thresholds
    coal: 20
    iron: 15
    copper: 15
    gold: 10
    redstone: 10
    lapis: 8
    diamond: 6
    emerald: 4
    ancient_debris: 3
  xray_stone_ore_ratio: 0.10      # Ore-to-stone ratio threshold (0.0-1.0)
                                  # Normal: 2-5% ores (0.02-0.05)
                                  # Suspicious: >10% ores (>0.10)
  whitelist_players: []           # Player UUIDs
  whitelist_groups: []            # LuckPerms groups
  speed_thresholds:               # Movement detection thresholds
    walk: 0.5                     # Max speed while walking
    sprint: 1.0                   # Max speed while sprinting
    fly: 1.5                      # Max creative flight speed
    vertical: 3.5                 # Max vertical speed (fly hack)
    teleport: 15.0                # Teleport-like movement threshold
    violations_before_alert: 5    # Consecutive violations before alert
    fly_violations_before_alert: 10

thresholds:
  mspt: 50.0                      # MSPT warning threshold
  heap_usage_percent: 80.0        # Heap warning threshold
  packet_flood_per_tick: 1000.0   # Packet flood threshold
  tps_drop: 19.0                  # TPS drop warning threshold

discord:
  enabled: false                  # Discord notifications
  webhook_url: ""                 # Discord Webhook URL
  alert_types:                    # Which alerts to send?
    high_mspt: true
    tps_drop: true
    high_heap: true
    packet_flood: true
    anticheat: true               # XRay alerts

XRay Ore Exclusions

You can exclude specific ores from XRay detection:

anticheat:
  xray_excluded_ores:
    - COAL_ORE        # Exclude coal
    - IRON_ORE        # Exclude iron
    - COPPER_ORE      # Exclude copper

Available ores: COAL_ORE, IRON_ORE, COPPER_ORE, GOLD_ORE, REDSTONE_ORE, LAPIS_ORE, DIAMOND_ORE, EMERALD_ORE, ANCIENT_DEBRIS

Deepslate variants (e.g. DEEPSLATE_DIAMOND_ORE) are automatically excluded as well.

Language Configuration

The plugin supports multiple languages. Set your language in config.yml:

# Available: en (English), de (German)
language: en

Language files are stored in plugins/PerformanceAnalyzer/lang/:

en.yml - English (default)
de.yml - German

You can customize any message by editing these files. After changes, use /perfreload to apply.

Adding a new language:

Copy en.yml to <code>.yml (e.g., fr.yml for French)
Translate all messages
Set language: fr in config.yml
Run /perfreload

Per-Ore Thresholds

Each ore type has its own threshold. When a player mines more than the threshold amount within the time window, an alert is triggered:

anticheat:
  xray_thresholds:
    coal: 20           # Common - high threshold
    iron: 15
    copper: 15
    gold: 10
    redstone: 10
    lapis: 8
    diamond: 6         # Rare - low threshold
    emerald: 4
    ancient_debris: 3  # Very rare - very low threshold

XRay Stone-to-Ore Ratio

The ore-to-stone ratio threshold is now configurable. This detects when a player mines too many ores compared to stone:

anticheat:
  xray_stone_ore_ratio: 0.10  # 10% ores is suspicious
                              # Normal mining: 2-5% (0.02-0.05)
                              # Suspicious: >10% (0.10+)

Lower values make the detection more strict, higher values more lenient. The check only triggers after a player has mined at least 20 stone blocks for meaningful statistical analysis.

Configurable Performance Thresholds (NEW in v2.0.0)

All performance thresholds are now configurable to prevent false alerts on servers with different hardware specifications. Adjust these values in the lag_analysis section of your config:

Chunk Thresholds:

lag_analysis:
  chunk_tile_entities_threshold: 10   # Hoppers, furnaces, chests per chunk
  chunk_redstone_threshold: 30        # Redstone components per chunk
  chunk_entity_warning: 50            # Entities per chunk (Warning)
  chunk_entity_critical: 100          # Entities per chunk (Critical)

World Health Thresholds:

lag_analysis:
  world_entity_warning: 5000          # Total entities per world (Warning)
  world_entity_critical: 10000        # Total entities per world (Critical)

Plugin Risk Score:

lag_analysis:
  plugin_risk_low: 50                 # 0-50 = Low risk (green)
  plugin_risk_medium: 100             # 51-100 = Medium risk (yellow)
                                      # 101+ = High risk (red)

The config file includes detailed comments with recommendations for different server types:

Standard Servers: Default values work well for most servers
Powerful Servers: Can handle higher thresholds (more entities/redstone)
Weak Servers: Should use lower thresholds to catch problems earlier

Example - High-Performance Server:

lag_analysis:
  chunk_tile_entities_threshold: 25
  chunk_redstone_threshold: 80
  chunk_entity_warning: 100
  chunk_entity_critical: 200
  world_entity_warning: 15000
  world_entity_critical: 25000

Plugin Risk Score Calculation:

Risk Score = (Event Listeners × 2) + (Scheduled Tasks × 3)
Heavy plugins (WorldEdit, FAWE, CoreProtect) have their score multiplied by 2
Helps identify plugins that may impact performance

Permissions

Permission	Description	Default
`performance.status`	Use `/perfstatus`	true
`performance.history`	Use `/perfhistory`	true
`performance.gui`	Use `/perfgui`	true
`performance.admin`	`/perfreload`, `/xrayalerts`, alert notifications	op
`performance.anticheat.bypass`	Bypass all AntiCheat checks	false
`performance.anticheat.manage`	Use `/acwhitelist`, `/xrayores`	op

Optional Dependencies

ProtocolLib (recommended)

Enables packet analysis and flood detection
Download: https://www.spigotmc.org/resources/protocollib.1997/

LuckPerms (recommended)

Enables group-based AntiCheat whitelist
Automatic group detection for players
Download: https://luckperms.net/

spark (recommended)

Accurate TPS/MSPT/CPU data: When Spark is installed, /perfstatus uses Spark's precise measurements
Multi-window TPS: Shows TPS for 10s, 1m, and 5m windows
Extended MSPT: Shows average, 95th percentile, and max values
CPU Monitoring: System and process CPU usage
Automatic fallback to internal calculations if Spark unavailable
Download: https://spark.lucko.me/

Technical Details

Java 21 required
Paper 1.21.4-1.21.10 compatible
Thread-safe implementation
Minimal performance overhead
Async DB operations
Maven Shade Plugin for dependency shading

Special Thank

to ELITEK3V for testing

PerfomanceAnalyzer

📖About PerfomanceAnalyzer

PerformanceAnalyzer v2.0.0 (Paper 1.21.x / Java 21)

Features

Multi-Language Support

Performance Monitoring

Database Support

Alert System

ProtocolLib Integration

AntiCheat Module (BETA)

Analysis Tools

Interactive GUI System

Discord Webhook Integration

LuckPerms Integration

Commands

`/perfstatus`

`/perfhistory [minutes]`

`/perfgui`

`/perfreload`

`/acwhitelist` (Alias: `/acwl`)

`/xrayalerts` (Alias: `/xra`)

`/movealerts` (Alias: `/mva`)

`/xrayores` (Alias: `/xro`)

`/worldstats` (Alias: `/ws`)

`/entitystats` (Alias: `/es`)

`/chunkstats` (Alias: `/cs`)

`/perfdrops` (Alias: `/pd`, `/drops`)

Configuration

XRay Ore Exclusions

Language Configuration

Per-Ore Thresholds

XRay Stone-to-Ore Ratio

Configurable Performance Thresholds (NEW in v2.0.0)

Permissions

Optional Dependencies

ProtocolLib (recommended)

LuckPerms (recommended)

spark (recommended)

Technical Details

Special Thank

PerfomanceAnalyzer

📖About PerfomanceAnalyzer

PerformanceAnalyzer v2.0.0 (Paper 1.21.x / Java 21)

Features

Multi-Language Support

Performance Monitoring

Database Support

Alert System

ProtocolLib Integration

AntiCheat Module (BETA)

Analysis Tools

Interactive GUI System

Discord Webhook Integration

LuckPerms Integration

Commands

/perfstatus

/perfhistory [minutes]

/perfgui

/perfreload

/acwhitelist (Alias: /acwl)

/xrayalerts (Alias: /xra)

/movealerts (Alias: /mva)

/xrayores (Alias: /xro)

/worldstats (Alias: /ws)

/entitystats (Alias: /es)

/chunkstats (Alias: /cs)

/perfdrops (Alias: /pd, /drops)

Configuration

XRay Ore Exclusions

Language Configuration

Per-Ore Thresholds

XRay Stone-to-Ore Ratio

Configurable Performance Thresholds (NEW in v2.0.0)

Permissions

Optional Dependencies

ProtocolLib (recommended)

LuckPerms (recommended)

spark (recommended)

Technical Details

Special Thank

`/perfstatus`

`/perfhistory [minutes]`

`/perfgui`

`/perfreload`

`/acwhitelist` (Alias: `/acwl`)

`/xrayalerts` (Alias: `/xra`)

`/movealerts` (Alias: `/mva`)

`/xrayores` (Alias: `/xro`)

`/worldstats` (Alias: `/ws`)

`/entitystats` (Alias: `/es`)

`/chunkstats` (Alias: `/cs`)

`/perfdrops` (Alias: `/pd`, `/drops`)