Skip to main content

NekoAntiXray - 完整文档

版本: AllPlatform-2.1.1 Minecraft: 1.21.10+ (Paper/Folia) 作者: SakuyaAyane Ghost Java: 17+

目录​

  1. 概览
  2. 安装指南
  3. 配置指南
  4. 检测系统
  5. 命令参考
  6. 权限
  7. API 参考
  8. 开发者指南
  9. 故障排除
  10. 附录

概览​

NekoAntiXray 是一款专为 Minecraft Folia/Paper 服务器设计的综合反作弊插件，专门用于通过多个独立的检测层来检测和防止 X-Ray（透视）作弊行为：

检测层级​

层级系统名称方式描述
1AlgoAntiXray行为分析挖矿路径追踪、矿脉聚类、模式识别
2XRayCheck陷阱式假矿石生成与监控
3Enhanced Anti-Xray数据包修改基于射线追踪的区块混淆
4DeepLearn深度学习ONNX 模型推理用于行为分析

附加功能​

  • 反种子破解 (Anti-Seed Cracker): 通过数据包修改防止世界种子被提取
  • 回放系统: 使用盔甲架可视化挖矿路径回放
  • 矿石统计: 玩家挖矿统计和排行榜
  • 大规模挖掘检测: 对合法的大规模挖掘行为进行智能检测
  • BungeeCord 集成: 跨服务器公告

架构概览​

NekoAntiXray.java (主插件类)
    ├── AlgoAntiXray.java (行为检测)
    ├── XRayCheck.java (假矿石检测)
    ├── enhanced/ (数据包修改系统)
    │   ├── EnhancedPacketListener.java
    │   ├── RayTraceCallable.java
    │   └── ChunkPacketBlockControllerAntiXray.java
    ├── antiseedcracker/ (种子保护)
    ├── deeplearn/ (ML 推理)
    ├── replay/ (挖矿回放)
    └── Utils/ (工具与配置)

安装指南​

要求​

  • 服务端: Paper 1.21.10+ 或 Folia 1.20.6+
  • Java: Java 17 或更高版本
  • 前置插件: ProtocolLib 5.3.0+
  • 可选: ONNX Runtime (用于深度学习模块)

分步安装​

  1. 下载插件

    NekoAntiXray-AllPlatform-2.1.1.jar

  2. 安装 ProtocolLib

  3. 安装 NekoAntiXray

    • 将 NekoAntiXray-AllPlatform-2.1.1.jar 放入 plugins/ 文件夹

  4. 启动服务器

    • 启动你的服务器
    • 插件将在 plugins/NekoAntiXray/ 中生成 config.yml

  5. 配置 (可选)

    • 编辑 plugins/NekoAntiXray/config.yml
    • 使用 /nax reload 应用更改

可选: 深度学习设置​

  1. 安装 ONNX Runtime

  2. 准备模型文件

    plugins/NekoAntiXray/
    ├── model.onnx           # 训练好的模型
    └── feature_stats.json   # 特征归一化统计数据

  3. 在配置中启用

    deeplearn:
      enable: true

配置指南​

配置文件位置​

plugins/NekoAntiXray/config.yml

主要配置部分​

1. 挖矿行为分析器 (AlgoAntiXray)​

check:
  mining-behavior-analyzer:
    active: false                    # 总开关

    # 世界特定设置
    world-configs:
      world: { enabled: true, y-limit: 32 }
      world_nether: { enabled: true, y-limit: 128 }
      world_the_end: { enabled: false, y-limit: -1 }
      _default: { enabled: false, y-limit: -1 }

    # 监控的目标矿石
    target-blocks:
      - ANCIENT_DEBRIS
      - EMERALD_ORE
      - DEEPSLATE_EMERALD_ORE
      - DIAMOND_ORE
      - DEEPSLATE_DIAMOND_ORE

    # 数据收集设置
    data-collection:
      path-max-blocks: 500           # 每个挖矿路径的最大方块数
      cleanup-after-minutes: 15       # VL=0 后的清理延迟
      vein-cluster:
        distance: 5                   # 矿脉聚类距离
        small-size: 4                 # 小矿脉阈值
        trigger-count: 3              # 触发分析的矿脉数量

    # 模式分析阈值
    pattern-analyzer:
      turning-limit: 10               # 转向次数阈值
      branching-limit: 6              # 分支数量阈值
      y-shift-limit: 4                # Y 轴变化阈值
      y-shift-min: 3                  # 每次位移的最小 Y 变化

    # 环境过滤器 (减少误报)
    environment-filters:
      apply-filters: true
      cave:
        air-count: 14                 # 洞穴检测的空气方块数
        cave-air-multiplier: 5        # 洞穴空气 (CAVE_AIR) 权重
        radius: 3                     # 扫描半径
        reduce-vl: true               # 在洞穴中减少 VL

    # 违规处理系统
    violation-system:
      auto-decay:
        enabled: true
        interval-minutes: 3
        amount: 1
      threshold-commands:
        10: 'say %player% triggered detection [VL: 10]'
        30:
          - 'kick %player% Abnormal mining detected'

