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

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.

Downloads
✔ 10
✔ 50
✔ 100
✘ 250
✘ 500
✘ 1000