Introduction to Anti-Xray

What is X-Ray?

X-Ray is a cheating technique that allows players to see through solid blocks to easily locate ores, caves, hidden bases, and other structures. This cheat can be achieved through modified clients, resource packs, or mods.

Paper Solution

Paper natively integrates a powerful anti-Xray system that works server-side. Unlike traditional plugins, this solution requires no additional installation and provides robust protection against the majority of X-Ray techniques.

Advantages of the Native Solution

Aspect	Description
Performance	Optimized at the server code level
Compatibility	Works with all vanilla clients
Maintenance	Automatically updated with Paper
Reliability	No external dependencies
Configuration	Customizable by world/dimension

---

Technical Operation

Basic Principle

Paper's anti-Xray works by modifying chunk data sent to clients. Instead of sending the actual blocks, the server replaces certain blocks with decoys until the player gets close enough to legitimately reveal them.

Revelation Process

A hidden block is revealed when one of the following conditions is met:

• The player breaks an adjacent block
• The player places an adjacent block
• A piston moves an adjacent block
• An explosion destroys an adjacent block
• Water or lava flows over an adjacent block
• The block enters direct line of sight (raytracing enabled)

Adjacent Blocks

The system considers the 6 faces of a block (top, bottom, north, south, east, west). A block is considered "exposed to air" if at least one of its faces touches a transparent block (air, glass, water, etc.).

---

Operation Modes

Paper offers two distinct modes, each with its own advantages and disadvantages.

Engine Mode 1: Simple Replacement

This mode replaces all hidden blocks (not exposed to air) with a single replacement block, usually stone.

Operation:

Hidden original block → Stone (or defined block)
Exposed to air block → Remains unchanged

Advantages:

• Low impact on performance
• Minimal memory consumption
• Reduced network bandwidth

Disadvantages:

• Vulnerable to advanced X-Ray filtering out stone
• Experienced players can guess locations

Recommended Use Case:

• Servers with limited resources
• Large player population
• Creative or semi-RP servers

Engine Mode 2: Random Obfuscation

This mode replaces hidden blocks with random blocks chosen from a configurable list, creating visual "noise" making X-Ray ineffective.

Operation:

Hidden original block → Random block (diamond_ore, gold_ore, iron_ore, etc.)
Exposed to air block → Remains unchanged

Advantages:

• Maximum protection against all types of X-Ray
• Impossible to distinguish real ores from fake ones
• Completely discourages X-Ray usage

Disadvantages:

• Higher impact on performance
• Increased memory consumption
• Increased network bandwidth

Recommended Use Case:

• Competitive survival servers
• PvP/Faction servers
• Servers where resource economy is important

Visual Comparison

Criterion	Mode 1	Mode 2
Protection	Basic	Maximum
CPU	Low	Moderate
RAM	Low	Moderate
Network	Low	Moderate
Recommended	Casual	Competitive

---

Complete Configuration

File Location

The configuration file is located at:

config/paper-world-defaults.yml      # Default configuration
/paper-world.yml              # World-specific configuration

Configuration Structure

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 2
    max-block-height: 64
    update-radius: 2
    lava-obscures: false
    use-permission: false
    hidden-blocks:
      - copper_ore
      - deepslate_copper_ore
      - raw_copper_block
      - gold_ore
      - deepslate_gold_ore
      - raw_gold_block
      - iron_ore
      - deepslate_iron_ore
      - raw_iron_block
      - coal_ore
      - deepslate_coal_ore
      - lapis_ore
      - deepslate_lapis_ore
      - mossy_cobblestone
      - obsidian
      - chest
      - diamond_ore
      - deepslate_diamond_ore
      - redstone_ore
      - deepslate_redstone_ore
      - clay
      - emerald_ore
      - deepslate_emerald_ore
      - ender_chest
    replacement-blocks:
      - chest
      - amethyst_block
      - andesite
      - budding_amethyst
      - calcite
      - coal_ore
      - deepslate_coal_ore
      - deepslate
      - deepslate_copper_ore
      - deepslate_diamond_ore
      - deepslate_emerald_ore
      - deepslate_gold_ore
      - deepslate_iron_ore
      - deepslate_lapis_ore
      - deepslate_redstone_ore
      - diorite
      - dirt
      - emerald_ore
      - granite
      - gravel
      - iron_ore
      - oak_planks
      - smooth_basalt
      - stone
      - tuff

Detailed Parameters

enabled

enabled: true

Enables or disables anti-Xray. Set to false to completely disable.