2. 假矿石检测 (XRayCheck)​

check:
  xray:
    enable: true                      # 总开关
    same-chunk-detection: true        # 同区块豁免

    line-break:
      length: 3                       # 直线挖掘检测

    spawn:
      ore: 30                         # 每次触发的生成尝试次数
      time: 225                       # 假矿石存活时间 (秒)
      distance-limit:
        ore: 12                       # 假矿石之间的最小距离
        player: 12                    # 距离玩家的最小距离
      x-change: { min: -10, max: 15 }
      z-change: { min: -10, max: 15 }
      y-change: { min: -10, max: 8 }
      amount: { min: 5, max: 7 }      # 每个位置的假矿石数量

    mining-count-threshold: 3         # 触发生成的挖掘计数

    vl:
      add:
        break-self: 1.0               # 破坏自己生成的假矿石增加的 VL
        break-other: 2.0              # 破坏他人生成的假矿石增加的 VL
      ban:
        enable: true
        threshold: 10.0               # 自动封禁 VL 阈值
        command: "ban %player% %duration% X-Ray detected"

3. 增强型反矿透 (Enhanced Anti-Xray / 数据包修改)​

world-settings:
  default:
    enabled: true
    anti-xray:
      ray-trace-third-person: true    # 第三人称射线追踪
      ray-trace-distance: 80.0        # 最大射线追踪距离
      rehide-blocks: true             # 方块破坏后重新隐藏
      rehide-distance: 80.0           # 重新隐藏检查距离
      max-ray-trace-block-count-per-chunk: 100
      ray-trace-blocks: []            # 空列表 = 使用 Paper 默认值
    ray-trace-threads: 4              # 线程池大小

4. 深度学习模块​

deeplearn:
  enable: false
  debug: false

  sequence_length: 50                 # 每次推理的事件数
  prediction_threshold: 0.5           # 作弊概率阈值
  cooldown_ms: 5000                   # 推理冷却时间
  mining_time_window_ms: 600000       # 10 分钟

  vein_detection:
    max_distance: 2.0
    max_time_ms: 3000
    max_consecutive_skips: 15
    max_vertical_distance: 3.0

  violations:
    enable-punishment: true
    vl-multiplier: 10.0
    min-vl-increase: 1
    max-vl-increase: 15

  valuable_materials:
    - DIAMOND_ORE
    - DEEPSLATE_DIAMOND_ORE
    - EMERALD_ORE
    # ... 更多材质

5. 反种子破解 (Anti-Seed Cracker)​

antiSeedCracker:
  enable: true
  modifyHashedSeed:
    enable: true                      # 随机化种子数据包
  modifyEndStructures:
    enable: true
    worlds:
      - world_the_end
    endSpikes:
      enable: true
      mode: "swap"                    # "swap" (交换) 或 "move" (移动)
    endCities:
      enable: true                    # 修改洋红色玻璃

6. 其他设置​

# 黑名单
blacklist:
  ores:
    - COAL_ORE
    - IRON_ORE
  worlds:
    - world_test

# 封禁设置
ban-announcement:
  message: "§c玩家 %player% 因作弊被封禁！"
ban-duration: 30                      # 天数，-1 为永久
enable-ban-announcement: true

# 回放系统
replay:
  enabled: true
  record-duration: 300                # 5 分钟

