ChunkVeil - Speedgot

ChunkVeil -----

Anti-xray, anti-ESP, and freecam protection for underground chunks, caves, ores, and bases.

Installation

Install Paper 1.21.x.
Install Java 21.
Install a ProtocolLib build compatible with your exact Paper/Minecraft version:
https://www.spigotmc.org/resources/protocollib.1997/
Put ChunkVeil in your server's plugins folder.
Start the server once to generate plugins/ChunkVeil/config.yml and plugins/ChunkVeil/lang.yml.
Run /chunkveil status.
Run /chunkveil compat and check for warnings.

Important: ChunkVeil depends on ProtocolLib. If ProtocolLib is missing, incompatible, or raw chunk packet rewriting cannot initialize, ChunkVeil fails closed and disables runtime protection instead of running in a weaker fallback mode.

Default Overworld Config

Code (Text):

worlds:
world:
enabled: true
hide-below-y: 0
min-y: -64
default-fake-block: DEEPSLATE
hide-air: false
hide-entities: true
hide-players: false

Recommended Settings

hide-air: false is recommended for most servers. It keeps underground air visible and only fakes non-air blocks. This is much lighter and still hides the most useful block information.

hide-air: true also replaces underground air with the fake block. This is stronger for hiding caves, rooms, tunnels, and hidden-base layouts, but it costs more CPU.

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

hide-players: false is recommended for most servers because hiding players can affect PvP, moderation, and player visibility.

default-fake-block should be a solid block that fits the world. Good examples are DEEPSLATE for the overworld, NETHERRACK for the Nether, and END_STONE for the End.

Performance Settings

ChunkVeil includes work budgets so admins can tune how much work is done per tick.

Code (Text):

performance:
max-priority-chunk-updates-per-player-per-tick: 24
max-regular-chunk-updates-per-player-per-tick: 1
entity-scan-interval-millis: 500
entity-scan-max-entities-per-player: 256
view-reveal-yaw-cache-bucket-degrees: 5
adaptive-scan-quality:
enabled: false
reduce-rays-below-tps: 18.5
minimum-front-horizontal-rays: 6
minimum-side-horizontal-rays: 3
minimum-back-horizontal-rays: 1
minimum-vertical-rays: 6

Adaptive scan quality is optional. When enabled, ChunkVeil can reduce reveal ray counts while TPS is below the configured threshold. This can help busy servers, but lower ray counts can make reveals less precise.

Packet Protection Settings

Code (Text):

packet-protection:
cancel-explosions: true
cancel-world-events: true
cancel-block-crack: true
cancel-positional-sounds: true

These options reduce extra underground leaks from packet types beyond chunk data, such as explosion packets, world event packets, block break animations, and positional sounds.

Commands

/chunkveil status - Shows runtime state, worlds, queues, protection counters, and timing metrics.
/chunkveil compat - Shows Minecraft, Paper, Java, ProtocolLib, rewrite status, runtime state, and warnings.
/chunkveil inspect <player> - Shows a player's world, bypass state, view distance, visible chunks, queued chunks, hidden entities, last scan age, and current chunk state.
/chunkveil report - Creates a diagnostic report file in plugins/ChunkVeil/reports.
/chunkveil predict <players> <ramGb> <cpuTier> [viewDistance] - Estimates performance from live timing samples. CPU tier is low, mid, high, or top based on single-core performance.
/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 periodic 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

Join with an admin account.
Run /chunkveil status.
Run /chunkveil compat and check for warnings.
Go underground below the configured hide-below-y.
Move in and out of caves, tunnels, or hidden rooms.
Run /chunkveil inspect <yourname>.
Run /chunkveil report and confirm a report file is created.
Test /chunkveil refresh.
Test /chunkveil disable to restore real chunks for online players.
Use /chunkveil debug on while testing.

Troubleshooting

ChunkVeil says runtime protection is disabled

Run /chunkveil compat. If the raw chunk packet rewrite is disabled, update ProtocolLib to a build compatible with your exact Paper/Minecraft version and restart the server.

ProtocolLib is installed but ChunkVeil fails closed

This usually means the installed ProtocolLib build cannot expose the required chunk packet internals for your server version. ChunkVeil intentionally refuses fallback masking because real underground data could leak before fake updates arrive.

/chunkveil predict says not enough live timing data

Move around underground, load chunks, let entity scans run, and try again. Prediction intentionally requires live samples so it does not give misleading estimates.

Cave shapes are still visible

Use hide-air: true for stronger cave and hidden-base shape protection. This costs more CPU, so test it with /chunkveil status and /chunkveil predict.

Reporting Bugs

Please include: