Article

Paper's anti-xray: what it protects, and what it will never detect

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

Updated 22 August 2026

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

Where to configure it

On recent Paper versions the setting is per world, in config/paper-world-defaults.yml for the defaults, or in a specific world's paper-world.yml (on older versions it lived in paper.yml):

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 1
    max-block-height: 64
    update-radius: 2
    lava-obscures: false
    use-permission: false
    hidden-blocks:
      - diamond_ore
      - deepslate_diamond_ore
      - ancient_debris
      # ...
    replacement-blocks:
      - stone
      - deepslate

• max-block-height — the height above which nothing is hidden any more. No point processing the surface.
• update-radius — update radius around a modified block.
• lava-obscures — also hides what is in contact with lava.
• use-permission — lets paper.antixray.bypass disable obfuscation for specific players (staff).
• replacement-blocks — unused in engine-mode: 1.

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.