# 矿石统计
ore-stats:
  enabled: true
  track-all-ores: true

检测系统​

1. AlgoAntiXray (行为分析)​

工作原理​

  1. 路径追踪: 记录玩家挖掘位置到路径列表中
  2. 矿脉聚类: 使用 BFS 将相邻矿石方块分组为矿脉
  3. 模式分析: 分析路径特征：
    • 转向频率 (如果频繁改变方向则可疑)
    • 分支数量 (如果呈锯齿状则可疑)
    • Y 轴变化 (如果垂直跳跃则可疑)
  4. 环境过滤: 在自然洞穴、水域、岩浆中降低 VL
  5. 违规管理: 累积 VL，在达到阈值时触发动作

检测流程​

BlockBreakEvent (方块破坏事件) → handleBlockBreak()
    ├── 检查是否为目标矿石
    ├── 添加到挖掘路径
    ├── 矿脉聚类
    │   └── 如果新矿脉计数 >= 阈值
    │       ├── 分析路径平滑度
    │       ├── 检查自然环境
    │       └── 计算 VL 增加值
    └── 检查阈值命令

关键阈值​

参数默认值描述
turning-limit10被视为可疑前的最大转向次数
branching-limit6被视为可疑前的最大分支数
y-shift-limit4最大 Y 轴变化次数
vein-cluster.distance5同一矿脉的最大距离
vein-cluster.trigger-count3触发分析的矿脉数

2. XRayCheck (假矿石系统)​

工作原理​

  1. 触发: 玩家连续挖掘矿石 (计数 >= 阈值)
  2. 生成: 在玩家周围生成隐形假矿石
  3. 监控: 追踪玩家是否破坏假矿石
  4. 惩罚: 每破坏一个假矿石增加 VL

假矿石生命周期​

玩家挖掘矿石 → 挖掘计数++
    └── 如果计数 >= 阈值
        ├── 计算生成位置
        ├── 检查距离限制
        └── 放置假矿石 (225秒后过期)

玩家破坏方块 → 检查是否为假矿石
    └── 如果是假矿石
        ├── VL += break-self (破坏自己生成的) 或 break-other (破坏他人生成的)
        ├── 检查连续违规
        └── 检查封禁阈值

3. Enhanced Anti-Xray (增强型/射线追踪)​

工作原理​

  1. 数据包拦截: 通过 ProtocolLib 拦截 MAP_CHUNK (区块地图) 数据包
  2. 缓存区块数据: 存储混淆后的方块位置
  3. 射线追踪: 计算玩家眼部位置的方块可见性
  4. 更新数据包: 可见时发送真实方块，隐藏时发送混淆方块

线程模型​

主线程 (Main Thread)             射线追踪线程池 (Ray-Trace Thread Pool)
    │                              │
    ├─ MAP_CHUNK 数据包 ──────────→ 缓存 ChunkBlocks
    │                              │
    │  定时器 (50ms) ──────────────→ RayTraceCallable.call()
    │                              ├── 对每个区块
    │                              │   ├── DDA 射线追踪
    │                              │   └── 队列结果
    │                              │
    │  更新 (1 tick) ←──────────── 轮询结果
    ├── 发送 BlockUpdate (方块更新) 数据包
    │

性能调优​

设置默认值范围影响
ray-trace-threads42-8CPU 使用率
ray-trace-distance8040-120精度 vs 性能
max-ray-trace-block-count-per-chunk10050-200单区块负载

4. DeepLearn (深度学习检测)​

工作原理​

  1. 特征提取: 从挖掘事件中生成特征：
    • 旋转差异 (相对于上一个矿石的角度)
    • 与上一个矿石的距离
    • 破坏前矿石是否暴露
    • 近期矿石数量
  2. 序列构建: 每个玩家缓冲 50 个事件
  3. 推理: 序列完成后运行 ONNX 模型
  4. VL 计算: VL = (概率 - 阈值) * 倍率

训练数据收集​

使用 /nax record <玩家> start cheater|legit 收集带标签的数据用于模型训练。

命令参考​

主命令: /nax​

