
ChunkVeil
ChunkVeil 是一款免费、开源的 Paper + ProtocolLib 反 X 射线和反 ESP 保护插件,专注于防止地下区块泄露。
大多数反 X 射线工具仅侧重于矿石隐藏。ChunkVeil 走得更远:它有助于隐藏地下区块、洞穴形状、隐藏房间、存储区域、方块实体、实体生成,并在修改后的客户端利用这些信息之前屏蔽后续的方块更新。
该插件专为希望在不引入完整游戏内反作弊系统的前提下,加强对抗 X 射线、ESP、自由视角侦察、洞穴发现、隐藏基地发现以及 PieChart 风格地下泄露的服务器管理员设计。
ChunkVeil 旨在减少客户端能获取的信息。它并不声称能让所有作弊客户端完全无法使用。
为什么使用 ChunkVeil?

- 非仅限矿石的反 X 射线 - 隐藏地下地形、矿石、洞穴和基地布局。
- 支持反 ESP - 可选择在隐藏其所在区块时同时隐藏地下实体。
- 抵抗自由视角(Freecam) - 直到玩家能够合理看到或到达之前,地下区块始终保持被遮蔽状态。
- 数据包级保护 - 当保护激活时,隐藏区块的数据包会在发送前被重写。包含真实地下方块数据的隐藏区块永远不会离开服务器;如果某个数据包无法安全重写,则直接取消发送而非发送出去。
- 方块更新保护 - 在区块被隐藏期间,后续的方块更改也会被遮蔽。
- 方块实体保护 - 低于受保护 Y 范围的隐藏方块实体更新数据包会被取消。
- 次要泄露防护 - 可取消隐藏的地下爆炸、世界事件、方块破坏动画和位置音效数据包。
- 基于视野的揭示机制 - 使用 360 度可见性扫描,而不是简单地根据半径揭示所有内容。
- 自适应扫描质量 - 可选的 TPS 感知光线减少功能,帮助繁忙的服务器保持刻时间(tick time)的可预测性。
- 按世界配置 - 可针对每个世界单独配置假方块、隐藏 Y 范围、空气隐藏、实体隐藏和玩家隐藏。
- 故障关闭式启动/运行时行为 - 如果 ProtocolLib 或原始区块重写不兼容,ChunkVeil 会禁用保护,而不是假装它是安全的。
- 经过测试,而非仅靠宣称 - CI 中运行了自动化的数据包回归测试套件,
/chunkveil verify 为管理员提供单一的通过/警告/失败保护检查。确切覆盖范围见:docs/COVERAGE.md
- 管理工具 - 包括状态查看、兼容性诊断、玩家检查、诊断报告、性能预测、重载、刷新、调试指标、权限管理和紧急禁用功能。
- 更新通知 - 当有与服务器精确 Minecraft 版本兼容的新版本发布时,管理员会收到带有下载链接的游戏内通知。
- 开源 - MIT 许可,易于审计。
要求

- Paper 1.21.x 或 26.x
- Java 21 或更高版本(Paper 26.x 本身需要 Java 25)
- 与你的 Paper/Minecraft 版本兼容的 ProtocolLib
ProtocolLib 的版本很重要。请选择与你的服务器版本匹配的构建:
ChunkVeil 以单个通用 jar 文件分发。已验证(Verified) 表示此确切组合已在运行此 ChunkVeil 版本的真实服务器上测试过。预期(Expected) 表示应该可以工作,但在发布前未进行测试。
| 服务器 |
ProtocolLib |
Java |
状态 |
| Paper 26.1.2 |
26.1 的最新开发构建 |
25 |
已验证 (ChunkVeil 0.5.0) |
| Paper 1.21.11 |
1.21.11 的最新构建 |
21+ |
已验证 (ChunkVeil 0.5.0) |
| Paper 1.21.8 |
5.4.0 |
21+ |
已验证 (ChunkVeil 0.5.0) |
| 其他 Paper 1.21.x / 26.x |
与该版本匹配的构建 |
21+ / 25 |
预期,未验证 |
| Spigot, Folia, pre-1.21 |
- |
- |
不支持 |
如果预期的组合出现异常,ChunkVeil 的设计原则是故障关闭以防止泄露,并且 /chunkveil compat 会告诉你出了什么问题。
工作原理

