Skip to main content

Configuring Anti-Xray

Originally written and maintained by stonar96.

Paper includes an obfuscation-based Anti-Xray with two modes, configurable per world in paper.yml.

Per World Configuration

If you aren't already familiar with per world configuration, please take a moment to familiarize yourself with the Per World Configuration Guide.

This guide is a step-by-step walk-through for configuring Anti-Xray. For reference documentation, refer to the Anti-Xray section of the Per-World Configuration Reference.

Anti-Xray has two different modes. engine-mode: 1 replaces specified blocks (hidden-blocks) with other "fake" blocks, stone (deepslate at y < 0), netherrack, or end_stone based on the dimension. In contrast, engine-mode: 2 will replace both hidden-blocks and replacement-blocks with randomly generated hidden-blocks.

The following images1 show how each mode will look for a player using Xray with the recommended configuration in both the overworld and nether.

Overworld Anti-Xray Comparison Nether Anti-Xray Comparison

Especially on the client side, engine-mode: 1 is much less computationally intensive, while engine-mode: 2 may better prevent Xray. With engine-mode: 1, only ores that are entirely covered by solid blocks will be hidden. Ores exposed to air in caves or water from a lake will not be hidden. With engine-mode: 2, fake ores obstruct the view of real blocks. If air is added to hidden-blocks, engine-mode: 2 will effectively hide all ores, even those exposed to air.

Anti-Xray Bypasses

Range Extension: While Anti-Xray alone will prevent the majority of users from Xraying on your server, it is not by any means infallible. Because of how Anti-Xray is (and has to be) implemented, it is possible to, on a default server, extend the range of real ores you can see by a not insignificant amount. This can be mitigated by any competent anti-cheat plugin; however, this is not included out of the box.

Seed Reversing: Another attack vector is the deterministic nature of Minecraft's world generation. If the client is able to obtain the world seed, it is able to know the real location of every generated ore, completely bypassing Anti-Xray. This can be partially worked around by making it harder for the client to reverse the world seed with the feature-seeds configuration, in conjunction with the structure seed options in spigot.yml. Note that this is not a complete solution, and it may still be possible for a client to obtain the server's world seed. Using a different seed for each world may also be beneficial.

Ores Exposed to Air: In both engine-mode: 1 and engine-mode: 2, it is possible for a client to view ores that are exposed to air. This can be mitigated in engine-mode: 2 by adding air to the hidden-blocks list. However, doing this may cause client performance issues (FPS drops) for some players.

The recommended configuration for both engine-mode: 1 and engine-mode: 2 is as follows:

Spacing

YAML cares about whitespace! The example configuration below is already formatted correctly. Ensure formatting remains unchanged by using the "copy" button in the top right of each example.

engine-mode: 1

Overworld Configuration

Replace the existing anti-xray block in paper.yml (under world-settings.default) with the following:

paper.yml
    anti-xray:
enabled: true
engine-mode: 1
# As of 1.18 some ores are generated much higher.
# Please adjust the max-block-height setting at your own discretion.
# https://minecraft.fandom.com/wiki/Ore might be helpful.
max-block-height: 64
update-radius: 2
lava-obscures: false
use-permission: false
hidden-blocks:
# There's no chance to hide dungeon chests as they are entirely surrounded by air, but buried treasures will be hidden.
- 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
replacement-blocks:
# The replacement-blocks list is not used in engine-mode: 1. Changing this will have no effect.
- stone
- oak_planks
- deepslate
End and Nether Configuration

Copy and paste this at the very bottom of paper.yml. See the Per-World Configuration Guide for more information. Remember to change the world names if your worlds are named differently!

paper.yml
  world_nether:
anti-xray:
max-block-height: 128
hidden-blocks:
- ancient_debris
- nether_gold_ore
- nether_quartz_ore
world_the_end:
anti-xray:
enabled: false

engine-mode: 2

Overworld Configuration

Replace the existing anti-xray block in paper.yml (under world-settings.default) with the following:

paper.yml
    anti-xray:
enabled: true
engine-mode: 2
# As of 1.18 some ores are generated much higher.
# Please adjust the max-block-height setting at your own discretion.
# https://minecraft.fandom.com/wiki/Ore might be helpful.
max-block-height: 64
update-radius: 2
lava-obscures: false
use-permission: false
hidden-blocks:
# You can add air here such that many holes are generated.
# This works well against cave finders but may cause client FPS drops for all players.
- 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
replacement-blocks:
# Chest is a tile entity and can't be added to hidden-blocks in engine-mode: 2.
# But adding chest here will hide buried treasures, if max-block-height is increased.
- 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
End and Nether Configuration

Copy and paste this at the very bottom of paper.yml. See the Per-World Configuration Guide for more information. Remember to change the world names if your worlds are named differently!

paper.yml
  world_nether:
anti-xray:
max-block-height: 128
hidden-blocks:
# See note about air and possible client performance issues above.
- air
- ancient_debris
- bone_block
- glowstone
- magma_block
- nether_bricks
- nether_gold_ore
- nether_quartz_ore
- polished_blackstone_bricks
replacement-blocks:
- basalt
- blackstone
- gravel
- netherrack
- soul_sand
- soul_soil
world_the_end:
anti-xray:
enabled: false

  1. Image design by Oberfail, initially posted in the PaperMC Discord. ​