MikuXrayNet

声明

本项目为 MikuMC 服务器原创插件，公开给大众免费使用，MikuMC 服务器与作者 JunXieX 享有项目著作权，本项目非开源项目，请注意。

MikuMC 系列插件交流群：1105054380

---

MikuMC 服务器原创的 反矿透 + 带宽优化 双模块插件，适配 Paper 26.2+ / Folia，基于 Java 25。

一句话：让透视端看不到真矿，同时让服务端少发封包。

---

一、功能特性

反矿透（AntiXray）

把埋在地下、玩家看不见的矿物与容器替换成普通方块后再发给客户端；等玩家真的走近、且真的能看见时，再还原成真实方块。

能力	说明
掩埋伪装	默认模式（all）会把所有看不见的目标方块替换掉（含暴露在洞穴里的矿脉——透视端最爱看的正是这些）；也可切换为 enclosed，只伪装六面都被包住的方块。伪装方块按权重随机选取，支持按高度分层（深层深板岩、浅层石头），还能直接沿用「下方方块」让伪装更自然
按维度配置	主世界 / 地狱 / 末地各自配置「隐藏什么、伪装成什么、怎么伪装」；末地默认关闭。支持 tag(...) 写法（如 tag(diamond_ores) 自动展开为全部钻石矿）
世界黑名单 / 逐世界覆盖	主城、副本等不想伪装也不想省带宽的世界加入独立文件 blacklist.yml 即可同时豁免反矿透与带宽优化；也可以只给某个世界单独覆盖反矿透设置
邻近显形	玩家靠近被伪装的位置时主动还原真实方块。还原前做视线判定——隔着墙、隔着地层绝不会提前亮出来；支持事件即时显形（挖开/炸开方块时当 tick 修复），显形包合并发送
视锥剔除	只处理玩家当前看得到的方向，省带宽；内建安全下限，「玩家看得见的方块一定是真的」是硬保证
磁盘缓存	改写结果落盘，重启后直接复用，省掉重复判定与编码；区块内容或配置变化会自动失效重写，磁盘异常自动降级为纯内存运行
引导绕过	持有 mikuxraynet.bypass 权限的玩家看到真实世界（方便管理员排查）。该权限在玩家进入服务器时判定一次，运行中授予/撤销需让玩家重新进入才生效
判定纠错	内置遮挡判定提供的「人工纠正表」，发现某方块被误判时填注册名即可修正

默认隐藏清单（可在配置里自由增删）：主世界 16 种矿石 + 3 种粗金属块 + 箱子 + 刷怪笼 + 苔石；地狱为下界残骸 + 下界金矿 + 箱子 + 刷怪笼（默认不含地狱石英矿——分布广、价值低，藏了只会到处是假石头）。

带宽优化（Bandwidth）

在不改变玩家看到的内容的前提下减少封包数量与体积。

能力	说明
零位移包取消	纯位移包在位移全为 0 时直接不发（可白名单豁免盔甲架、展示框等）；朝向包一律放行——朝向是绝对量化角，「全 0」是合法的正南/平视，按全 0 取消会导致客户端朝向不同步
方块变更合并	玩家周围短时间内的多条方块变更合并成一条批量包；挖掘/放置半径内原包立即放行，不影响手感
调色板位宽预算	防止「替换方块导致区块封包膨胀」，并顺带清理无用的调色板条目，多数情况下封包更小
实体剔除	剔除被墙完全挡住的实体，带强制可见距离兜底（玩家自身、其它玩家、烟花始终放行）
视锥剔除	在「被墙挡住」之外，再剔除位于视野之外、且距离超过设定值的实体（玩家背后 / 侧后根本看不到的实体），连射线都省下；玩家转头后一个复检周期内自动补发。视锥数学与反矿透侧共用同一套，FOV 默认取客户端上限 110°，保证把 FOV 拉满也看不到被剔除的实体
AFK 降级	挂机玩家按距离丢弃粒子与方块破坏动画等低价值包
高延迟降视距	延迟持续超标的玩家自动降低视距，恢复正常后还原
运行摘要	定时在控制台输出一行精简摘要，随时掌握省包情况

---

