Anti-Xray on Your Minecraft Server: Turn On Paper's and Catch Cheaters

Why X-ray works (and why it can be stopped)

The server sends each player the blocks of the chunks near them, buried ones included. The normal game doesn't show them because stone covers them, but a resource pack with transparent stone or an X-ray mod does. The data is already on their computer: all the cheat does is draw it.

That's why banning it in the rules isn't enough: from the server you can't see which pack or mod each player has. What you can do is not send them the truth. Paper's anti-xray swaps buried ores for stone (or for fake ores) in what reaches the player, and only shows the real block when they get close to it by mining.

Paper has it, but turned off

It's in config/paper-world-defaults.yml, in the anticheat → anti-xray block, with enabled: false. You have to change it by hand. It applies to every world on the server; each world can also have its own paper-world.yml to change something in that world only, which is what we'll do with the Nether and the End.

It only exists in Paper and the servers built on it (Purpur, for example). On a modded server (Fabric, Forge, NeoForge) that file isn't there: what's left there is to watch and undo, as in the last section. If you're not sure which one you have, Paper, Fabric and Forge explained.

The three modes: which to choose

engine-mode: 1 (hide): replaces buried ores with the normal block for that place (stone, deepslate below y=0, netherrack in the Nether). Someone using X-ray sees a world with no ores. It's the lightest, especially for each player's computer. Its catch: it only hides ores fully surrounded by solid blocks; those touching cave air or water stay visible.

engine-mode: 2 (obfuscate): does the opposite, filling what can't be seen with fake ores everywhere. Someone using X-ray sees diamonds in every block and can't tell which are real. It stops cheating much better, but it sends more data and can cost the player some performance.

engine-mode: 3 (obfuscate by layer): like 2, but it picks one fake block for each layer of the chunk instead of one per block. According to Paper's documentation, it sends roughly half as much data as 2 when you join the server.

For a server of friends who know each other, 1 is enough and you won't notice it. For one open to strangers, 2 or 3: X-ray becomes useless for the people who really use it.

The recommended config for the overworld

It's the one Paper suggests in its official guide. Open config/paper-world-defaults.yml, find the anticheat: line and replace its whole anti-xray block with one of these two. Keep the spacing: YAML doesn't allow tabs and indentation matters.

max-block-height: 64 is how high hiding goes. Since 1.18, iron, coal and emeralds also generate in mountains, above 64: if you want to hide those too, raise it (the higher, the more work).

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 1
    hidden-blocks:
    - chest
    - coal_ore
    - deepslate_coal_ore
    - copper_ore
    - deepslate_copper_ore
    - raw_copper_block
    - diamond_ore
    - deepslate_diamond_ore
    - emerald_ore
    - deepslate_emerald_ore
    - gold_ore
    - deepslate_gold_ore
    - iron_ore
    - deepslate_iron_ore
    - raw_iron_block
    - lapis_ore
    - deepslate_lapis_ore
    - redstone_ore
    - deepslate_redstone_ore
    lava-obscures: false
    max-block-height: 64
    replacement-blocks: []
    update-radius: 2
    use-permission: false

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 2
    hidden-blocks:
    - air
    - copper_ore
    - deepslate_copper_ore
    - raw_copper_block
    - diamond_ore
    - deepslate_diamond_ore
    - gold_ore
    - deepslate_gold_ore
    - iron_ore
    - deepslate_iron_ore
    - raw_iron_block
    - lapis_ore
    - deepslate_lapis_ore
    - redstone_ore
    - deepslate_redstone_ore
    lava-obscures: false
    max-block-height: 64
    replacement-blocks:
    - chest
    - amethyst_block
    - andesite
    - budding_amethyst
    - calcite
    - coal_ore
    - deepslate_coal_ore
    - deepslate
    - diorite
    - dirt
    - emerald_ore
    - deepslate_emerald_ore
    - granite
    - gravel
    - oak_planks
    - smooth_basalt
    - stone
    - tuff
    update-radius: 2
    use-permission: false

What each line means

hidden-blocks: what gets hidden. In mode 1 it's the list of ores swapped for stone; in 2 and 3, it's also the list of fake blocks that get scattered.