- 地下数据对玩家开始处于隐藏状态。
- 隐藏的地下方块被替换为可配置的假方块。
- ChunkVeil 使用视线扫描玩家实际可能揭示的区域。
- 当地图块变得可见或可达时,真实区块会被恢复。
- 后续隐藏的方块/实体更新在可能的情况下会被遮蔽或取消。
ChunkVeil 的核心规则:当保护激活时,一个隐藏的区块绝不会带着真实的地下方块数据离开服务器。 如果主要数据包重写路径无法启动,或在运行时出现关键的重写不兼容问题,不安全的数据包将被取消,ChunkVeil 将故障关闭——它会禁用保护,并在控制台和在线管理员处发出强烈警告。没有不安全的回退模式:保护要么按设计正常工作,要么明确处于关闭状态。
ChunkVeil 主要针对主世界(Overworld)进行设计。下界(Nether)和末地(End)可以进行配置,但默认情况下它们是禁用的,因为它们的地图结构和假方块选择通常需要单独的测试。
视觉对比
这些截图使用了类似 X 射线的视角,以便更容易看出差异。
无 ChunkVeil

禁用 ChunkVeil 后,修改后的客户端可以在玩家本不该知晓的情况下看到地下地形、洞穴、矿石、结构和隐藏空间。
启用 hide-air: false 的 ChunkVeil

这是推荐的默认设置。空气保持为空气,因此洞穴和空洞可能仍然显示为开放空间,但隐藏的实心方块会被替换为配置的假方块,例如 DEEPSLATE。这种方式速度更快,且在无需重写大量空气的情况下最大程度减少了有用的方块信息泄露。
启用 hide-air: true 的 ChunkVeil