二、注意事项

1. 依赖
   • PacketEvents 2.13.0+（必需）：缺失时插件直接禁用。
   • ProtocolLib 5.3.0+（必需）：它是封包拦截通道；缺失时插件仍能加载，但反矿透与带宽优化停用，仅保留配置与命令，便于排查。
   • 可选兼容：ViaVersion / ViaBackwards / Geyser-Spigot（自动识别加载顺序）。
2. 运行环境：Paper 26.2+ 或 Folia 26.x，Java 25；不支持 Java 17 及以下。Folia 兼容（世界访问一律走区域调度器），且已在 paper-plugin.yml 显式声明 folia-supported: true。只支持 Paper 系核心（Paper / Leaf / Folia）：jar 内只附带 paper-plugin.yml，不再附带传统 plugin.yml，纯 Bukkit/Spigot 核心无法加载本插件。
3. 配置文件：首次启动自动生成 antixray.yml、bandwidth.yml 与 blacklist.yml（世界黑名单，对两个模块同时生效），全部带中文注释，按服主视角说明每项作用；改完执行 /mikuxraynet reload 即时生效（少部分项需重启，命令会提示）。
4. 安全上下限：关键项都设了安全区间，配超范围会被自动钳制到安全值并在控制台提示一次。下限（例：视锥角度 110°、视锥豁免距离 16 格、降视距下限 6 格、磁盘缓存过期 1 天、实体视锥 FOV 30°）用来避免「玩家看得见假方块」或「看得到实体却被剔除」；上限（例：合并窗口 200ms、复检周期 40 tick、降视距幅度 4 格、邻近显形距离 128 格）用来避免手滑配出「明显延迟」或「拖慢服务器」的数值。
5. 缓存会失效重建：修改隐藏清单、伪装方块、遮挡规则、remove-block-entities、blacklist.yml 的世界名单、bandwidth.yml 的 palette 段（位宽预算 / 自检）、磁盘缓存的 zstd-sha256 等会改变改写结果的项，都会让磁盘缓存与内存缓存整体失效并自动重建一次；此外区块边界依赖的邻块贴边快照内容变化时，也会让对应条目自然失效重写。以上均属正常现象，之后命中率恢复。
6. 磁盘缓存占用：默认上限 20000 条约占 200~600 MB；过期时间从写入时刻起算，应大于两次开服的间隔（默认 7 天）。要限制占用请调 max-entries / max-file-size-mb。另可用 disk-cache.zstd-sha256 对自动下载的压缩库做摘要校验（默认留空＝不校验，但仍会打印实际 SHA-256 供你填入）；若缓存目录被另一个服务端实例同时占用，本实例会自动停用「被占用文件」的磁盘缓存（只提示一次，功能不受影响）。
7. 给主城减负：把主城 / 副本世界加入 blacklist.yml 的 world-blacklist，可同时跳过反矿透（省 CPU，也避免建筑被伪装）与带宽优化（不做实体剔除、变更合并等）；也可只单独覆盖反矿透设置（antixray.yml 的 world-overrides），此时带宽优化照常工作。黑名单优先级高于 world-overrides。
8. 全程 fail-open：任何超时、队列积压或异常都会放行原包，绝不卡住玩家或客户端加载。
9. 自带诊断：/mxnet status 查看完整统计，/mxnet dump 导出诊断文件；状态里有「安全阀触发」计数，正常运营下应恒为 0，非 0 请带 dump 反馈。

---

三、技术亮点

