Paper anti-xray: engine modes 1, 2, 3, what they protect and their limits

"I turned on Paper's anti-xray, I'm covered." That is the sentence you read most often, and it rests on a misunderstanding: the built-in anti-xray does not detect anything. It hides. Those are two different jobs, and confusing them leaves a complete blind spot in your moderation.

What Paper's anti-xray actually does

The principle is server-side obfuscation: before sending terrain data to the client, the server replaces or hides certain blocks. The cheating player sees falsified information. One big advantage worth stressing: because everything happens server-side, no mod, texture pack or modified client can undo the protection.

The three engine modes

Which engine mode should you choose?

PaperMC's own recommended configuration for modes 2 and 3 includes air in hidden-blocks, while warning that it can drop the FPS of every player, cheaters or not. If players complain after you enable it, removing air from the list is the first thing to try.

Where to configure it

The setting lives in config/paper-world-defaults.yml for every world. To give a dimension its own settings (the Nether does not have the same ores), override it in that world's paper-world.yml. Paper's documentation uses world/dimensions/minecraft/the_nether/paper-world.yml for the Nether; on installs where the Nether has its own world_nether/ folder, the file goes there. On very old versions, the setting lived in paper.yml.

Ready-to-use configuration: engine-mode 2

These are the values recommended by PaperMC's documentation. For mode 3, keep the same lists and just change engine-mode: 2 to engine-mode: 3.

Overworld — config/paper-world-defaults.yml (replace the existing anticheat.anti-xray block):

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

Nether — the Nether's paper-world.yml:

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 2
    hidden-blocks:
    - air
    - ancient_debris
    - bone_block
    - glowstone
    - magma_block
    - nether_bricks
    - nether_gold_ore
    - nether_quartz_ore
    - polished_blackstone_bricks
    lava-obscures: false
    max-block-height: 128
    replacement-blocks:
    - basalt
    - blackstone
    - gravel
    - netherrack
    - soul_sand
    - soul_soil
    update-radius: 2
    use-permission: false

End — the End's paper-world.yml. There is nothing to hide there, so obfuscation is turned off:

anticheat:
  anti-xray:
    enabled: false

Ready-to-use configuration: engine-mode 1

Overworld — config/paper-world-defaults.yml:

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

Nether — the Nether's paper-world.yml:

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

The End: same as above, enabled: false.

What each setting does

• hidden-blocks — the blocks to hide: ores, plus air in modes 2 and 3 to cover ores exposed in caves.
• replacement-blocks — in modes 2 and 3, common blocks that are also swapped for fake ores, so real ores can't be told apart from them. Unused in mode 1, hence [].
• max-block-height — nothing above this height is hidden: no point processing the surface. 64 in the Overworld, 128 in the Nether.
• update-radius — the radius around a block the player interacts with (by mining it, for example) within which real block data is sent back.
• lava-obscures — also hides what is in contact with lava.
• use-permission — when true, players with paper.antixray.bypass (staff) see the world without obfuscation.

The distinction that changes everything: a lock, not a camera

A lock stops people getting in. A camera tells you who tried. Paper's anti-xray is an excellent lock — and there is no camera behind it.

In practice, the built-in anti-xray produces no trace at all: no log, no alert, no name. It cannot tell you that a player attempted anything, let alone who. If somebody gets through — and we are about to see that the official docs describe three ways to do so — they become completely invisible to you.

The three limits acknowledged by Paper's documentation

These are not outside criticisms: PaperMC documents them itself.

1. Ore exposed to air stays visible

In modes 1, 2 and 3, an ore in contact with air — typically on a cave wall — is not hidden. It is therefore visible to a cheating client just as it is to everyone else.

You can mitigate this in modes 2 and 3 by adding air to hidden-blocks, but the docs warn that it can tank the FPS of all your players, including those who do not cheat. The cure is often worse than the disease.

2. Range extension

Because world generation is deterministic, a client can exploit that regularity to extend what it infers beyond what the server actually sends it.

3. Seed recovery — the fundamental flaw

This is the most serious one. Since the world is generated deterministically from a seed, a client that manages to recover your world's seed knows the real location of every generated ore. Obfuscation then becomes entirely useless: it no longer even needs to look at what the server sends.

Paper's feature-seeds options, combined with the structure seed settings in spigot.yml, make the job harder. But the documentation is explicit: this is not a complete solution, and a client can still get there.

The fourth limit, a structural one

This one appears in no documentation, because it is not a technical defect: anti-xray only protects the future.

The day you enable it, everything that happened before stays out of reach. If a player x-rayed for six months, obfuscation changes nothing about it — your server's economy is already unbalanced, and you still have no way of knowing who is responsible. The only thing that can answer that question is your history.

What that means in practice

The two layers do not replace each other — they complement each other:

The key point is in the second-to-last row: the three documented bypasses above let someone see the ore, but none of them lets them collect it without breaking it. The mining behaviour always ends up in your logs. That is what makes after-the-fact analysis robust exactly where obfuscation gives way.

Key points

• Enable Paper's anti-xray: it is a good first layer, free and impossible to undo client-side.
• But it hides, it does not detect: no log, no alert, no name.
• PaperMC documents three bypasses itself: ore exposed to air, range extension, seed recovery.
• A cheater who gets through leaves no trace on the anti-xray side — only in your block history.
• And none of this says anything about what happened before you turned it on.

Technical details and limits verified against the official PaperMC documentation.

Keep reading