Hide your ores from X-ray cheaters with Paper's built-in anti-xray

What anti-xray changes, and what it leaves alone

An X-ray mod or resource pack can only show what the server sent, and Minecraft sends every block of a chunk, buried diamonds included. Paper's anti-xray edits that copy on its way out: ores nobody could see get swapped for stone or mixed in with fakes. The chunk saved on disk stays as it was, so switching the feature off later loses nothing. It is part of Paper, with nothing to install, and stays off until you enable it.

Where the settings live on Paper 26.x

Paper keeps world settings in two layers. config/paper-world-defaults.yml applies to every world, and a paper-world.yml inside a dimension's folder overrides those defaults for that dimension alone. Since 26.1 the dimensions live inside the main world folder, and their files moved with them.

world stands for the level-name in server.properties.

1. 1

   Open the file

   On the Files tab, click the config folder and press Edit next to paper-world-defaults.yml. For one dimension, open world/dimensions/minecraft, then that dimension's folder, and edit its paper-world.yml.

2. 2

   Keep a copy and mind the spaces

   Press Download on the file first. YAML reads indentation, so indent with spaces, never tabs. As the panel warns, a broken config can stop the server from booting.

3. 3

   Save and restart

   Press Save, then Restart on the Console tab. Anti-xray changes only take effect when the server starts.

Every option and its default

The default hidden-blocks list goes beyond ores: next to every ore, its deepslate version and the raw copper and raw iron blocks, it holds chest, ender_chest, obsidian, mossy_cobblestone and clay.

A block is only hidden when it is covered on all sides. Full solid blocks such as stone count as cover. Air, water and glass do not, and neither do spawners, barriers, shulker boxes, slime blocks and mangrove roots.

The update radius keeps mining normal

When a player starts breaking a block, or a solid block turns see-through, Paper sends the true version of the hidden blocks around it: the six touching blocks at radius 1, up to 24 positions at radius 2. At 0 nothing is sent, which Paper treats as a testing setting.

Letting staff see the real world

Operators hold paper.antixray.bypass unless something takes it away, so with use-permission: true every operator mines without fakes. A permissions plugin such as LuckPerms, from the Plugin catalog on the Plugins tab, hands it to a moderator or takes it from an operator:

lp user Kai permission set paper.antixray.bypass true
lp user Mara permission set paper.antixray.bypass false

What each engine mode shows a cheater

Mode 1 hides only ores wrapped in solid blocks on every side. Ores in a cave wall or on a lake bed stay as they are, so a cheater still spots everything that borders open space.

In modes 2 and 3 the fakes block the view of real ores. Put air in hidden-blocks and the fakes include holes, which also works against cave finders, but Paper warns it can drop players' frame rates. Blocks that hold items can be hidden but never used as fakes, so chest goes in replacement-blocks, where it also hides buried treasure once max-block-height reaches that high.

Settings for the overworld and the Nether

This set uses mode 3. Replace the whole anti-xray block in config/paper-world-defaults.yml with it:

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 3
    hidden-blocks: [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

Coal and emerald ores sit in replacement-blocks: they vanish from X-ray view but never appear as fakes. Against cave finders, add air as the first entry of hidden-blocks. Paper notes that since 1.18 some ores generate much higher than 64, so raise max-block-height in steps of 16 if you want those hidden too; each step adds work per chunk.

The Nether needs a list of its own. This goes in the Nether's paper-world.yml:

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 3
    hidden-blocks: [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

At 128 the Nether is covered up to its bedrock roof, and the bricks and bone blocks keep fortresses, bastions and fossils from standing out. For the End, Paper advises leaving anti-xray off:

anticheat:
  anti-xray:
    enabled: false

Prefer mode 1? Set engine-mode: 1, move the coal and emerald ores into hidden-blocks together with chest, and set replacement-blocks: [], since mode 1 ignores that list. In the Nether, mode 1 only needs ancient_debris, nether_gold_ore and nether_quartz_ore.

What it costs the server and the players

Anti-xray works on chunks as they go out to players, plus a few block updates whenever someone mines, so players who roam and load new chunks cause the most work.

• Height. Only the part of a chunk below max-block-height is reworked.
• Mode. Mode 1 is the lightest. Modes 2 and 3 fill chunks with fakes that every player's computer has to draw, and air in the list is what Paper links to frame drops.
• Joining. Mode 3 sends roughly half the data of mode 2 when a player joins.
• Dimensions. Leaving the End off saves the work there entirely.

Measure rather than guess: record a spark profile on a busy evening before and after, as the spark guide explains. If sending chunks turns out heavy, a smaller view distance cuts how many chunks each player receives.

Test it with your own eyes

1. 1

   Check the values arrived

   After the restart, record a short spark profile and open its link. The viewer shows the configuration the server runs with, so you can confirm enabled: true made it in.

2. 2

   Look through the stone

   While use-permission is false, operators get the fakes too, so your own account is a fair test. Load a resource pack that makes stone see-through and go underground below Y 64.

3. 3

   Compare with your mode

   Mode 1 should show stone, with ores only along caves. Modes 2 and 3 should show a dense spray of ores that are mostly not there.

4. 4

   Mine toward a real ore

   Start breaking the block beside an ore you know is real. The ore shows up as soon as you begin, which is the update radius at work.

What anti-xray cannot stop

• Ores exposed to air or water. Cave walls and lake beds stay visible; modes 2 and 3 only surround them with fakes.
• Dungeon chests. They stand in open air with nothing to hide behind.
• Anything above `max-block-height`.
• Range extension. A modified client can still see real ores somewhat further than intended. Paper points to a separate anti-cheat plugin for that.
• Seed reversing. A client that works out the world seed knows where every ore generated. generate-random-seeds-for-all: true under feature-seeds makes that harder, as does a different seed per world, but neither moves ores in terrain that already exists.
• Staff with the bypass. With use-permission: true, every operator sees the real blocks.

If it seems to do nothing below Y 0, the file is probably out of date: a list from before 1.18 lacks deepslate and the deepslate ores. For a new world, the seed guide covers choosing a seed of your own.

Purpur, vanilla, Fabric and NeoForge

Purpur runs Paper's anti-xray unchanged. A vanilla server has none and cannot load plugins or mods; switch it to Paper or Purpur on the Settings tab, as Paper vs Purpur vs Spigot describes, and the world comes along.

On Fabric and NeoForge, the AntiXray mod brings the same three engine modes, with builds for 26.2. It runs on the server only, so players install nothing. Find it with Search mods on the Mods tab, press Verify & install and restart. On Fabric its settings live in config/antixray.toml, one section per dimension such as [the_nether], with keys like engineMode and maxBlockHeight. Its block lists accept tags, so #c:ores takes in ores from other mods that carry that tag.