<\/p>\n
# \ud83d\udc40 Clairvoyant Anti-X-ray<\/p>\n
**Clairvoyant** is a powerful, modern anti-x-ray plugin designed for PaperMC servers. It moves beyond simple ore obfuscation and instead focuses on **intelligent data analysis** to identify suspicious player behavior. By meticulously logging every mining action and analyzing patterns, Clairvoyant provides server administrators with the clear, evidence-based insights needed to catch cheaters and maintain a fair gameplay environment.<\/p>\n
The goal of Clairvoyant is not to automatically ban players, but to empower administrators. It calculates a “Suspicion Score” for each player, allowing you to make informed decisions based on detailed reports and interactive in-game visualizations.<\/p>\n
—–<\/p>\n
## \u2728 Features<\/p>\n
* **Detailed Action Logging**: Logs every block break, block place, and specific interactions to a local SQLite database for later analysis.
\n* **Advanced Heuristic Engine**: Analyzes player data against multiple configurable heuristics (e.g., ore-to-stone ratio, tunneling patterns, mining at suspicious Y-levels) to calculate an overall suspicion score.
\n* **Interactive In-Game Visualization**: The `\/cv trace` command generates interactive, admin-only visual markers in the world, showing exactly where a player has mined. Right-click a marker to get detailed information about the action.
\n* **Comprehensive Reports**: The `\/cv check` command provides a detailed report, breaking down the player’s suspicion score by each heuristic, complete with color-coded status levels ([NORMAL], [SUSPICIOUS], [DANGEROUS]).
\n* **Highly Configurable**: Almost every aspect of the analysis engine\u2014from heuristic weights to what ores are considered valuable\u2014can be customized in the `config.yml` file. This includes full support for adding modded or custom items.
\n* **Performance-Focused**: Built with an asynchronous architecture to minimize impact on server performance (TPS).<\/p>\n
—–<\/p>\n
## \u2754 Compatibility<\/p>\n
This plugin is built on the **Paper API**. It will work on any server software that is a fork of Paper and maintains plugin compatibility.<\/p>\n
#### \u2705 Supported Server Software:<\/p>\n
* **Paper** (Recommended)
\n* **Purpur**
\n* And other direct forks of Paper.<\/p>\n
#### \u274c Unsupported Server Software:<\/p>\n
* **Folia**
\n* **Velocity, Waterfall, BungeeCord**
\n* **Spigot\/Bukkit**<\/p>\n
—–<\/p>\n
## \ud83d\udee0\ufe0f Commands & Permissions<\/p>\n
The main command is `\/clairvoyant`, with alias `\/cv`. All commands require the permission `clairvoyant.admin` by default.<\/p>\n
| Command | Arguments | Description | —–<\/p>\n ## \u2699\ufe0f Installation<\/p>\n 1. Download the latest `clairvoyant-vX.X.X.jar` from the releases page. —–<\/p>\n ## \ud83d\udd27 Configuration Guide (`config.yml`)<\/p>\n All configuration is handled in the `plugins\/Clairvoyant\/config.yml` file. This guide explains each section in detail.<\/p>\n ### `weights`<\/p>\n This section controls how much influence each heuristic has on the final suspicion score. It’s recommended to keep the sum of all weights equal to `1.0`.<\/p>\n * **Example**: If you think `tunneling-pattern` is a more reliable indicator of cheating than `torch-usage`, you can increase its weight and decrease the other.<\/p>\n <\/p>\n “`yaml ### `ore-lists`<\/p>\n This is where you define which blocks the plugin should care about. **You can add items from mods or custom plugins here** using their unique namespaced ID (e.g., `mod_id:item_id`).<\/p>\n * `high-value`: A list of rare and valuable ores. Mining these ores in unusual ways will significantly impact the suspicion score. ### `visualization-mapping`<\/p>\n This section customizes the visual feedback for the `\/cv trace` command.<\/p>\n * `default-marker`: The block that will be used for any mined block not specified in the `ores` list below. ### `thresholds`<\/p>\n This section allows you to fine-tune the sensitivity of each heuristic.<\/p>\n * `min-blocks-for-analysis`: The minimum number of blocks a player must break before their data can be analyzed. This prevents inaccurate reports for new players. ### `suspicion-levels`<\/p>\n This section sets the score boundaries for the status levels displayed in the `\/cv check` report.<\/p>\n * `suspicious`: Any score above this value will be flagged as **[SUSPICIOUS]**. ### `auto-punish`<\/p>\n This section sets the threshold level and punishment command for the auto-punish feature.<\/p>\n * `enabled`: Turns the auto-punish feature on and off. <\/p>\n","protected":false},"excerpt":{"rendered":" A plugin for detecting X-ray users by logging and visualizing their activities.<\/p>\n","protected":false},"featured_media":40539,"template":"","meta":{"_minecraft_slug":"clairvoyant","_minecraft_project_id":"ssG5wQAM","_minecraft_author":"nitg3n","_minecraft_license":"MIT","_minecraft_downloads":179,"_minecraft_follows":4,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"clairvoyant.zip","_minecraft_size_bytes":84489100,"_minecraft_version_count":4,"_minecraft_updated_at":"2026-05-16T13:00:39.965719Z","_minecraft_date_created":"2025-08-13T20:21:51.867742Z","_minecraft_date_modified":"2025-08-19T08:39:40.203828Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/clairvoyant","_minecraft_icon_attachment_id":40539,"_minecraft_imported_at":"2026-06-01T21:50:48+00:00","_minecraft_import_hash":"f91baabfcfe2f753f858deb7bf4ec9dd","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[89,126,127,128,867,92],"mod_loader":[132,133],"minecraft_version":[62,37,73,74,38,78,79,80,81],"class_list":["post-40538","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-game-mechanics","mod_category-management","mod_category-paper","mod_category-purpur","mod_category-social","mod_category-utility","mod_loader-paper","mod_loader-purpur","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8"],"yoast_head":"\n
\n| :— |:————|:————————————————————————————————————————|
\n| `\/cv stats` | `
\n| `\/cv trace` | `
\n| `\/cv check`| `
\n| `\/cv help` | | Displays the list of available commands. |
\n|`\/cv autopunish`| `
\n2. Place the JAR file into your server’s `\/plugins` directory.
\n3. Start or restart your server.
\n4. The plugin will generate a `Clairvoyant` folder containing the `config.yml` and `clairvoyant.db` files.<\/p>\n
\nweights:
\n high-value-ore-ratio: 0.15
\n tunneling-pattern: 0.25 # Increased weight
\n torch-usage: 0.05
\n # … and so on
\n“`<\/p>\n
\n* `common`: A map of common ores. Used by some heuristics to detect if a player is abnormally focusing on one type of common ore.
\n* `stones`: A list of common blocks that are typically ignored during mining (like stone, dirt, deepslate). This list is crucial for calculating ore-to-stone ratios.<\/p>\n
\n* `ores`: A map that defines which block to show for a specific mined ore. For example, when a `DIAMOND_ORE` is mined, the trace will show a `DIAMOND_BLOCK`.<\/p>\n
\n* `high-value-ratio`: The ore-to-stone ratio above which the heuristic will start adding to the suspicion score.
\n* `suspicious-y-levels`: Defines the Y-level ranges that are considered optimal for finding valuable ores. Players who spend an unusual amount of time mining in these specific zones will get a higher score.
\n* And many others to control the sensitivity of each specific analysis.<\/p>\n
\n* `dangerous`: Any score above this value will be flagged as **[DANGEROUS]**.<\/p>\n
\n* `threshold-level`: Sets the threshold level for the auto-punish feature.
\n* `command`: Sets the command to execute when the critical level is reached.<\/p>\n