Paper Anti-Xray: Enable Ore Hiding and Choose an Engine Mode

For server owners running Paper, built-in anti-xray provides a way to hide underground ores without adding another plugin. By the end, you will have enabled it, chosen an engine mode and prepared a test that checks both ore hiding and normal mining.

Find Paper's anti-xray settings#

Paper includes anti-xray, but it is disabled by default. Its settings sit under anticheat.anti-xray in the world configuration.

Paper Free High-performance Minecraft server software whose built-in anti-xray hides ores by sending fake blocks to players. On PaperMC

The shared file is config/paper-world-defaults.yml. Settings there apply across worlds unless a world's own paper-world.yml overrides them. Use the shared file for a common starting point, then add world-specific settings where needed.

Before editing, make a backup through your existing backup process. If that process needs attention, follow our guide to automating backups and testing a restore.

Choose between engine modes 1, 2 and 3#

The engine mode changes the fake block information players receive. Paper defaults to mode 1, but enabling anti-xray and choosing its mode are separate settings.

Start with mode 1 if keeping server overhead low is your priority. If you want the stronger obfuscation approach, test mode 2 or 3 with your actual players and hardware. Paper's anti-xray guideSource site explains the modes and their limitations.

Enable anti-xray without replacing the block lists#

The following example enables mode 2 while keeping several other settings at their documented defaults. Merge these values into the existing section, preserving its hidden-blocks and replacement-blocks lists.

anticheat:
  anti-xray:
    enabled: true
    engine-mode: 2
    max-block-height: 64
    update-radius: 2
    lava-obscures: false
    use-permission: false

This is a partial configuration, so do not replace the whole file with it or add a second anticheat section. Preserve the indentation of the surrounding settings.

The default max-block-height is 64. Choose the height according to what you want protected in that world. Keep update-radius at its default of 2 for your first test; the documented range is 0 to 2.

Leave use-permission: false unless you specifically need a bypass. With permission checks enabled, players holding paper.antixray.bypass skip anti-xray. Paper's permission reference says nobody receives that permission by default.

Choose which blocks to hide#

The two block lists have different jobs. Understanding that difference helps avoid a configuration that hides fewer blocks than you intended.

• hidden-blocks: the blocks anti-xray hides. In modes 2 and 3, suitable entries also supply the fake blocks shown to clients.
• replacement-blocks: additional blocks replaced with fake hidden blocks in modes 2 and 3.

Paper's default hidden list includes the main ores and their deepslate variants, along with entries such as raw copper blocks, raw iron blocks, clay, obsidian, chests and ender chests. The default replacement list contains stone, oak_planks and deepslate. Keeping those defaults initially gives you a clear baseline.

Be careful with air and chests#

Paper documents adding air to the hidden list as useful against cave finders. It also warns that this can reduce client FPS for all players, so test it separately from your initial enablement.

Chests need special treatment because they are block entities. Paper notes that they cannot serve as fake hidden blocks in mode 2, although listing chest can help hide buried treasure chests when the maximum block height is raised. Do not assume every block in the list behaves like an ore.

Give the Nether and End their own settings#

Use per-world overrides when different dimensions need different hidden blocks or heights. Paper's current world configuration referenceSource site places these files inside the world's dimension directories.

Set the required overrides under the same anticheat.anti-xray structure. Review the hidden-block list for each dimension rather than assuming the Overworld list covers the blocks you care about there.

Restart and test ordinary mining#

Paper requires a full server restart to apply anti-xray changes. Save every edited file before starting the server again.

1. Test in each dimension where you changed settings.
2. Use an account without the bypass permission if you enabled permission checks.
3. Check enclosed underground ores as well as normal mining and exposed cave surfaces.
4. Assess server responsiveness and client frame rates before changing another setting.

If fake blocks appear to be missing during an x-ray test, Paper notes that the testing mod may disable those blocks or the resource pack may hide them. Check the client's display settings before concluding that the server configuration has failed.

Know the limits and when to consider Orebfuscator#

Anti-xray does not make suspicious mining impossible. Ores exposed to air or transparent blocks can remain visible because players can legitimately see them. Paper also warns that knowledge of the world seed can let a client calculate real ore locations; it points to feature seeds as a partial mitigation.

Orebfuscator is another option when you need block-entity hiding or proximity-based visibility controls. It changes network packets without changing the world itself.

Orebfuscator Free An anti-xray plugin that obfuscates blocks and block entities by modifying packets, with proximity-based visibility; needs ProtocolLib. On Modrinth

Its listing describes support for obfuscating blocks, hiding block entities such as chests and adjusting visibility by player proximity. Read its Java and dependency requirements before installing it, and use its configuration and troubleshooting wiki to plan a separate test.

For broader protection, our Paper anti-cheat comparison covers other detection needs. If you need to investigate changes made by a player, follow our guide to inspecting activity and rolling back griefing. Keep those investigation tasks separate from checking whether ore hiding works.