Описание
# 🛡️ Meow Anti-Xray
> Server-side anti-xray for Fabric and NeoForge survival servers.
> ⛏️ Paper-style ore obfuscation, 🚀 no client install, 🔌 one shared core across both loaders.
`Meow Anti-Xray` focuses on one job: bringing a Paper-like anti-xray experience to modded dedicated servers. Players join normally with a vanilla or modded client, while the server rewrites chunk packets before they are sent, hiding unexposed valuable blocks from xray clients.
This project was split from `MeowConsole` and now contains only anti-xray functionality. Console utilities, sleep features, player-message helpers, and unrelated tools were removed so the mod stays lightweight, focused, and easier to profile.
[](https://modrinth.com/mod/meowanti-xray) [](https://github.com/xiaoyiluck666/MeowAnti-Xray/wiki) [](https://github.com/xiaoyiluck666/MeowAnti-Xray) [](https://github.com/xiaoyiluck666/MeowAnti-Xray/issues/new/choose) [](https://www.paypal.com/paypalme/neworldcn) [](https://afdian.com/a/xiaoyiluck)
## ✨ Why Use Meow Anti-Xray
- 🚀 **Server-side only**: Install it on the server; players do not need to install anything.
- 🧭 **Paper-style behavior**: Uses an engine mode 2 inspired default setup and tracks Paper-style hidden blocks, replacement blocks, reveal updates, and neighbor refresh behavior.
- 🔌 **Built for modded servers**: Fabric and NeoForge share the same anti-xray core, keeping configuration and behavior aligned across loaders.
- 🧱 **Safer decoys**: Block entities such as chests and ender chests are excluded from fake ore candidates, reducing visual glitches and confusing client-side states.
- ⚡ **Stable under exploration load**: Async chunk packet rewriting uses bounded backpressure to avoid unbounded snapshot queues and memory spikes.
- 📊 **Config checks without risky fallback**: `/antixray config` shows the active configuration, `/antixray validate` checks the file on disk without applying it, and `/antixray reload` applies only validated changes atomically. Failures preserve both the file and last-known-good protection.
## 🧩 Features
- 💎 Hides diamonds, ancient debris, redstone, lapis, gold, and other valuable blocks.
- 🪨 Replaces hidden blocks client-side with configurable decoy states.
- 🔍 Reveals nearby real blocks when players mine, start breaking blocks, or explosions modify terrain.
- 🌍 Supports separate settings for the Overworld, Nether, End, and custom dimensions.
- ⚙️ Supports per-dimension height ranges, hidden block lists, replacement block lists, and enable switches.
- 🔐 Supports permission bypass through `paper.antixray.bypass` or a custom permission node.
- 📣 Checks Modrinth for updates asynchronously and shows the latest status in `/antixray status`.
## 🌐 Compatibility
Version `1.7.0` targets Minecraft `26.3` and Java `25`:
- Fabric: Fabric Loader `>=0.19.5`, Fabric API `>=0.161.0+26.3`, Minecraft `>=26.3 =26.3.0.16-beta`, Minecraft `[26.3,26.4)`.
## ⚙️ Performance Model
The expensive part of anti-xray protection happens when players load new chunks. Meow Anti-Xray moves chunk packet rewriting away from the main thread when possible and limits queued async work with `async-queue-size`:
```yml
anti-xray:
async-chunk-rewrite: true
async-worker-threads: 1
async-queue-size: 16
```
The default favors memory safety. Servers with more memory or heavy exploration traffic can try `32` or `64`, then use `/antixray profile` to watch for sync fallback and rewrite timings.
Paper can hook directly into vanilla chunk packet serialization. A Fabric / NeoForge mod has to keep enough snapshot data to rewrite packets safely across loaders. This project aims for Paper-style protection with an implementation tuned for the mod loader environment, not a line-by-line copy of Paper internals.
## 📈 Stress-Tested
Meow Anti-Xray has been tested with real exploration and heavy chunk-loading workloads. The numbers below come from local Fabric / NeoForge dev servers, spark profiler reports, and the project's network fake-player load runner. The goal was to verify stable chunk packet rewriting under real loading pressure.
| Scenario | Result |
| --- | --- |
| 🧪 Fabric 1.5.0 default queue with 8 network fake players | Three 90-second samples averaged `427.17 chunks/s`, `0` client errors |
| 🔥 NeoForge 1.5.0 default queue with 8 network fake players | Three 90-second samples averaged `390.07 chunks/s`, `0` client errors |
| 🚀 Fabric queue=32 tuning screen | Three samples averaged `497.28 chunks/s`; kept as a manual tuning option |
| 🚀 NeoForge queue=32 tuning screen | Three samples averaged `462.82 chunks/s`; watch pressure in `/antixray profile` |
| 🛡️ Default policy | `async-queue-size=16`, favoring convergence and memory stability |
The 1.5.0 dual-loader matrix shows that the default `16` gives the best balance between throughput, convergence, and pressure. Queues `32` and `64` can increase throughput, but reach saturated pressure more often; server owners should tune them only while watching `/antixray profile` and available memory. See `reports/1.5.0-pressure-matrix.md` for the complete matrix.
- 🧪 Fabric real exploration:
- 🔥 NeoForge 8 fake players, conservative default queue:
- 🚀 NeoForge 8 fake players, higher-throughput queue:
## 🌍 Good Fit For
- 🧱 Fabric / NeoForge survival servers
- 🤝 Public, semi-public, and friend-group servers
- 🛡️ Servers that want strong anti-xray protection while staying in the modded ecosystem
- 🗺️ Pregenerated worlds, high-view-distance servers, frequent teleport routes, and active exploration
- 🐾 Servers migrating from the old MeowConsole built-in anti-xray module
Pregeneration or chunk preloading does not bypass this mod. It works when chunk packets are sent to player clients; it does not modify stored world data. Web maps and offline renderers that read real chunk data directly need their own hiding or rendering configuration.
## 🚀 Quick Start
1. Download the jar for your loader from Modrinth: use the Fabric file for Fabric servers and the NeoForge file for NeoForge servers.
2. Put the jar in the server `mods` folder.
3. Start the server once to generate:
```text
config/meowantixray.yml
```
4. Tune hidden blocks, replacement blocks, height ranges, and async settings for your server.
5. Run `/antixray validate` first, then `/antixray reload`; use `/antixray status` and `/antixray profile` to check runtime state.
Common config example:
```yml
anti-xray:
engine-mode: 2
max-block-height: 64
hidden-blocks: ["minecraft:diamond_ore", "minecraft:deepslate_diamond_ore"]
replacement-blocks:
- minecraft:stone
- minecraft:deepslate
dimension-settings:
nether:
hidden-blocks:
- minecraft:ancient_debris
replacement-blocks:
- minecraft:netherrack
```
Existing config files are supplemented with newly added missing keys during load without overwriting your values. Quoted values, quoted list items, inline lists, and dimension aliases such as `nether` / `end` are supported. Explicit empty inline lists such as `hidden-blocks: []` are also preserved as intentional configuration.
## 🧰 Commands
```text
/antixray status
/antixray config
/antixray validate
/antixray reload
/antixray profile
/antixray debug
/antixray inspect
```
## 🔗 Links
- GitHub:
- Issues:
- Modrinth:
- Original MeowConsole project:
- PayPal donations:
- Afdian donations:
---
# 🛡️ Meow Anti-Xray
> 为 Fabric 与 NeoForge 生存服准备的服务端反矿透模组。
> ⛏️ Paper 风格矿物伪装，🚀 客户端零安装，🔌 双 Loader 共用同一套核心逻辑。
`Meow Anti-Xray` 专注解决一个问题：让 Mod 服务端也能拥有接近 Paper Anti-Xray 的矿物隐藏体验。玩家不需要安装客户端模组，服务端会在区块发送给客户端之前重写区块包，把未暴露的矿物伪装成普通方块，从源头降低矿透收益。
本项目从 `MeowConsole` 拆分而来，现在只保留反矿透相关能力。没有控制台工具、睡眠功能、玩家消息等额外模块，目标是更轻、更纯粹，也更容易排查性能。
[](https://modrinth.com/mod/meowanti-xray) [](https://github.com/xiaoyiluck666/MeowAnti-Xray/wiki) [](https://github.com/xiaoyiluck666/MeowAnti-Xray) [](https://github.com/xiaoyiluck666/MeowAnti-Xray/issues/new/choose) [](https://www.paypal.com/paypalme/neworldcn) [](https://afdian.com/a/xiaoyiluck)
## ✨ 为什么选择 Meow Anti-Xray
- 🚀 **服务端安装即可生效**：玩家无需安装任何客户端内容，适合公开服、好友服和整合包服务端。
- 🧭 **Paper 风格体验**：默认按接近 Paper engine mode 2 的方式隐藏矿物，并持续对齐 Paper 风格的默认隐藏方块、替换方块、显露更新和邻近刷新行为。
- 🔌 **专为 Mod 服务端维护**：Fabric 与 NeoForge 共用核心逻辑，尽量保持配置、行为和性能策略一致。
- 🧱 **更安全的假矿处理**：箱子、末影箱等方块实体不会被用作假矿候选，减少客户端显示异常和误导性画面。
- ⚡ **高压跑图更稳**：异步区块包重写配合队列背压，避免大量区块快照无限堆积导致内存暴涨。
- 📊 **配置可检查、失败不误伤**：`/antixray config` 显示当前生效配置，`/antixray validate` 在不应用配置的前提下检查磁盘文件，`/antixray reload` 只有验证通过才原子生效；失败时保留原文件与最后一次有效防护。
## 🧩 核心功能
- 💎 隐藏钻石、远古残骸、红石、青金石、金矿等高价值方块。
- 🪨 使用可配置的替换方块填充客户端视野，降低矿透可用信息。
- 🔍 玩家挖掘、开始破坏方块、爆炸改变地形时，会刷新附近真实方块。
- 🌍 支持主世界、下界、末地和自定义维度分别配置。
- ⚙️ 支持隐藏高度范围、隐藏方块列表、替换方块列表和维度开关。
- 🔐 支持权限绕过：可配置 `paper.antixray.bypass` 或自定义权限节点。
- 📣 启动时异步检查 Modrinth 新版本，并在 `/antixray status` 中显示当前状态。
## 🌐 版本兼容
当前 `1.7.0` 版本面向 Minecraft `26.3` 与 Java `25`：
- Fabric：Fabric Loader `>=0.19.5`，Fabric API `>=0.161.0+26.3`，Minecraft `>=26.3 =26.3.0.16-beta`，Minecraft `[26.3,26.4)`。
## ⚙️ 性能设计
反矿透最重的工作发生在玩家加载新区块时。Meow Anti-Xray 会尽量把区块包重写放到后台线程，并通过 `async-queue-size` 限制待处理任务数量：
```yml
anti-xray:
async-chunk-rewrite: true
async-worker-threads: 1
async-queue-size: 16
```
默认值优先保证内存安全。服务器内存充足、玩家经常高速跑图或传送时，可以尝试把 `async-queue-size` 调到 `32` 或 `64`，再通过 `/antixray profile` 观察是否出现明显同步 fallback。
需要说明的是：Paper 可以在原生区块包序列化阶段直接接入；Fabric / NeoForge 模组层需要保留必要快照才能异步处理。因此本项目追求的是“Paper 风格效果 + 适合 Mod Loader 的高性能实现”，不是机械照搬 Paper 源码。
## 📈 压测验证
Meow Anti-Xray 不只停留在功能实现，也做过真实跑图和高压区块加载测试。下面数据来自本地 Fabric / NeoForge dev server、spark profiler 与项目内网络假玩家压测工具，重点验证的是“区块包重写在真实加载压力下是否稳定”。
| 场景 | 结果 |
| --- | --- |
| 🧪 Fabric 1.5.0 默认队列，8 个网络假玩家 | 3 次 90 秒样本平均 `427.17 chunks/s`，客户端错误 `0` |
| 🔥 NeoForge 1.5.0 默认队列，8 个网络假玩家 | 3 次 90 秒样本平均 `390.07 chunks/s`，客户端错误 `0` |
| 🚀 Fabric queue=32 调优筛选 | 3 次样本平均 `497.28 chunks/s`，保持为手动调优选项 |
| 🚀 NeoForge queue=32 调优筛选 | 3 次样本平均 `462.82 chunks/s`，需结合 profile 观察压力 |
| 🛡️ 默认策略 | `async-queue-size=16`，优先保证异步任务收敛和内存稳定 |
1.5.0 双 Loader 矩阵显示，默认 `16` 在吞吐、任务收敛和压力之间更均衡；`32`/`64` 虽然可以提高吞吐，但更容易进入饱和压力状态，建议服主结合 `/antixray profile` 和机器内存手动调整。完整矩阵记录见 `reports/1.5.0-pressure-matrix.md`。
- 🧪 Fabric 真实跑图：
- 🔥 NeoForge 8 假玩家，默认保守队列：
- 🚀 NeoForge 8 假玩家，更高吞吐队列：
## 🌍 适合哪些服务器
- 🧱 Fabric / NeoForge 生存服
- 🤝 公益服、半公开服、好友服
- 🛡️ 希望使用 Mod 生态，但仍然需要强反矿透的服务器
- 🗺️ 使用预生成地图、高视距、频繁传送或多人跑图的服务器
- 🐾 想从 MeowConsole 内置反矿透迁移到独立反矿透模组的服务器
预生成或预加载地图不会绕过本模组。它在区块发送给玩家客户端时生效，而不是在区块生成时修改世界数据。网页地图、离线渲染器等直接读取服务端真实区块数据的工具，需要使用它们自己的隐藏或渲染配置。
## 🚀 快速开始
1. 从 Modrinth 下载与你的 Loader 匹配的 jar：Fabric 下载 Fabric 文件，NeoForge 下载 NeoForge 文件。
2. 把 jar 放入服务端 `mods` 目录。
3. 启动服务端，生成配置文件：
```text
config/meowantixray.yml
```
4. 根据服务器类型调整隐藏方块、替换方块、高度范围和异步参数。
5. 先用 `/antixray validate` 预检，再用 `/antixray reload` 应用；使用 `/antixray status` 与 `/antixray profile` 检查运行状态。
常用配置示例：
```yml
anti-xray:
engine-mode: 2
max-block-height: 64
hidden-blocks: ["minecraft:diamond_ore", "minecraft:deepslate_diamond_ore"]
replacement-blocks:
- minecraft:stone
- minecraft:deepslate
dimension-settings:
nether:
hidden-blocks:
- minecraft:ancient_debris
replacement-blocks:
- minecraft:netherrack
```
旧配置加载时会自动补齐新增但缺失的键，不会覆盖你已经写好的值。配置支持带引号的值、带引号的列表项、内联列表，以及 `nether` / `end` 这类维度别名；像 `hidden-blocks: []` 这样的显式空列表也会按你的配置原样保留。
## 🧰 常用命令
```text
/antixray status
/antixray config
/antixray validate
/antixray reload
/antixray profile
/antixray debug
/antixray inspect
```
## 🔗 链接
- GitHub：
- 问题反馈：
- Modrinth：
- MeowConsole 原项目：
- PayPal 捐赠：
- 爱发电捐赠：