ChunkVeil

What is ChunkVeil?

ChunkVeil is a free, open-source Paper + ProtocolLib anti-xray protection plugin focused on underground information leaks.

Most anti-xray plugins focus mainly on ores. ChunkVeil is designed to protect more of the underground world: caves, hidden bases, underground rooms, block entities, entity spawns, and later block updates can all leak useful information to modified clients.

ChunkVeil helps reduce xray, ESP, freecam scouting, hidden-base discovery, cave discovery, ore scouting, and PieChart-style underground leaks. It does not claim to make every hacked client impossible to use, and it is not a full gameplay anti-cheat.

Why Server Admins Use It

• More than ore obfuscation - Helps hide caves, underground terrain, ores, hidden rooms, and base layouts.
• Anti-ESP support - Optionally hides underground entities while their chunk is hidden.
• Freecam resistance - Underground chunks stay masked until the player can realistically see or reach them.
• Packet-level chunk masking - Rewrites outgoing hidden underground chunk sections before the client receives them when supported.
• Configurable fake blocks - Replaces hidden blocks with a per-world fake block such as DEEPSLATE, NETHERRACK, or END_STONE.
• View-based reveals - Reveals chunks with a visibility scan instead of exposing everything in a simple radius.
• Persistent reveals - Keeps revealed chunks visible until they leave the player's render distance.
• Block update protection - Rewrites later block update packets while a chunk is hidden.
• Block entity protection - Cancels hidden block entity update packets below the protected Y range.
• Secondary leak protection - Can cancel hidden underground explosion, world event, block break animation, and positional sound packets.
• Adaptive scan quality - Optional TPS-aware ray reduction helps busy servers keep tick time predictable.
• Fail-closed safety - If ProtocolLib or raw chunk rewriting is not compatible, ChunkVeil disables runtime protection instead of pretending it is safe.
• Admin tools - Status, compatibility diagnostics, player inspect, diagnostic reports, performance prediction, reload, refresh, debug metrics, permissions, and emergency runtime disable.

Requirements

• Paper 1.21.x or 26.x
• Java 21
• ProtocolLib compatible with your Paper/Minecraft version

Important: ProtocolLib version matters. Use a ProtocolLib build compatible with your server version.

ProtocolLib:
https://www.spigotmc.org/resources/protocollib.1997/

ChunkVeil is tested on Paper 1.21.11 and Paper 26.1.2. Other Paper 1.21.x and 26.x builds are expected to work when paired with a compatible ProtocolLib build, but they are not all tested before each release.

How It Works

1. Underground data starts hidden from the player.
2. Hidden underground blocks are replaced with a configurable fake block.
3. ChunkVeil scans what the player can realistically reveal using view rays.
4. Real chunks are restored when they become visible or reachable.
5. Later hidden block/entity updates are masked or cancelled where possible.

If the main packet rewrite path cannot start, or if a critical packet rewrite incompatibility appears at runtime, ChunkVeil fails closed and disables its runtime protection. This avoids giving admins false confidence when underground data cannot be hidden before send.

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 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.

ChunkVeil uses a late ProtocolLib packet priority and declares Orebfuscator as an optional soft dependency so, when both plugins are installed, ChunkVeil is more likely to apply its hidden-chunk rewrite after other packet modifiers. Hidden chunks and hidden block updates are still rewritten for players who already have the chunk loaded.

If another plugin rewrites the same chunk, block-change, or multi-block-change packets after ChunkVeil, that plugin may change the final fake block appearance. It should not reveal real underground blocks unless that plugin deliberately restores real block data.

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

1. Install Paper 1.21.x.
2. Install Java 21.
3. Install ProtocolLib compatible with your Paper version: https://www.spigotmc.org/resources/protocollib.1997/
4. Put ChunkVeil in your server's plugins folder.
5. Start the server once to generate config.yml and lang.yml.
6. Run /chunkveil status in-game or from console.

Default Overworld Config

Recommended Settings

hide-air: false is recommended for most servers. It keeps air visible and only fakes non-air underground blocks, which is much lighter.

hide-air: true is stronger for hidden-base protection because it also hides cave shapes and empty rooms, but it costs more.

hide-entities: true hides underground mobs, item drops, minecarts, armor stands, and similar entities while their chunk is hidden.

hide-players: false is the default because hiding players can affect PvP and moderation.

Commands

• /chunkveil status - Shows runtime state, worlds, queue size, rewrite status, and metrics.
• /chunkveil compat - Shows server, Java, ProtocolLib, rewrite, runtime, and warning diagnostics.
• /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 reload - Reloads config and language files.
• /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 - Allows all ChunkVeil admin commands.
• chunkveil.status
• chunkveil.compat
• chunkveil.inspect
• chunkveil.report
• chunkveil.predict
• chunkveil.reload
• chunkveil.refresh
• chunkveil.toggle
• chunkveil.debug
• chunkveil.version
• chunkveil.bypass - Bypasses all hiding for the player.

Recommended First Test

1. Join with an admin account.
2. Run /chunkveil status.
3. Run /chunkveil compat and check for warnings.
4. Go underground below the configured hide-below-y.
5. Move in and out of caves, tunnels, or hidden rooms.
6. Test /chunkveil inspect <yourname>.
7. Test /chunkveil report before reporting bugs.
8. Test /chunkveil refresh.
9. Test /chunkveil disable to restore real chunks for online players.
10. Use /chunkveil debug on while testing.

Links

• Source Code: https://github.com/DeKaeyman/ChunkVeil
• Bug Reports: https://github.com/DeKaeyman/ChunkVeil/issues
• Releases: https://github.com/DeKaeyman/ChunkVeil/releases
• ProtocolLib: https://www.spigotmc.org/resources/protocollib.1997/