engine-mode

engine-mode: 2

Sets the operation mode (1 or 2). See the previous section for details.

max-block-height

max-block-height: 64

Maximum height (Y coordinate) at which anti-Xray applies. Above this value, no obfuscation is performed. Reducing this value improves performance.

Recommended Values:

• Overworld: 64 (sea level)
• Nether: 128 (total height)
• End: 0 (disabled, few ores)

update-radius

update-radius: 2

Block update radius when a block is revealed. A value of 2 means blocks within a 2-block radius will be updated.

Values:

• 1: Maximum performance, risk of unrevealed blocks
• 2: Recommended balance
• 3+: Maximum security, performance impact

lava-obscures

lava-obscures: false

If enabled, lava is considered an opaque block for obfuscation. Useful for the Nether but can cause visual issues.

use-permission

use-permission: false

If enabled, players with the paper.antixray.bypass permission will not be affected by the anti-Xray. Useful for administrators during debugging.

hidden-blocks

hidden-blocks:
  - diamond_ore
  - emerald_ore
  # ...

List of blocks to hide/obfuscate. These blocks will be replaced when not exposed to air.

Mode 1: These blocks are replaced by stone (or the first block from replacement-blocks).

Mode 2: These blocks are replaced by a random block from the replacement-blocks list.

replacement-blocks

replacement-blocks:
  - stone
  - deepslate
  - granite
  # ...

List of blocks used as replacements.

Mode 1: Only the first block in the list is used.

Mode 2: Blocks are randomly chosen from this list.

---

Optimization by Server Type

Vanilla Survival Server

Balanced configuration for a classic survival experience.

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 2
    max-block-height: 64
    update-radius: 2
    lava-obscures: false
    use-permission: false
    hidden-blocks:
      - chest
      - coal_ore
      - deepslate_coal_ore
      - copper_ore
      - deepslate_copper_ore
      - diamond_ore
      - deepslate_diamond_ore
      - emerald_ore
      - deepslate_emerald_ore
      - gold_ore
      - deepslate_gold_ore
      - iron_ore
      - deepslate_iron_ore
      - lapis_ore
      - deepslate_lapis_ore
      - redstone_ore
      - deepslate_redstone_ore
    replacement-blocks:
      - chest
      - coal_ore
      - deepslate_coal_ore
      - copper_ore
      - deepslate_copper_ore
      - diamond_ore
      - deepslate_diamond_ore
      - emerald_ore
      - deepslate_emerald_ore
      - gold_ore
      - deepslate_gold_ore
      - iron_ore
      - deepslate_iron_ore
      - lapis_ore
      - deepslate_lapis_ore
      - redstone_ore
      - deepslate_redstone_ore
      - amethyst_block
      - andesite
      - budding_amethyst
      - calcite
      - deepslate
      - diorite
      - dirt
      - granite
      - gravel
      - smooth_basalt
      - stone
      - tuff

Faction/PvP Server

Maximum configuration for competitive environments where cheating must be strictly prevented.

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 2
    max-block-height: 320
    update-radius: 2
    lava-obscures: false
    use-permission: false
    hidden-blocks:
      - ancient_debris
      - chest
      - coal_ore
      - deepslate_coal_ore
      - copper_ore
      - deepslate_copper_ore
      - diamond_ore
      - deepslate_diamond_ore
      - emerald_ore
      - deepslate_emerald_ore
      - gold_ore
      - deepslate_gold_ore
      - iron_ore
      - deepslate_iron_ore
      - lapis_ore
      - deepslate_lapis_ore
      - nether_gold_ore
      - nether_quartz_ore
      - redstone_ore
      - deepslate_redstone_ore
      - trapped_chest
      - ender_chest
      - shulker_box
      - white_shulker_box
      - orange_shulker_box
      - magenta_shulker_box
      - light_blue_shulker_box
      - yellow_shulker_box
      - lime_shulker_box
      - pink_shulker_box
      - gray_shulker_box
      - light_gray_shulker_box
      - cyan_shulker_box
      - purple_shulker_box
      - blue_shulker_box
      - brown_shulker_box
      - green_shulker_box
      - red_shulker_box
      - black_shulker_box
      - barrel
      - dispenser
      - dropper
      - hopper
      - spawner
      - tnt
    replacement-blocks:
      - chest
      - coal_ore
      - deepslate_coal_ore
      - copper_ore
      - deepslate_copper_ore
      - diamond_ore
      - deepslate_diamond_ore
      - emerald_ore
      - deepslate_emerald_ore
      - gold_ore
      - deepslate_gold_ore
      - iron_ore
      - deepslate_iron_ore
      - lapis_ore
      - deepslate_lapis_ore
      - redstone_ore
      - deepslate_redstone_ore
      - amethyst_block
      - andesite
      - budding_amethyst
      - calcite
      - deepslate
      - diorite
      - dirt
      - granite
      - gravel
      - oak_planks
      - smooth_basalt
      - stone
      - tuff