当启用 hide-air 时,ChunkVeil 还会将地下的空气替换为假方块。这使得从客户端侧更难判断洞穴形状、房间布局和隐藏基地的结构,但代价更高,因为需要重写更多的方块。
与 Paper Anti-Xray 的兼容性
ChunkVeil 可以与 Paper 内置的 anti-xray 以及基于数据包插件(如 Orebfuscator)协同运行。Paper 的 anti-xray 通常在 ProtocolLib 接收到传出区块数据包之前运行,随后 ChunkVeil 会对玩家即将接收的数据包应用其地下隐藏处理。
为了获得最严格的保护,请使用 /chunkveil status、一个 XRay/Freecam 客户端,并根据你想要隐藏多少洞穴/基地形状,分别测试 hide-air: false 和 hide-air: true,以验证你的具体插件组合。
安装
- 安装 Paper 1.21.x 或 26.x。
- 安装 Java 21 或更高版本(Paper 26.x 需要 Java 25)。
- 安装与你 Paper 版本兼容的 ProtocolLib 构建版本。
- 将
ChunkVeil.jar 放入服务器的 plugins 文件夹中。
- 启动服务器一次,以生成
plugins/ChunkVeil/config.yml 和 plugins/ChunkVeil/lang.yml。
- 在游戏中或控制台中运行
/chunkveil status。
推荐默认配置
worlds:
world:
enabled: true
hide-below-y: 0
min-y: -64
default-fake-block: DEEPSLATE
hide-air: false
hide-entities: true
hide-players: false
对于大多数服务器,推荐使用 hide-air: false,因为它性能开销更小。当隐藏洞穴形状和隐藏基地布局比性能更重要时,请使用 hide-air: true。
命令
/chunkveil status - 显示运行时状态、世界列表、队列大小、重写状态和指标。
/chunkveil verify - 对整个保护状态进行一次 PASS/WARN/FAIL 检查:ProtocolLib、运行时、重写路径、故障、版本、世界、二级保护、其他数据包插件和配置。(/chunkveil compat 是其别名。)
/chunkveil inspect <player> - 显示玩家的当前 ChunkVeil 状态、可见区块数、队列计数、视距和绕过状态。
/chunkveil report - 创建诊断报告文件以用于故障排除。
/chunkveil predict <players> <ramGb> <cpuTier> [viewDistance] - 根据实时采样估算性能。
/chunkveil update - 立即检查是否有更新的兼容版本可用。
/chunkveil reload - 重新加载配置文件和语言文件。添加 --check 可验证磁盘上的配置而不应用它。
/chunkveil refresh - 强制对在线玩家进行重新扫描和刷新。
/chunkveil disable - 紧急开关,恢复在线玩家的真实区块。
/chunkveil enable - 重新启动运行时。
/chunkveil debug on|off - 切换调试指标。
/chunkveil version - 显示插件版本。
别名:/cv
权限
chunkveil.admin
chunkveil.status
chunkveil.verify
chunkveil.inspect
chunkveil.report
chunkveil.predict
chunkveil.update
chunkveil.reload
chunkveil.refresh
chunkveil.toggle
chunkveil.debug
chunkveil.version
chunkveil.bypass
首次测试指南
- 使用管理员账号加入服务器。
- 运行
/chunkveil verify 并阅读 PASS/WARN/FAIL 结果。
- 运行
/chunkveil status 查看计数器。
- 移动到配置好的
hide-below-y 以下的地下区域。
- 在洞穴或隧道内外移动。
- 测试
/chunkveil inspect <yourname>。
- 在提交错误报告前,先测试
/chunkveil report。
- 测试
/chunkveil refresh。
- 测试
/chunkveil disable 以恢复在线玩家的真实区块。
- 在测试期间使用
/chunkveil debug on。
更新通知
ChunkVeil 会定期检查 GitHub 上的小型版本清单,并在有适用于你当前 Minecraft 版本的新发布时通知拥有 chunkveil.update 权限的管理员。未声明与正在运行的服务器版本兼容的发布版本永远不会被推送。
该检查器仅读取版本元数据。它从不下载或安装任何内容。你可以在 config.yml 中将 update-checker.enabled: false 来禁用此功能。
匿名使用统计
ChunkVeil 使用 bStats 收集匿名的聚合使用统计数据:服务器数量、玩家数量、Minecraft/Java 版本,以及一些 ChunkVeil 特有的图表,例如 hide-air 的使用情况。绝不会发送任何世界数据、玩家数据或服务器地址。
你可以在 config.yml 中通过设置 metrics.enabled: false 来退出统计,或者在全局范围内(所有插件)通过 plugins/bStats/config.yml 退出。
错误报告
请在 GitHub 上报告错误:
请提供你的 ChunkVeil 版本、Paper 版本、ProtocolLib 版本、日志、配置以及复现步骤。
源代码

ChunkVeil
ChunkVeil is a free, open-source Paper + ProtocolLib anti-xray and anti-ESP protection plugin focused on underground chunk leaks.
Most anti-xray tools focus on ores. ChunkVeil goes further: it helps hide underground chunks, cave shapes, hidden rooms, storage areas, block entities, entity spawns, and later block updates before modified clients can use that information.
It is built for server admins who want stronger protection against xray, ESP, freecam scouting, cave discovery, hidden-base discovery, and PieChart-style underground leaks without adding a full gameplay anti-cheat.
ChunkVeil reduces what the client can learn. It does not claim to make every hacked client impossible to use.
Why Use ChunkVeil?