子命令用法描述
reload/nax reload重载配置
ban/nax ban <玩家> [原因]因透视封禁玩家
resetviolation/nax resetviolation <玩家>清除玩家的 VL
replay/nax replay [play|stop|pause]挖掘回放控制
orestats/nax orestats <玩家>查看矿石统计
oretop/nax oretop查看矿石排行榜
oretrack/nax oretrack <玩家>切换矿石通知
record/nax record <玩家> <start|stop> [标签]ML 训练数据收集
internalbypass/nax internalbypass <grant|remove|list>管理绕过
realseed/nax realseed [world]查看真实世界种子
cleanup/nax cleanup清理回放盔甲架
togglemassexcavation/nax togglemassexcavation切换大规模挖掘检测
announcement/nax announcement <stats|announce>封禁公告

回放子命令​

命令描述
/nax replay打开回放 GUI
/nax replay play <文件>开始回放
/nax replay stop停止回放
/nax replay pause暂停/继续回放
/nax replay forward快进
/nax replay backward倒退
/nax replay tp传送到回放位置
/nax replay delete <文件>删除回放文件

内部绕过子命令​

命令描述
/nax internalbypass grant <玩家> <秒数> [原因]授予检测豁免
/nax internalbypass remove <玩家>移除绕过
/nax internalbypass list列出活跃的绕过
/nax internalbypass clear清除所有绕过
/nax internalbypass info <玩家>查看绕过详情
/nax internalbypass extend <玩家> <秒数>延长绕过时间

权限​

权限描述默认
nekoantixray.admin所有管理员命令OP
nekoantixray.reload重载配置OP
nekoantixray.ban封禁玩家OP
nekoantixray.resetviolation重置 VLOP
nekoantixray.replay回放命令OP
nekoantixray.orestats查看统计OP
nekoantixray.oretrack追踪玩家OP
nekoantixray.cleanup清理盔甲架OP
nekoantixray.realseed查看真实种子OP
nekoantixray.update更新插件OP
nekoantixray.bypass绕过检测false
nekoantixray.alerts接收警报OP
nekoantixray.massexcavation大规模挖掘控制OP
nekoantixray.locate.bypass使用 /locate 命令OP
fakeseed.viewreal查看真实种子OP
fakeseed.reload重载假种子OP

API 参考​

公共类​

NekoAntiXray (主插件类)​

public class NekoAntiXray extends JavaPlugin {
    // 获取插件实例
    public static NekoAntiXray getInstance()

    // 获取 FoliaLib 用于调度
    public FoliaLib getFoliaLib()

    // 获取子系统
    public AlgoAntiXray getAlgoAntiXray()
    public XRayCheck getXRayCheck()
    public ConfigManager getConfigManager()
    public ReplayManager getReplayManager()
    public InferenceManager getInferenceManager()
    public OreStatsManager getOreStatsManager()

    // 验证
    public boolean validatePlayerData(Player player, String operation)
}

AlgoAntiXray (行为检测)​

public class AlgoAntiXray {
    // 检测入口点
    public void handleBlockBreak(Player player, Block block)
    public void handleBlockPlace(Player player, Block block)
    public void handleExplosion(List<Block> explodedBlocks, Entity sourceEntity)

    // VL 管理
    public int getViolationLevel(UUID playerId)
    public void increaseViolationLevelFromAI(Player player, float probability)

    // 查询方法
    public List<Location> getMiningPath(UUID playerId, String worldName)
    public int countVeinBlocks(Location startLocation, Material type)
}

XRayCheck (假矿石检测)​

public class XRayCheck {
    // 检测
    public void checkXRay(Player player, Block block)
    public boolean isFakeOre(Block block)
    public void processFakeOreBreak(Player player, Block block)

    // 管理
    public void addNoCheckBlock(Location location)
    public void removeFakeOre(Location location)

    // 查询
    public Map<Location, Material> getFakeOreTypes()
    public double getPlayerViolation(Player player)

    // 清理
    public void cleanupMiningCounts()
    public void cleanupFakeOres()
    public void decreaseViolations()
}

ConfigManager (配置管理)​

public class ConfigManager {
    // 生命周期
    public void loadConfig()
    public void reloadConfig()

    // AlgoAntiXray 设置
    public boolean isWorldDetectionEnabled(String worldName)
    public int getWorldMaxHeight(String worldName)
    public List<String> getAlgoRareOres()
    public int getMaxPathLength()