replacement-blocks: modes 2 and 3 only. These are the blocks that can be swapped for fake ones (stone, deepslate, granite…). Mode 1 doesn't use it.

air in hidden-blocks (modes 2 and 3): also fills in fake holes, so not even caves show up properly with X-ray. It's the most effective against people looking for caves, but it can lower every player's FPS. If someone complains about stutters while exploring, remove it from the list.

update-radius: how many blocks from a broken block the real ones are revealed. 2 works well: raise it and nobody runs into ores that “appear” while mining.

use-permission: with true, operators and anyone with the paper.antixray.bypass permission see the real world. With false (recommended), nobody is exempt, you included.

Chests are only hidden if they're fully buried, like treasure: dungeon chests touch the air and there's no way to hide them.

The Nether and the End

The Nether needs its own list (ancient debris, nether gold and quartz ore, and up to height 128). It goes in the paper-world.yml of the Nether folder, which overrides the general settings in that world only. The End has no ores: it's best to turn it off there so it costs nothing.

Where they are: since Minecraft 26.1, in world/dimensions/minecraft/the_nether/paper-world.yml and world/dimensions/minecraft/the_end/paper-world.yml. In older versions, in world_nether/paper-world.yml and world_the_end/paper-world.yml. Paper creates it almost empty: paste the block below whatever it has (if it isn't there, create it with that name).

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 1
    hidden-blocks:
    - ancient_debris
    - nether_gold_ore
    - nether_quartz_ore
    lava-obscures: false
    max-block-height: 128
    replacement-blocks: []
    update-radius: 2
    use-permission: false

anticheat:
  anti-xray:
    enabled: false

What anti-xray can't hide

Ores in plain sight. Whatever touches cave air or lake water anyone can see, cheats or not. In mode 1 it stays that way; in 2 and 3, the fake blocks cover almost all of it, and more with air in the list.

The world seed. Some mods work out the seed from the terrain and, with it, know where every ore generated without needing to see them. Don't share the seed of an open server; Paper also has the feature-seeds → generate-random-seeds-for-all option in paper-world-defaults.yml, which changes where ores are placed in terrain generated from then on, though it isn't foolproof.

Seeing a bit further. Paper's documentation warns that, because of how it has to work, someone cheating may see real ores at a bit more than the usual distance. Closing that gap takes a separate anticheat plugin.

What's already been taken. Turning it on doesn't bring back the diamonds someone mined last week: that's what the next part is for.

Catching who already used it: CoreProtect

Someone mining with X-ray digs straight tunnels from diamond to diamond, never stopping for coal or iron, and comes out with far more than you find by playing. CoreProtect, which records who broke every block, makes it obvious. It only logs from when it's installed: add it as soon as possible (how, in the griefers guide).

Who has mined diamonds in the last 3 days: /co lookup a:-block i:diamond_ore,deepslate_diamond_ore t:3d. The same for a specific player, adding u:Name. In the Nether, with i:ancient_debris. If one of them has ten times more than the rest, go and look at their tunnels with /co inspect.

And if you confirm it, /co rollback u:Name t:3d undoes what they broke (the ores go back in place), and the rest is up to the server's rules: a warning, taking away what they mined or kicking them out.

How to do it at NapNodes

1. Make a backup

   In “Backups”, before touching anything (the free server has no backups: download the .yml files from “Files”).

2. Stop the server

   Press “Stop”. Paper reads these files on startup, so you edit them with the server stopped and they apply when you start it.

3. Edit paper-world-defaults.yml

   In “Files”, go into the config folder and open paper-world-defaults.yml: you edit it right in the panel. Find anticheat:, replace the anti-xray block with the one for the mode you chose and save.

4. The Nether and the End

   In “Files”, go into world → dimensions → minecraft → the_nether (in versions before 26.1, world_nether) and paste the Nether block at the end of paper-world.yml. Same in the_end with the one that turns it off.

5. Start it and check

   Press “Start”. If it doesn't start, check the “Console”: it's almost always an extra space in the YAML. To test it, join with an X-ray pack in your own game (with use-permission: false it affects you too) and look underground in an area nobody has explored.

Frequently asked questions