Economy Server

Configuration targeting valuable resources to protect the server's economy.

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 2
    max-block-height: 64
    update-radius: 2
    lava-obscures: false
    use-permission: false
    hidden-blocks:
      - diamond_ore
      - deepslate_diamond_ore
      - emerald_ore
      - deepslate_emerald_ore
      - gold_ore
      - deepslate_gold_ore
      - ancient_debris
      - chest
      - ender_chest
      - spawner
    replacement-blocks:
      - diamond_ore
      - deepslate_diamond_ore
      - emerald_ore
      - deepslate_emerald_ore
      - gold_ore
      - deepslate_gold_ore
      - coal_ore
      - deepslate_coal_ore
      - iron_ore
      - deepslate_iron_ore
      - copper_ore
      - deepslate_copper_ore
      - deepslate
      - stone
      - granite
      - diorite
      - andesite

Performance Server (High Population)

Minimal configuration for servers with many players where performance is critical.

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 1
    max-block-height: 48
    update-radius: 1
    lava-obscures: false
    use-permission: false
    hidden-blocks:
      - diamond_ore
      - deepslate_diamond_ore
      - emerald_ore
      - deepslate_emerald_ore
      - ancient_debris
    replacement-blocks:
      - stone

---

Configuration by Dimension

Overworld (world)

File: world/paper-world.yml

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 2
    max-block-height: 64
    update-radius: 2
    lava-obscures: false
    use-permission: false
    hidden-blocks:
      - chest
      - coal_ore
      - deepslate_coal_ore
      - copper_ore
      - deepslate_copper_ore
      - diamond_ore
      - deepslate_diamond_ore
      - emerald_ore
      - deepslate_emerald_ore
      - gold_ore
      - deepslate_gold_ore
      - iron_ore
      - deepslate_iron_ore
      - lapis_ore
      - deepslate_lapis_ore
      - redstone_ore
      - deepslate_redstone_ore
      - raw_copper_block
      - raw_gold_block
      - raw_iron_block
    replacement-blocks:
      - amethyst_block
      - andesite
      - budding_amethyst
      - calcite
      - chest
      - coal_ore
      - deepslate_coal_ore
      - copper_ore
      - deepslate_copper_ore
      - deepslate
      - diamond_ore
      - deepslate_diamond_ore
      - diorite
      - dirt
      - emerald_ore
      - deepslate_emerald_ore
      - gold_ore
      - deepslate_gold_ore
      - granite
      - gravel
      - iron_ore
      - deepslate_iron_ore
      - lapis_ore
      - deepslate_lapis_ore
      - oak_planks
      - redstone_ore
      - deepslate_redstone_ore
      - smooth_basalt
      - stone
      - tuff

Nether (world_nether)

File: world_nether/paper-world.yml

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

End (world_the_end)

File: world_the_end/paper-world.yml

The End contains few resources to protect. A minimal or disabled configuration is usually sufficient.

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 1
    max-block-height: 0
    update-radius: 2
    lava-obscures: false
    use-permission: false
    hidden-blocks:
      - chest
      - ender_chest
      - shulker_box
    replacement-blocks:
      - end_stone

Or simply disabled:

anticheat:
  anti-xray:
    enabled: false

---

Performance Impact

Metrics per Mode

Metric	Mode 1	Mode 2	No Anti-Xray
CPU (chunk gen)	+5-10%	+15-25%	Baseline
RAM per chunk	+0.1 KB	+0.5-1 KB	Baseline
Bandwidth	+2-5%	+10-20%	Baseline
Network latency	Negligible	+1-5 ms	Baseline

Factors Influencing Performance

Number of hidden-blocks

The longer the list, the heavier the processing.

# Light (5-10 blocks)
hidden-blocks:
  - diamond_ore
  - emerald_ore
  - gold_ore
  - ancient_debris
  - chest

# Heavy (20+ blocks)
hidden-blocks:
  - coal_ore
  - deepslate_coal_ore
  - copper_ore
  - deepslate_copper_ore
  # ... 20+ entries