• 原生封包改写，不碰 NMS：直接在出站区块封包上做纯字节级编解码（复用 Netty ByteBuf），服务端版本升级不需要改代码，也不会因为内部类变动而崩服。
• 真异步扣包，网络线程零计算：通过 ProtocolLib 的异步通道拦截封包，回调只登记任务后立即让出；解码、遮挡判定、重编码全部在自有线程池完成，并设有队列上限与处理超时——积压的结果是放行，而不是卡玩家。
• 前置只当「启动期字典」用：PacketEvents 仅在启动时构建方块状态位图（空气 / 流体 / 遮挡 / 伪装权重），此后热路径零引用，不给封包链路增加任何额外开销。
• 自研磁盘缓存格式：32×32 区块一个区域文件、一个区块一条独立追加记录（改 1 个区块只重压 1 条，不再重压整桶）+ zstd 压缩（服务端缺失时自动回退内置压缩，并支持自动下载与镜像源）；每条负载携带「原始区块字节指纹 + 配置指纹 + 邻块快照内容指纹」多重校验，跨重启安全复用，内容、配置或邻块状态一变立刻自动重写。
• 内容指纹走硬件指令：区块内容指纹（每个区块封包都要校验一次）改用 JDK 内置的 CRC32C + CRC32 两个不同多项式组合（仍是 64 位强度）。本机实测 200 KB 负载从标量 FNV-1a 的约 143 µs 降到约 8.8 µs（1.4 GB/s → 22 GB/s，约 16 倍），且未采用「抽样指纹」——抽样会漏检未采样区间的单字节改动，那等于放行按旧内容改写的新区块，属不可接受的正确性风险。
• 显形索引用得省、发得也省：伪装坐标按区块共享（内存占用与玩家数无关），已显形坐标按玩家记录（天然有界）；一个巡检周期的显形数据用 Paper 原生批量包一次性发出，通常只产生「涉及区块段数」个包。
• 遮挡判定走异步位图：反矿透显形与实体剔除共用同一套遮挡判定（区块级遮挡位图 + 专用线程池异步射线），候选点只取暴露面，「只发玩家真正看得见的」，既省带宽也不隔着墙泄露；判定全程在网络线程之外完成，堵塞结果是放行而非卡玩家。
• 实体优化也守线程纪律：视锥剔除复用反矿透侧同一套视锥数学，并在每个玩家所属线程上做纯数学复判（不打射线），据此实现「转头后 ≤ 1 个复检周期补发」，全程不触碰任何实体 API。
• 面向 Folia 的线程纪律：Paper / Folia 双平台启动期自动判定；世界访问一律走区域调度器，跨区域访问严格规避，区域化多线程下同样稳定。
• 停用/热重载也做清理：Bukkit 会在 onDisable 之前就把插件置为 disabled，导致此时任何调度都会被拒绝——本插件在停用期改为同步恢复被隐藏的实体与降过的视距（跨区域时明确提示需重登），不会留下「看不见的怪」或「被降死的视距」。
• 内存纪律：缓存键只含世界名与坐标等基本类型，绝不持有 World / Chunk / Player / 封包对象，世界卸载即整体释放。
• 邻块快照位打包：用于消除区块边界漏洞的邻块贴边数据按每格 1 bit 存储（单条约 3 KB），并按列裁剪到地表高度；只在需要六面判定的模式下才抓取，默认模式完全不抓。
• 可观测性：改写 / 显形 / 实体隐藏 / 磁盘缓存 / 线程池水位 / 安全阀计数全部可在 /mxnet status 与 dump 中查看，任何异常都有一处可追的证据。

---

四、安装

1. 将 MikuXrayNet-x.y.z.jar 放入 plugins/。
2. 确保已安装前置 PacketEvents 与 ProtocolLib。
3. 启动服务端，自动生成两份带中文注释的配置；按需修改后 /mikuxraynet reload 生效。

---

五、命令与权限

命令	说明
/mikuxraynet status（别名 /mxnet、/mxr）	查看运行状态：依赖、平台、改写与显形统计、实体隐藏、磁盘缓存命中率、线程池水位
/mikuxraynet dump	导出完整诊断转储文件并回显路径
/mikuxraynet reload	热重载两份配置并重建周期任务

权限	说明	默认
mikuxraynet.admin	管理命令总权限（父节点，含 status / dump / reload）	OP
mikuxraynet.status	查看运行状态与统计	OP
mikuxraynet.dump	导出诊断转储	OP
mikuxraynet.reload	热重载配置	OP
mikuxraynet.bypass	绕过反矿透，看到真实世界（进入服务器时判定一次）	无

三个子命令权限可单独授予：只给 mikuxraynet.status 的玩家，补全里只出现 status、也只能执行它；mikuxraynet.admin 是这三者的父节点，授予 admin 即同时授予三者。