- Anti-xray for more than ores - Hide underground terrain, ores, caves, and base layouts.
- Anti-ESP support - Optionally hide underground entities while their chunk is hidden.
- Freecam resistance - Underground chunks stay masked until the player can realistically see or reach them.
- Packet-level protection - While protection is active, hidden chunk packets are rewritten before they are sent. A hidden chunk never leaves the server with real underground block data in it; a packet that cannot be rewritten safely is cancelled instead of sent.
- Block update protection - Later block changes are also masked while a chunk is hidden.
- Block entity protection - Hidden block entity update packets below the protected Y range are cancelled.
- Secondary leak protection - Can cancel hidden underground explosion, world event, block break animation, and positional sound packets.
- View-based reveals - Uses a 360-degree visibility scan instead of revealing everything in a simple radius.
- Adaptive scan quality - Optional TPS-aware ray reduction helps busy servers keep tick time predictable.
- Per-world config - Configure fake blocks, hidden Y ranges, air hiding, entity hiding, and player hiding per world.
- Fail-closed startup/runtime - If ProtocolLib or raw chunk rewriting is not compatible, ChunkVeil disables protection instead of pretending it is safe.
- Tested, not just claimed - An automated packet regression test suite runs in CI, and
/chunkveil verify gives owners a single PASS/WARN/FAIL protection check. Exact coverage: docs/COVERAGE.md
- Admin tools - Includes status, compatibility diagnostics, player inspect, diagnostic reports, performance prediction, reload, refresh, debug metrics, permissions, and emergency disable.
- Update notifications - Admins get an in-game notice with a download link when a newer release compatible with the server's exact Minecraft version is available.
- Open source - MIT licensed and easy to audit.
Requirements

- Paper 1.21.x or 26.x
- Java 21 or newer (Paper 26.x itself requires Java 25)
- ProtocolLib compatible with your Paper/Minecraft version
ProtocolLib version matters. Pick the build that matches your server version:
ChunkVeil ships as a single universal jar. Verified means this exact combination was run on a real server with this ChunkVeil release. Expected means it should work but was not run before release.
| Server |
ProtocolLib |
Java |
Status |
| Paper 26.1.2 |
newest dev build for 26.1 |
25 |
Verified (ChunkVeil 0.5.0) |
| Paper 1.21.11 |
newest build for 1.21.11 |
21+ |
Verified (ChunkVeil 0.5.0) |
| Paper 1.21.8 |
5.4.0 |
21+ |
Verified (ChunkVeil 0.5.0) |
| Other Paper 1.21.x / 26.x |
matching build for that version |
21+ / 25 |
Expected, not verified |
| Spigot, Folia, pre-1.21 |
- |
- |
Unsupported |
If an expected combination misbehaves, ChunkVeil is designed to fail closed rather than leak, and /chunkveil compat will tell you what went wrong.
How It Works

- Underground data starts hidden from the player.
- Hidden underground blocks are replaced with a configurable fake block.
- ChunkVeil scans what the player can realistically reveal using view rays.
- Real chunks are restored when they become visible or reachable.
- Later hidden block/entity updates are masked or cancelled where possible.
ChunkVeil's core rule: while protection is active, a hidden chunk never leaves the server with real underground block data in it. If the main packet rewrite path cannot start, or a critical rewrite incompatibility appears at runtime, the unsafe packet is cancelled and ChunkVeil fails closed — it disables protection and warns loudly in the console and to online admins. There is no insecure fallback mode: protection is either working as designed or unmistakably off.
ChunkVeil is primarily designed for the overworld. Nether and End can be configured, but they are disabled by default because their terrain and fake block choices usually need separate testing.
Visual Comparison
These screenshots use an xray-style view so the difference is easy to see.
Without ChunkVeil

With ChunkVeil disabled, underground terrain, caves, ores, structures, and hidden spaces can be visible to modified clients before the player should know about them.
ChunkVeil with hide-air: false

This is the recommended default. Air stays air, so caves and empty pockets may still appear as open space, but solid hidden blocks are replaced with the configured fake block, such as DEEPSLATE. This is faster and reduces the most useful block information without rewriting huge amounts of air.
ChunkVeil with hide-air: true

