VeinGuard

VeinGuard is a robust, lightweight anti-xray solution designed to help server administrators identify and monitor suspicious mining patterns in real-time. By tracking specific block breaks and analyzing player behavior, VeinGuard provides the tools necessary to maintain a fair gaming environment without compromising server performance.

Unlike traditional anti-xray plugins that obfuscate blocks, VeinGuard focuses on behavioral detection, giving staff the evidence they need to take action.

🛡️ Core Detection & Analysis

• Intelligent Tracking: Monitors specific block types (configured by you) and calculates break rates over customizable timeframes.
• Violation Level (VL) System: Assigns a "suspicion score" to players based on their mining activity. VL decays over time but triggers automated actions when thresholds are met.
• Mining Incident Model: Groups consecutive alerts into single "incidents" for a cleaner, more accurate overview of mining sessions.
• Anti-Spam Logic: Configurable cooldowns per block or per alert ensure your staff aren't overwhelmed by repetitive notifications.

📢 Multi-Channel Alerts

• In-Game Notifications: Instant alerts via Chat or Action Bar for online staff.
• Discord Integration: Seamless webhook support to log alerts directly to your staff channels.
• Console Logging: Detailed logs for administrative review.
• Automated Actions: Execute custom commands (e.g., mute, freeze, or kick) automatically when a player reaches a specific violation threshold.

🕵️ Staff Tools & Investigation

• Advanced Patrol System: Cycle through online players in Spectator mode with an automated UI and boss bar tracking.
• Detailed Player Reports: Generate instant reports showing exact block counts and highlighted violations.
• History & Leaderboards: Access a persistent database (SQLite/MySQL) to view historical mining data and top violators over time.
• Staff Utility: Easily mute alerts for specific players or toggle your own notification visibility.

⚙️ Customization & Integration

• Dynamic Configuration: Reload settings and language files on-the-fly without restarting the server.
• Granular Bypasses: Exempt players via permissions globally or for specific materials.
• WorldGuard Support: Use the veinguard-check custom flag to enable or disable tracking in specific regions.
• Smart Filtering: Automatically ignores players in Creative mode, specific worlds, or above a defined Y-level.

📋 Requirements

• Java: Version 17 or newer.
• Platform: Spigot, Paper, Purpur (1.21+), or any compatible fork.
• Version: Minecraft 1.18+ (Spigot/Paper).

🚀 Quick Start

1. Download: Grab the latest .jar from Spigot, Modrinth, Hangar, or GitHub.
2. Install: Drop the file into your server's plugins/ directory.
3. Initialize: Start the server to generate the default configuration files.
4. Configure: Adjust config.yml and lang.yml to your preference.
5. Apply: Run /vg reload to apply changes instantly.

📖 How to Use

VeinGuard is designed to be intuitive for both administrators and staff. Below is a guide on how to get the most out of the plugin.

👑 For Server Owners & Admins

1. Define Tracked Blocks: Open config.yml to specify which blocks VeinGuard should monitor (e.g., DIAMOND_ORE, ANCIENT_DEBRIS). We have already provided a list of common blocks.
2. Set Thresholds: Configure the threshold for each block. If a player breaks more than the threshold within the timeframe, an alert is triggered.
3. Configure Automated Actions: Use the Violation Level (VL) system to execute commands automatically (e.g., /kick or /freeze) when a player reaches a certain suspicion level.
4. Manage Regions: Use WorldGuard flags (veinguard-check: deny) to disable tracking in areas like public mines or other areas where a player shouldn't be tracked.

👮 For Staff & Moderators

• Monitor Alerts: Keep an eye on in-game chat or Discord. Alerts group consecutive breaks into "Incidents" to prevent spam.
• Real-Time Investigation: Use /vg check <player> to see a player's recent mining activity and current break rates.
• Review History: Use /vg history <player> to pull historical data from the database, even if the player is offline.
• Active Patrol: Use /vg patrol start to automatically cycle through online players in Spectator mode. The Boss Bar will keep you informed of their status.
• Manage Notifications: Use /vg toggle-alerts to hide notifications if you're busy, or /vg mute <player> to silence a specific (trusted) user.

👤 For Players

• Fair Play: Just play normally! VeinGuard is designed to ignore natural mining patterns and only flags highly suspicious, repetitive behavior.
• Privacy: Staff can only see mining statistics for tracked blocks; your other activities remain private.

🔍 Anatomy of a Mining Incident

To better understand how VeinGuard protects your server, let's walk through a typical detection scenario:

1. The Trigger: A player mines a tracked block (e.g., Diamond Ore). VeinGuard immediately records this event in its internal cache.
2. Threshold Check: If the player mines more blocks than allowed within your configured timeframe (e.g., 15 diamonds in 5 minutes), an Alert is triggered.
3. Data Processing:
   • In-Game: Staff receive a notification (Chat or Action Bar).
   • Discord: A webhook sends detailed info (coordinates, light level, etc.) to your staff channel.
   • Database: The incident is logged to the persistent database (SQLite or MySQL).
4. Violation Levels (VL):
   • Each alert adds to the player's VL score (based on the block's "weight").
   • VL Decay: If the player stops mining suspiciously, their VL will naturally decrease over time.
5. Automated Action: If the player's VL reaches a specific threshold (e.g., 50 VL), VeinGuard executes your pre-defined Violation Action (e.g., /kick or /freeze).
6. Staff Investigation:
   • Real-time: Staff use /vg check <player> to see the total number of tracked blocks they've mined in the last configured timeframe.
   • History: Staff use /vg history <player> to review past incidents starting with the most recent, also displaying details such as block counts, coordinates, and timestamps.
   • Verdict: Staff can then teleport to the location or use /vg patrol to monitor the player.

🔗 Useful Links

• 📖 Documentation & Wiki: Detailed guides and configuration help.
• 🐞 Issue Tracker: Report bugs or suggest new features.
• 💬 Discord Support: Get help and stay updated.
• 📊 Plugin Metrics: View our anonymous usage statistics.