    // XRay 设置
    public boolean isXRayEnabled()
    public double getBanThreshold()
    public int getMiningCountThreshold()

    // DeepLearn 设置
    public boolean isDeepLearnEnabled()
    public int getDeepLearnSequenceLength()
    public double getDeepLearnPredictionThreshold()
}

InferenceManager (ML 检测)​

public class InferenceManager {
    // 生命周期
    public InferenceManager(NekoAntiXray plugin)
    public void close()

    // 检测
    public Map<String, Object> onPlayerBlockBreak(Player player, Block block)

    // 状态
    public boolean isReady()
}

OreStatsManager (矿石统计)​

public class OreStatsManager {
    // 记录
    public void recordOreMined(Player player, Material oreType)

    // 查询
    public Map<String, Integer> getPlayerStats(String playerName)
    public List<Map.Entry<String, Integer>> getTopPlayers(int limit)
    public boolean hasStats(String playerName)

    // 管理
    public void clearPlayerStats(String playerName)
    public void saveStats()
    public void reload()
}

事件钩子​

插件使用标准的 Bukkit 事件：

// 方块事件
@EventHandler
public void onBlockBreak(BlockBreakEvent event)

@EventHandler
public void onBlockPlace(BlockPlaceEvent event)

// 爆炸事件
@EventHandler
public void onBlockExplode(BlockExplodeEvent event)

@EventHandler
public void onEntityExplode(EntityExplodeEvent event)

// 玩家事件
@EventHandler
public void onPlayerJoin(PlayerJoinEvent event)

@EventHandler
public void onPlayerQuit(PlayerQuitEvent event)

开发者指南​

项目结构​

src/main/java/sakuyaayane/nekoantixray/
├── NekoAntiXray.java              # 插件主类
├── AlgoAntiXray.java              # 行为检测
├── XRayCheck.java                 # 假矿石检测
├── XRayListener.java              # 事件协调器
├── commands/                       # 命令处理器 (18 个文件)
├── enhanced/                       # 数据包修改 (20 个文件)
│   ├── listeners/                 # ProtocolLib 监听器
│   ├── tasks/                     # 异步射线追踪任务
│   └── utils/                     # 数据结构
├── antiseedcracker/               # 种子保护 (15 个文件)
├── deeplearn/                     # ML 推理 (3 个文件)
├── replay/                        # 挖掘回放 (6 个文件)
└── Utils/                         # 工具类 (22 个文件)

构建说明​

# 克隆仓库
git clone https://github.com/MelodyAyane/NekoAntiXray.git
cd NekoAntiXray

# 使用 Maven 构建
mvn clean package

# 输出 JAR
target/NekoAntiXray-AllPlatform-2.1.1.jar

依赖项​

依赖版本范围用途
Paper API1.21.10-R0.1providedBukkit/Paper API
Folia API1.20.6-R0.1providedFolia 支持
ProtocolLib5.3.0provided数据包操作
FoliaLib0.5.0compile+shade调度器抽象
bStats3.0.2compile+shade统计
ONNX Runtime1.18.0providedML 推理
Gson2.10.1compileJSON 解析

编码规范​

Folia 兼容性​

始终使用 FoliaLib 进行调度：

// 良好 - 兼容 Folia
plugin.getFoliaLib().getImpl().runTimer(task, delay, period, TimeUnit.SECONDS);
plugin.getFoliaLib().getImpl().runAsync(task);
plugin.getFoliaLib().getImpl().runAtEntity(player, task);

// 糟糕 - 在 Folia 上会崩溃
Bukkit.getScheduler().runTask(plugin, task);

线程安全​

使用并发数据结构：

// 玩家数据映射
private final Map<UUID, Data> playerData = new ConcurrentHashMap<>();

// 方块位置追踪
private final LongBooleanHashMap blockCache = new LongBooleanHashMap();

空值安全​

始终验证玩家数据：

public void handleBlockBreak(Player player, Block block) {
    if (!plugin.validatePlayerData(player, "handleBlockBreak")) {
        return;
    }
    // 可以安全继续
}