When hide-air is enabled, ChunkVeil also replaces underground air with the fake block. This makes cave shapes, rooms, and hidden base layouts much harder to read from the client side, but it costs more because many more blocks need to be rewritten.
Compatibility With Paper Anti-Xray
ChunkVeil can run alongside Paper's built-in anti-xray and packet-based plugins such as Orebfuscator. Paper anti-xray usually runs before ProtocolLib sees the outgoing chunk packet, and ChunkVeil then applies its underground hiding pass to the packet the player is about to receive.
For the strictest protection, test your exact plugin stack with /chunkveil status, an xray/freecam client, and both hide-air: false and hide-air: true depending on how much cave/base shape you want to conceal.
Installation
- Install Paper 1.21.x or 26.x.
- Install Java 21 or newer (Java 25 for Paper 26.x).
- Install a ProtocolLib build compatible with your Paper version.
- Put
ChunkVeil.jar in your server's plugins folder.
- Start the server once to generate
plugins/ChunkVeil/config.yml and plugins/ChunkVeil/lang.yml.
- Run
/chunkveil status in-game or from console.
Recommended Default
worlds:
world:
enabled: true
hide-below-y: 0
min-y: -64
default-fake-block: DEEPSLATE
hide-air: false
hide-entities: true
hide-players: false
hide-air: false is recommended for most servers because it is much lighter. Use hide-air: true when hiding cave shapes and hidden base layouts is more important than performance.
Commands
/chunkveil status - Shows runtime state, worlds, queue size, rewrite status, and metrics.
/chunkveil verify - One PASS/WARN/FAIL check of the whole protection state: ProtocolLib, runtime, rewrite path, failures, versions, worlds, secondary protection, other packet plugins, and config. (/chunkveil compat is an alias.)
/chunkveil inspect <player> - Shows a player's current ChunkVeil state, visible chunks, queue count, view distance, and bypass state.
/chunkveil report - Creates a diagnostic report file for troubleshooting.
/chunkveil predict <players> <ramGb> <cpuTier> [viewDistance] - Estimates performance from live timing samples.
/chunkveil update - Checks now whether a newer compatible release is available.
/chunkveil reload - Reloads config and language files. Add --check to validate the config from disk without applying it.
/chunkveil refresh - Forces a rescan and refresh for online players.
/chunkveil disable - Emergency switch that restores real chunks for online players.
/chunkveil enable - Starts the runtime again.
/chunkveil debug on|off - Toggles debug metrics.
/chunkveil version - Shows the plugin version.
Alias: /cv
Permissions
chunkveil.admin
chunkveil.status
chunkveil.verify
chunkveil.inspect
chunkveil.report
chunkveil.predict
chunkveil.update
chunkveil.reload
chunkveil.refresh
chunkveil.toggle
chunkveil.debug
chunkveil.version
chunkveil.bypass
Good First Test
- Join with an admin account.
- Run
/chunkveil verify and read the PASS/WARN/FAIL verdict.
- Run
/chunkveil status for counters.
- Go underground below the configured
hide-below-y.
- Move in and out of caves or tunnels.
- Test
/chunkveil inspect <yourname>.
- Test
/chunkveil report before reporting bugs.
- Test
/chunkveil refresh.
- Test
/chunkveil disable to restore real chunks for online players.
- Use
/chunkveil debug on while testing.
Update Notifications
ChunkVeil periodically checks a small version manifest on GitHub and tells admins (permission chunkveil.update) when a newer release is available for their exact Minecraft version. Releases that do not declare compatibility with the running server version are never offered.
The checker only reads version metadata. It never downloads or installs anything. Disable it with update-checker.enabled: false in config.yml.
Anonymous Usage Statistics
ChunkVeil uses bStats to collect anonymous aggregate usage statistics: server count, player counts, Minecraft/Java versions, and a few ChunkVeil-specific charts such as hide-air usage. No world data, no player data, and no server address is ever sent.
Opt out with metrics.enabled: false in config.yml, or globally for all plugins in plugins/bStats/config.yml.
Bug Reports
Please report bugs on GitHub:
Include your ChunkVeil version, Paper version, ProtocolLib version, logs, config, and reproduction steps.
Source Code
评论 0
登录后参与评分
还没有评论,来抢沙发吧