Stop X-ray cheating on your Minecraft server

X-ray cheats let a player see ores through solid rock. Paper has a built-in defence for this called Anti-Xray. It is obfuscation: the server sends players altered block data, with other blocks in place of many real ores, so a cheating client sees fewer of the real ores. It is switched off until you turn it on, and it is a Paper feature.

Checked against Paper 26.3 and the PaperMC Anti-Xray documentation, October 2026.

Pick an engine mode

Paper's documentation describes three modes:

• engine-mode: 1 swaps the blocks you list in hidden-blocks for plain stone (deepslate below y 0), netherrack or end stone, depending on the dimension. It is the cheapest for players' computers. It only hides ores completely surrounded by solid blocks, so an ore showing in a cave wall stays visible.
• engine-mode: 2 replaces both the hidden blocks and the replacement-blocks with randomly placed fake ores. Paper says it may better prevent Xray.
• engine-mode: 3 works like mode 2 but randomises each layer of a chunk. Paper says it can halve the network load when joining.

This guide uses mode 1. The documentation has ready-made blocks for the other two.

Turn it on for the Overworld

1. Open the File Manager and go into the config folder.
2. Double-click paper-world-defaults.yml, or select it and press Edit.
3. Find the anticheat: section with anti-xray: inside it and replace that block with the one below. Keep the spaces exactly as shown and do not use tab characters.
4. Press Save, then press Restart on the Console tab.

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

Always restart after a change. Paper's documentation says not to use /reload for Anti-Xray.

Set the Nether and the End

The file above is the default for every world, and Paper's documentation gives the Nether its own block, with Nether ores. From Minecraft 26.1, Paper keeps one paper-world.yml per dimension. Open world/dimensions/minecraft/the_nether/paper-world.yml and add this under the _version line that is already there:

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

For The End, add anticheat: with anti-xray: and enabled: false inside it to world/dimensions/minecraft/the_end/paper-world.yml, which is what Paper's documentation recommends. On older versions the same file sits in that dimension's world folder.

What it does not hide

• Ores above max-block-height. Newer versions generate some ores higher than 64, so raise it if you see them.
• Ores touching air, such as in caves, in mode 1. Modes 2 and 3 can hide them if you add air to hidden-blocks, which may lower frame rates for some players.
• Ores a cheater can compute if they learn your world seed. Do not share it (Find your world seed).

Paper says Anti-Xray alone stops most cheaters but is not infallible, and an anti-cheat plugin covers the rest.

Let staff see everything

Set use-permission: true and give staff the paper.antixray.bypass permission. Paper warns that this check can strain older permission plugins, so use it with a current one such as LuckPerms. With it on, operators also bypass Anti-Xray, which can make it look broken when you test as an operator.

If you are new to these files, read Edit bukkit.yml, spigot.yml and Paper config first.