添加检测功能​

  1. 根据策略选择检测系统
  2. 向 config.yml 添加配置键
  3. 使用 getter 更新 ConfigManager
  4. 实现检测逻辑
  5. 在 Folia 服务器上测试

测试​

  1. 部署到 Folia/Paper 1.21.10+ 测试服务器
  2. 使用 X-Ray 资源包进行测试
  3. 监控控制台的违规信息
  4. 检查 TPS 影响
  5. 验证 VL 衰减和清理

故障排除​

常见问题​

插件无法加载​

症状: 插件加载失败，控制台报错

解决方案:

  1. 验证是否安装了 Java 17+
  2. 确保 ProtocolLib 已安装且为最新版本
  3. 检查控制台的具体错误信息
  4. 验证服务器是否为 Paper/Folia 1.21.10+

CPU 使用率高​

症状: 插件激活时服务器 TPS 下降

解决方案:

  1. 在配置中减少 ray-trace-threads
  2. 增加 ms-per-ray-trace-tick (降低更新频率)
  3. 减少 ray-trace-distance
  4. 在次要世界中禁用增强型反矿透 (enhanced anti-xray)

误报​

症状: 合法玩家被标记为 X-Ray

解决方案:

  1. 启用环境过滤器 (洞穴, 水, 岩浆)
  2. 提高检测阈值
  3. 将矿石添加到黑名单
  4. 为生存服务器启用大规模挖掘检测

内存泄漏​

症状: 内存使用量随时间增加

解决方案:

  1. 验证清理任务是否正在运行 (检查日志)
  2. 减小 cleanup-after-minutes 值
  3. 确保玩家正确断开连接 (无挂起数据)

调试模式​

启用调试日志：

deeplearn:
  debug: true

检查控制台以获取详细的检测日志。

获取帮助​

附录​

A. 矿石类型参考​

材质检测层级默认状态
DIAMOND_ORE (钻石矿)Algo, XRay, Deep启用
DEEPSLATE_DIAMOND_ORE (深层钻石矿)Algo, XRay, Deep启用
EMERALD_ORE (绿宝石矿)Algo, XRay, Deep启用
ANCIENT_DEBRIS (远古残骸)Algo, XRay, Deep启用
GOLD_ORE (金矿)Deep黑名单
IRON_ORE (铁矿)Deep黑名单
COAL_ORE (煤矿)-黑名单
COPPER_ORE (铜矿)-黑名单

B. VL 计算参考​

AlgoAntiXray VL​

每条可疑路径的基础 VL: 1
洞穴修正: -50% (如果 reduce-vl: true)
爆炸加成: suspicious_rate × penalty_multiplier
AI 加成: (probability - threshold) × vl_multiplier

XRayCheck VL​

破坏自己的假矿石: +1.0
破坏他人的假矿石: +2.0
连续违规加成: +1.0 (在 60秒内达到 3次后)

C. 性能基准测试​

设置内存CPU准确率
仅 Enhanced50MB5%高
Enhanced + Algo80MB10%极高
全部 (含 ML)150MB15%最高

D. 配置模板​

严格模式 (低容忍度)​

check:
  mining-behavior-analyzer:
    active: true
    pattern-analyzer:
      turning-limit: 8
      branching-limit: 4
      y-shift-limit: 3
    environment-filters:
      apply-filters: false
  xray:
    enable: true
    mining-count-threshold: 2
    vl:
      ban:
        threshold: 5.0

宽松模式 (低误报)​

check:
  mining-behavior-analyzer:
    active: true
    pattern-analyzer:
      turning-limit: 15
      branching-limit: 10
      y-shift-limit: 6
    environment-filters:
      apply-filters: true
      cave:
        reduce-vl: true
  xray:
    enable: false

E. 文件位置​

文件位置用途
config.ymlplugins/NekoAntiXray/主配置
ore-stats.ymlplugins/NekoAntiXray/矿石统计
ban-statistics.ymlplugins/NekoAntiXray/封禁记录
model.onnxplugins/NekoAntiXray/ML 模型
feature_stats.jsonplugins/NekoAntiXray/特征归一化
*.replayplugins/NekoAntiXray/replays/回放文件
recording_*.csvplugins/NekoAntiXray/training_data/训练数据

文档生成于 NekoAntiXray v2.1.1 最后更新: 2025-12-17