PerformanceAnalyzer v1.2.2 (Paper 1.21.4-1.21.10 / Java 21)

A comprehensive performance monitoring plugin for Minecraft Paper servers with database logging, alert system, interactive GUI, and AntiCheat functionality.

Features

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
• Fly Detection: Checks for illegal vertical movement
• Speed Detection: Detects too fast horizontal movement
• 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)
• 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.

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

/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

Configuration

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

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
  whitelist_players: []           # Player UUIDs
  whitelist_groups: []            # LuckPerms groups

thresholds:
  mspt: 50.0                      # MSPT warning threshold
  heap_usage_percent: 80.0        # Heap warning threshold
  packet_flood_per_tick: 1000.0   # Packet flood 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.

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

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 (planned)

• Future integration for detailed profiling
• 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

Changelog

v1.2.2 (Current)

New Features:

• Per-Ore Thresholds - Each ore has its own threshold (Ancient Debris: 3, Diamond: 6, Coal: 20, etc.)
• Coordinates in XRay Alerts - Shows world, position, and mining area (Multiverse compatible)
• Debug Mode - Console logs only when debug_mode enabled in config.yml
• OPs Bypass Option - Configurable whether OPs should bypass AntiCheat checks

Improvements:

• MySQL driver as provided - Server operator must supply the driver
• Clear error message when MySQL configured but driver missing
• Dynamic User-Agent in Discord Webhook (shows current plugin version)
• AntiCheat disabled by default (must be consciously enabled)
• Less console spam through debug mode

Bugfixes:

• TPS drop alerts are now correctly sent to Discord
• XRay commands work even when AntiCheat is disabled (shows helpful message)

v1.2.1

New Features:

• XRay Alert System (/xrayalerts) - Bundled alerts with command overview
• XRay Ore Exclusions (/xrayores) - Exclude ores via command
• XRay Ore Breakdown - Shows exactly which ores were mined
• XRay Discord Integration - Suspicious players reported to Discord
• Config Migration - New config entries are automatically added

Improvements:

• ProtocolLib 1.21.x compatibility (no more warnings)
• GUI completely overhauled and fixed
• Bundled chat notifications (less spam)
• Extended config options for XRay
• Ore breakdown in alerts and Discord messages

Bugfixes:

• GUI event handlers now work correctly
• ProtocolLib filters only supported packet types
• Thread-safety improvements in XRayDetector
• Config is automatically updated on plugin updates

v1.2.0

New Features:

• Interactive GUI System (/perfgui) with dashboard, config, and AntiCheat overview
• XRay Detection with three detection methods (frequency, ratio, rare ores)
• Discord Webhook Integration for automatic notifications
• LuckPerms Integration for group-based AntiCheat whitelist
• Whitelist System with /acwhitelist command (players + groups)
• Reload Command (/perfreload) for config updates without restart
• Tab Completion for all commands

Improvements:

• Alert system with Discord integration
• Config options changeable via GUI
• Extended AntiCheat config
• All settings live-reloadable

v1.1.0

Fixed:

• Fake data in AsciiSparkline replaced with real DB data
• Thread-safety issues in TickSampler
• ProtocolLib hook fully implemented
• Old duplicate classes removed

New:

• Alert system with admin notifications
• AntiCheat module for basic cheat detection
• DB query methods for historical analysis
• Automatic DB logging for all metrics
• Packet flood detection
• Performance spike counter
• Extended config options

Future Features (TODO)

• Web dashboard for live monitoring
• Grafana/Prometheus export
• Per-world performance stats
• Chunk loading tracking
• Entity density analysis
• Spark integration for profiling
• Discord webhook for alerts (Implemented)
• Database cleanup command