Paper Anti-Xray: How to Set It Up and Choose an Engine Mode
Paper ships with an anti-xray system that hides ores from cheating clients by sending fake blocks. It works per world, has three modes, and is enabled in Paper's recommended configuration. If you want to tune it, the settings are in paper-world-defaults.yml under anticheat then anti-xray.
This guide explains the modes, the recommended values, how to apply a change, and the limits. It was checked on 2026-11-15 against the Paper documentation. It only applies to Paper and forks that include the feature, so see Paper vs Spigot vs Purpur vs Vanilla if you are unsure what you are running. Anti-xray reduces cheating, but it does not remove it, and the section on limits matters as much as the setup.
- Edit
paper-world-defaults.ymlfor defaults. Usepaper-world.ymlinside each dimension's folder for per-dimension changes, such as the Nether or the End. - Mode 1 swaps hidden blocks for stone, netherrack or end stone and is much cheaper. Modes 2 and 3 use random fake ores and hide more, at a higher cost. Mode 3 can cut network load on join by about half compared with mode 2.
- Recommended:
max-block-height64 in the overworld and 128 in the Nether, with the End set toenabled: false. - Changes need a restart. Do not use
/reload. - Anti-xray cannot stop every case. A client that learns your world seed can locate ores, and ores touching air stay visible.
On this page
How it works
Normally the server sends the true block data for every chunk, which is exactly what an X-ray client reads. Paper's anti-xray changes the data it sends: blocks you list as hidden are replaced with something else, until a player is close enough to see them for real. Only ores completely surrounded by solid blocks are hidden. Ores that touch cave air or water are not.
Engine modes
| Mode | What it does | Trade-off |
|---|---|---|
1 | Replaces each hidden block with a plain block that fits the dimension: stone (deepslate below y=0), netherrack or end stone. | Much less computation, especially on the client. Real ores are hidden but fake ones are not added. |
2 | Replaces hidden blocks and replacement blocks with randomly generated hidden blocks, so fake ores sit among the real ones. | May stop X-ray better, because fake ores obstruct real ones. More work for server and client. |
3 | Like mode 2, but the random block is chosen per chunk layer rather than per block. | Paper says it can reduce network load on join by about a factor of two and helps chunk packet compression. |
A sensible starting point on most servers is mode 1, because it costs the least. Move to mode 2 or 3 only if players report that mode 1 is being defeated, and check performance afterwards.
Where to edit and what to set
- Defaults (used by every world):
paper-world-defaults.yml, underanticheat.anti-xray. Open the Files tab and look in the server'sconfigfolder. If you cannot find it, check where your server software keeps its configuration. - The Nether:
paper-world.ymlin thethe_netherdimension folder inside your world folder (world/dimensions/minecraft/the_nether/for a default world). - The End: the same file in the
the_endfolder. Paper's recommended value there isenabled: false. - YAML needs spaces, never tabs.
| Key | What it does | Recommended |
|---|---|---|
enabled | Turns anti-xray on or off for the world. | true in the overworld and Nether, false in the End |
engine-mode | 1, 2 or 3. | Your choice. See above |
hidden-blocks | Blocks to hide. In modes 2 and 3, adding air hides ores exposed to air but may cause client FPS drops. | Paper's published list for your mode |
replacement-blocks | Fake blocks used in modes 2 and 3. Ignored in mode 1. Chests go here, because tile entities cannot be hidden blocks in mode 2. | Paper's published list |
max-block-height | Ores above this height are not hidden. | 64 overworld, 128 Nether |
lava-obscures | Whether lava hides ores around it. | false |
update-radius | How far around a changed block the real data is sent. | 2 |
use-permission | When true, players with the bypass permission, and operators, see real ores. | false |
anticheat:
anti-xray:
enabled: true
engine-mode: 1
max-block-height: 64
lava-obscures: false
update-radius: 2
use-permission: false
hidden-blocks:
- coal_ore
- iron_ore
- gold_ore
- diamond_ore
- deepslate_diamond_oreApply it safely
- Back up the file
Download a copy of the file from the Files tab, or take a World and settings backup on Backups.
- Edit and save
Make one change, keep the indentation, and save the file.
- Restart
Click Restart. Paper says changes need a restart and that you should not use
/reload. - Check it
Read the Console tab for YAML errors, then confirm the config is applied. Paper suggests using timings or spark. See the lag and spark guide.
- Test as a normal player
Operators and players with the bypass permission see real ores when
use-permissionis true, so test with a normal account.
The bypass permission is paper.antixray.bypass. Permissions are set with your permissions plugin, and operators bypass anyway. For adding ops, see the whitelist, ops and bans guide.
What anti-xray cannot do
- Seed reversing. If a client gets the world seed, it can calculate where ores are. Partial mitigations exist, such as
feature-seedsin the world configuration, structure seed options inspigot.ymland using a different seed for each world. They are partial measures. See the seed guide. - Range extension. Clients can see real ores beyond the normal range by a noticeable amount. Paper does not include an anti-cheat plugin to deal with that.
- Exposed ores. Ores touching air can be visible in every mode.
- Tile entities. Anti-xray can hide chests that are not exposed to air, but cannot place them as fake blocks.
If ores are still visible
| Check | Why |
|---|---|
enabled is true for that world | Each dimension can have its own file. The End is off by default in the recommended setup. |
max-block-height | Ores above it are not hidden. |
use-permission and your own rank | If you are an operator or have the bypass permission, you see real ores. |
| The block lists | An outdated list can miss newer ore types. Missing replacement blocks can stop it working below y=0 or in some biomes. |
| Exposed ores | Ores touching air or lake water are never hidden. |
| The player's own tools | A client X-ray mod or resource pack may show blocks regardless of what you do. |
| You restarted | A change is not applied until the server restarts. |
Looking for a host? See Minecraft server hosting.
Frequently asked questions
How do I enable anti-xray on a Paper server?
Set enabled to true under anticheat then anti-xray in paper-world-defaults.yml, choose an engine-mode, and restart the server.
Which Paper anti-xray engine mode should I use?
Mode 1 is the cheapest and hides ores with plain blocks. Modes 2 and 3 add fake ores and cost more. Mode 3 can cut join network load by about half compared with mode 2.
Why can players still find ores with anti-xray on?
Ores touching air are visible, ores above max-block-height are not hidden, and a client that knows your seed can locate ores. Operators and permission holders also see real ores.
Do I need to restart after changing anti-xray settings?
Yes. Restart the server and do not use /reload.
What is the anti-xray bypass permission in Paper?
paper.antixray.bypass. It only matters if use-permission is true, and operators bypass anti-xray as well.