max-block-height

Reducing this value significantly decreases the load.

# Optimal performance
max-block-height: 48

# Balanced
max-block-height: 64

# Maximum protection (costly)
max-block-height: 320

update-radius

Each increase multiplies the number of blocks to check.

# Radius 1: 6 blocks checked
update-radius: 1

# Radius 2: 26 blocks checked
update-radius: 2

# Radius 3: 98 blocks checked
update-radius: 3

Performance Optimization

For high-load servers

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 1          # Lightest mode
    max-block-height: 48    # Low limit
    update-radius: 1        # Minimal radius
    hidden-blocks:          # Short list
      - diamond_ore
      - deepslate_diamond_ore
      - ancient_debris
    replacement-blocks:
      - stone

Performance Monitoring

Use Spark to analyze the impact:

/spark profiler start
# Wait a few minutes while players play
/spark profiler stop

Look for in the report:

• AntiXray in threads
• ChunkSerializer for generation impact
• PlayerConnection for network impact

---

Troubleshooting and Common Issues

Issue: Blocks briefly visible before obfuscation

Symptom: Players see real blocks for a fraction of a second when chunks load.

Cause: Network latency or high server load.

Solutions:

# Increase anti-xray priority
update-radius: 2

# Check network configuration
# In server.properties
network-compression-threshold=256

Issue: Blocks remain hidden after mining

Symptom: After breaking a block, adjacent blocks remain obfuscated.

Cause: update-radius too low or version bug.

Solutions:

# Increase update radius
update-radius: 2

# Ensure Paper is up to date
# Download the latest build from papermc.io

Issue: Degraded performance

Symptom: Low TPS, lag when loading chunks.

Solutions:

# Reduce load
engine-mode: 1
max-block-height: 48
update-radius: 1

# Reduce block list
hidden-blocks:
  - diamond_ore
  - deepslate_diamond_ore
  - emerald_ore
  - deepslate_emerald_ore

Issue: Some blocks are not hidden

Symptom: X-Ray players see certain ores.

Cause: Block not included in hidden-blocks or exposed to air.

Solutions:

# Ensure all variants are included
hidden-blocks:
  - diamond_ore
  - deepslate_diamond_ore  # Don't forget the deepslate version

Issue: Incompatibility with certain plugins

Symptom: Protection or economy plugins malfunction.

Cause: Some plugins interact with blocks in a non-standard way.

Solutions:

• Update the relevant plugin
• Contact the plugin developer
• Add admins to bypass:

use-permission: true

Then give permission paper.antixray.bypass to admins.

Debug Commands

# Reload configuration (after modification)
/paper reload

# Check active configuration
/paper dumpplugins  # Indirectly checks if Paper is working

# Profile the server
/spark profiler start
/spark profiler stop

---

Best Practices

Initial Configuration

1. Start in Mode 2 for maximum protection
2. Adjust based on observed performance
3. Test with trusted players using X-Ray

Recommended Block List

Essential (all servers)

• diamond_ore / deepslate_diamond_ore
• emerald_ore / deepslate_emerald_ore
• ancient_debris

Recommended (survival)

• gold_ore / deepslate_gold_ore
• iron_ore / deepslate_iron_ore
• copper_ore / deepslate_copper_ore
• lapis_ore / deepslate_lapis_ore
• redstone_ore / deepslate_redstone_ore
• coal_ore / deepslate_coal_ore

Containers (PvP/Faction)

• chest / trapped_chest
• ender_chest
• barrel
• shulker_box (all colors)
• hopper
• dispenser / dropper

Special

• spawner (if significant on your server)
• tnt (PvP servers)
• obsidian (hidden bases)

Maintenance

• Regularly update Paper for fixes
• Monitor performance with Spark or Timings
• Test after each major update of Minecraft
• Document your changes in a changelog file

Additional Security

Anti-Xray does not replace other measures:

• Anti-cheat plugin (Matrix, Vulcan, Grim)
• Block logs (CoreProtect, Prism)
• Active moderation and player reports
• Regular check of suspicious players

---

Resources and References

Official Documentation

• Paper Documentation: https://docs.papermc.io/
• Anti-Xray Configuration: https://docs.papermc.io/paper/anti-xray

Useful Tools

• Spark Profiler: https://spark.lucko.me/
• Paper Timings: https://timings.aikar.co/

Community

• Discord PaperMC: https://discord.gg/papermc
• SpigotMC Forums: https://www.spigotmc.org/