# 👀 Clairvoyant Anti-X-ray
**Clairvoyant** 是一个为 PaperMC 服务器设计的强大、现代的反 X 射线插件。它超越了简单的矿石隐藏，而是专注于**智能数据分析**以识别可疑玩家行为。通过仔细记录每次挖掘动作并分析模式，Clairvoyant 为服务器管理员提供清晰、基于证据的洞察力，以抓捕作弊者并维护公平的游戏环境。
Clairvoyant 的目标不是自动封禁玩家，而是赋予管理员权力。它为每个玩家计算一个“怀疑分数”，让您能够根据详细的报告和交互式游戏内可视化做出明智的决策。
-----
## ✨ 特性
* **详细动作记录**: 将每次方块破坏、方块放置和特定交互记录到本地 SQLite 数据库中，以便日后分析。
* **高级启发式引擎**: 根据多个可配置的启发式方法（例如矿石与石头比例、挖掘模式、在可疑 Y 级别挖掘）分析玩家数据，以计算总体怀疑分数。
* **交互式游戏内可视化**: `/cv trace` 命令生成交互式、仅限管理员查看的世界标记，显示玩家挖掘的位置。右键单击标记以获取有关该操作的详细信息。
* **综合报告**: `/cv check` 命令提供详细的报告，分解每个启发式方法对玩家的怀疑分数，并提供颜色编码的状态级别 ([NORMAL], [SUSPICIOUS], [DANGEROUS])。
* **高度可配置**: 分析引擎的几乎每个方面——从启发式权重到将哪些矿石视为有价值——都可以来自定义 `config.yml` 文件。这包括对添加模组或自定义物品的全面支持。
* **注重性能**: 采用异步架构构建，以最大限度地减少对服务器性能（TPS）的影响。
-----
## ❔ 兼容性
此插件是基于 **Paper API** 构建的。它将在任何维护插件兼容性的 Paper 的分支服务器软件上运行。
#### ✅ 支持的服务器软件：
* **Paper** (推荐)
* **Purpur**
* 以及 Paper 的其他直接分支。
#### ❌ 不支持的服务器软件：
* **Folia**
* **Velocity, Waterfall, BungeeCord**
* **Spigot/Bukkit**
-----
## 🛠️ 命令 & 权限
主命令是 `/clairvoyant`，别名 `/cv`。所有命令默认需要 `clairvoyant.admin` 权限。
| 命令 | 参数 | 描述 |
| :--- |:------------|:------------------------------------------------------------------------------------------------------------------------|
| `/cv stats` | `<玩家>` | 显示指定玩家的详细挖掘统计信息，包括每次类型方块的计数。 |
| `/cv trace` | `<玩家>` | 生成互动式、游戏内可视化，显示玩家最近的挖掘活动。 只有您才能看到标记。 |
| `/cv check`| `<玩家>` | 在玩家身上运行完整的启发式分析，并显示详细的怀疑报告，其中包含总分和状态。 |
| `/cv help` | | 显示可用命令列表。 |
|`/cv autopunish`| `` | 切换自动惩罚功能 |
-----
## ⚙️ 安装
1. 从发布页面下载最新的 `clairvoyant-vX.X.X.jar`。
2. 将 JAR 文件放入服务器的 `/plugins` 目录中。
3. 启动或重启服务器。
4. 插件将生成一个 `Clairvoyant` 文件夹，其中包含 `config.yml` 和 `clairvoyant.db` 文件。
-----
## 🔧 配置指南 (`config.yml`)
所有配置均在 `plugins/Clairvoyant/config.yml` 文件中处理。本指南详细介绍了每个部分。
### `weights`
此部分控制每个启发式方法对最终怀疑分数的多少影响。 建议将所有权重的总和保持在 `1.0` 左右。
* **示例**: 如果你认为 `tunneling-pattern` 是检测作弊更可靠的指标，而不是 `torch-usage`，你可以增加它的权重并降低其他权重。
```yaml
weights:
high-value-ore-ratio: 0.15
tunneling-pattern: 0.25 # 增加权重
torch-usage: 0.05
# ... 以此类推
```
### `ore-lists`
这是你定义插件应该关心的方块的地方。**你可以在这里使用它们的命名空间 ID（例如 `mod_id:item_id`）添加模组或自定义插件中的物品**。
* `high-value`: 稀有且有价值的矿石列表。以非寻常方式挖掘这些矿石会严重影响怀疑分数。
* `common`: 一张常见矿石的地图。某些启发式方法用于检测玩家是否异常专注于某种类型的常见矿石。
* `stones`: 一张通常在挖掘过程中被忽略的常见方块列表（如石头、泥土、深板岩）。此列表对于计算矿石与石头比例至关重要。
### `visualization-mapping`
此部分自定义 `/cv trace` 命令的视觉反馈。
* `default-marker`: 用于任何未在以下 `ores` 列表中指定的挖掘方块的方块。
* `ores`: 一个地图，定义了针对特定挖掘矿石应显示的方块。 例如，当挖掘 `DIAMOND_ORE` 时，trace 将显示一个 `DIAMOND_BLOCK`。
### `thresholds`
此部分允许您微调每个启发式方法的灵敏度。
* `min-blocks-for-analysis`: 玩家必须破坏的最小方块数量，才能对其数据进行分析。 这可以防止对新玩家的不准确报告。
* `high-value-ratio`: 启发式方法开始对怀疑分数产生影响的矿石与石头比例。
* `suspicious-y-levels`: 定义了寻找有价值矿石的最佳 Y 级别范围。 在这些特定区域花费过多时间的玩家将获得更高的分数。
* 以及许多其他控制每个特定分析的灵敏度的方法。
### `suspicion-levels`
此部分设置 `/cv check` 报告中显示的状态级别的分数边界。
* `suspicious`: 任何高于此值的分数都将被标记为 **[SUSPICIOUS]**。
* `dangerous`: 任何高于此值的分数都将被标记为 **[DANGEROUS]**。
### `auto-punish`
此部分设置自动惩罚功能的阈值级别和惩罚命令。
* `enabled`: 开启和关闭自动惩罚功能。
* `threshold-level`: 设置自动惩罚功能的阈值级别。
* `command`: 当达到关键级别时要执行的命令。