VeinGuard

Minecraft 版本： 1.18 1.18.1 1.18.2 1.19 1.19.1 1.19.2 1.19.3 1.19.4 1.20 1.20.1 1.20.2 1.20.3 1.20.4 1.20.5 1.20.6 1.21 1.21.1 1.21.2 1.21.3 1.21.4 1.21.5 1.21.6 1.21.7 1.21.8 1.21.9 1.21.10 1.21.11 26.1 26.1.1 26.1.2 26.2

平台： bukkit paper purpur spigot

标签： management utility

---

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.

---

Expand for Commands & Permissions
### ? Permissions Overview * `veinguard.admin` — Full access to all plugin features and commands. * `veinguard.mod` — Standard moderator access. Includes: * `veinguard.notify`, `veinguard.bypass`, `veinguard.command.check`, `veinguard.command.help`, `veinguard.command.history`, `veinguard.command.top`, `veinguard.command.toggle-alerts`, `veinguard.command.tracked-blocks.list`. * `veinguard.notify` — Receive in-game alert notifications. * `veinguard.bypass` — Complete exemption from tracking. * `veinguard.bypass.[MATERIAL]` — Exemption for a specific block (e.g., `veinguard.bypass.DIAMOND_ORE`). * `veinguard.unmute` — Permission to unmute players. * `veinguard.resetall` — Permission to reset tracking for all players. * `veinguard.update` — Receive update notifications on join. --- ### ? Commands | Command | Permission | Description | Example Usage | | :--- | :--- | :--- | :--- | | `/vg help [page]` | `veinguard.command.help` | Displays a detailed list of all available commands and their usage. | `/vg help 2` | | `/vg check ` | `veinguard.command.check` | Opens a real-time report of a player's recent mining activity, including exact block counts. | `/vg check Notch` | | `/vg history [time]` | `veinguard.command.history` | Retrieves historical mining incidents from the database for investigation of offline players. | `/vg history Notch 24h` | | `/vg top [time]` | `veinguard.command.top` | Displays a leaderboard of players with the highest violation levels, block counts, and total alerts triggered. | `/vg top 7d` | | `/vg patrol ` | `veinguard.command.patrol` | Manage the automated staff patrol: `start`, `stop`, `pause`, `resume`, `next`, or `back`. | `/vg patrol start` | | `/vg msg ` | `veinguard.command.msg` | Sends a formatted plugin message to a player (useful for automated violation actions). | `/vg msg Notch Fair play only!` | | `/vg staffmsg ` | `veinguard.command.staffmsg` | Broadcasts an administrative message to all staff members with notification permissions. | `/vg staffmsg Checking Notch.` | | `/vg mute ` | `veinguard.command.mute` | Silences all future alert notifications for a specific player (e.g., for trusted members). | `/vg mute Notch` | | `/vg unmute ` | `veinguard.command.unmute` | Restores alert notifications for a previously muted player. | `/vg unmute Notch` | | `/vg toggle-alerts [player]` | `veinguard.command.toggle-alerts` | Toggles your own alert visibility or manages it for another staff member. | `/vg toggle-alerts` | | `/vg tracked-blocks ` | `veinguard.command.tracked-blocks.[add/list/remove]` | Real-time management of which blocks are being monitored by the system. | `/vg tracked-blocks add DIAMOND_ORE 15 Diamond Ore` | | `/vg reload` | `veinguard.command.reload` | Hot-reloads all configuration and language files without requiring a server restart. | `/vg reload` | | `/vg reset ` | `veinguard.command.reset` | Completely clears a specific player's current break history and Violation Level (VL). | `/vg reset Notch` | | `/vg resetall` | `veinguard.command.resetall` | Wipes active tracking data and VL scores for all online players simultaneously. | `/vg resetall` | | `/vg purge [player]` | `veinguard.command.purge` | Manually removes old historical data from the database to keep it optimized. | `/vg purge 30d` |

? 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.