Recommended Paper Anti-Xray settings by stonar96

Anti-Xray.md

❗ This has been moved to the official PaperMC docs ❗

Link: https://docs.papermc.io/paper/anti-xray

Help: https://discord.gg/papermc

Recommended Paper Anti-Xray settings by stonar96

General

Anti-Xray can be configured per world in the paper.yml configuration file. To understand how per world configuration works please read this first. Note that after changing any settings for Anti-Xray you have to restart your server. Executing the /reload command (you should never do this) won't apply the settings to worlds that are already loaded.

The official documentation for the Anti-Xray settings and what they mean can be found here.

Basically Anti-Xray has two different modes. engine-mode: 1 replaces specified ores by "fake" stone, netherrack or end stone blocks depending on the world type and engine-mode: 2 randomly places specified fake ores when a chunk packet is sent to the client. The following picture^[1] shows how this looks like for a player using Xray on your server.

engine-mode: 1 is less computationally intensive but engine-mode: 2 works better to prevent Xray. As you can see in the picture above, engine-mode: 1 isn't perfect because only ores that are completely covered by solid blocks can be hidden. This means that ores exposed to air in caves, for example, are still visible. In engine-mode: 2 fake ores obstruct the view to these ores and additionally fake air blocks can also be added.

Default settings

These are the default settings for Anti-Xray. As already mentioned above, you should take a look at the official documentation. I've added some additional info in the comments below that isn't currently there.

world-settings:
  default:
    # Other default world-settings.
    anti-xray:
      # enabled controls the on/off state for the Anti-Xray system.
      enabled: false
      # engine-mode is described above.
      engine-mode: 1
      # As of 1.15.2 build #248 chunk-edge-mode doesn't exist anymore.
      # This setting isn't necessary anymore because neighbor chunks are now usually loaded anyway.
      # Sets how the engine handles chunk edges.
      # Where 1 is not to obfuscate the edges of chunks with unloaded neighbors,
      # 2 is to not send the chunk until its neighbors are present (similar to a x-1 view distance),
      # and 3 is to load the neighbor so it can properly obfuscate the current edge (similar to an x+1 view distance).
      chunk-edge-mode: 2
      # As of 1.17 build #1 max-chunk-section-index doesn't exist anymore.
      # This setting is replaced by the max-block-height setting.
      # max-chunk-section-index controls the height the engine should operate to.
      # y = (max-chunk-section-index + 1) * 16
      # A max-chunk-section-index greater than 15 defaults to 15. A max-chunk-section-index smaller than 0 doesn't make sense.
      max-chunk-section-index: 3
      # max-block-height controls the height (y-coordinate) the engine should operate to.
      # Only integer multiples of 16 are possible values.
      # If another value is specified, it is "rounded down" to the nearest multiple of 16.
      # 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 is the radius for block updates, which send the real blocks to the client when a block is broken.
      # There are only 3 valid options: 0, 1 and 2.
      # An update-radius greater than 2 defaults to 2. An update-radius smaller than 0 defaults to 0.
      # Don't use update-radius: 0 in production. This is only a test mode.
      update-radius: 2
      # Whether or not to obfuscate blocks touching lava.
      # Doesn't work well with non-stone-like ore textures.
      lava-obscures: false
      # Whether or not to enable support for the paper.antixray.bypass permission.
      # Depending on your permission plugin, this may cause performance issues.
      use-permission: false
      # In engine-mode: 1 hidden-blocks are replaced by stone, netherrack or end_stone depending on the world type.
      #                   all types of air blocks are ignored in this list.
      # In engine-mode: 2 hidden-blocks are randomly placed.
      #                   tile entities such as chest or spawner are ignored in this list.
      #                   blocks can be added multiple times to this list, those are used accordingly more often.
      #                   an empty or invalid list or a list that only contains ignored blocks results in [diamond_ore].
      #                   the default block states are placed.
      hidden-blocks:
      - copper_ore
      - deepslate_copper_ore
      - gold_ore
      - deepslate_gold_ore
      - iron_ore
      - deepslate_iron_ore
      - 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
      # In engine-mode: 1 replacement-blocks are not used. Changing this list in engine-mode: 1 has no effect.
      # In engine-mode: 2 replacement-blocks and hidden-blocks are randomly replaced by hidden-blocks.
      #                   tile entities such as chest or spawner are ignored in hidden-blocks.
      #                   tile entities can be added to replacement-blocks.
      #                   all types of air blocks aren't be replaced regardless of where they are added.
      replacement-blocks:
      - stone
      - oak_planks
      - deepslate
    # Other default world-settings.

Recommended settings

Engine-Mode 1

world-settings:
  default:
    # Other default world-settings.
    anti-xray:
      enabled: true
      engine-mode: 1
      chunk-edge-mode: 2
      max-chunk-section-index: 3
      # 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 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:
      - stone
      - oak_planks
      - deepslate
    # Other default world-settings.

  # world_nether: needs to be changed if your world is named differently.
  world_nether:
    anti-xray:
      max-chunk-section-index: 7
      max-block-height: 128
      hidden-blocks:
      - ancient_debris
      - nether_gold_ore
      - nether_quartz_ore
  # world_the_end: needs to be changed if your world is named differently.
  world_the_end:
    anti-xray:
      enabled: false

Engine-Mode 2

world-settings:
  default:
    # Other default world-settings.
    anti-xray:
      enabled: true
      engine-mode: 2
      chunk-edge-mode: 2
      max-chunk-section-index: 3
      # 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-chunk-section-index 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
    # Other default world-settings.

  # world_nether: needs to be changed if your world is named differently.
  world_nether:
    anti-xray:
      max-chunk-section-index: 7
      max-block-height: 128
      hidden-blocks:
      # See note about air 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: needs to be changed if your world is named differently.
  world_the_end:
    anti-xray:
      enabled: false

References

[1] This picture was made by the user Oberfail#2096 on the PaperMC Discord.

Would it not also be a good idea to add cave_air to hidden-blocks to further disrupt cave finders?

Of course you can, however, I wouldn't add too many blocks if it's not absolutely necessary because that also increases the packet size. Adding air doesn't mean it's 100% safe either because more clever hacks could detect those fake air blocks by distinguishing them from real caves for example. Another thing is that if you add cave_air, then I could also ask: Why not add water, lava, ...?

Not sure if I'll get a reply here, but is there any way to turn the anti-xray off for people in spectator mode? As an admin, I find it difficult to check suspicious activity in underground bases and caves with hundreds of ores obscuring my vision.

The reason why you see the fake blocks as spectator in engine-mode: 2 is the air in the hidden-blocks list. There is a permission node paper.antixray.bypass that you can set to true for admins to bypass Anti-Xray. For this you have to enable the setting use-permission in the config. You can link that permission node via contexts to spectator mode using LuckPerms for example or you create an alias for the gamemode command that additionally sets this permission. Note that the fake blocks won't dynamically appear/disappear when the permission note is set. Resending chunks (e.g. rejoining or moving away from your current location and going back) is required. I have written a plugin that can resend chunks with a command. You can also add this command to your gamemode command alias, in case you define one.

So if i remove air from the hidden-blocks list i will not see the fake blocks in spectator, but people that are using x-ray will see them, right?

Yes, but then Anti-Xray will be less effective against certain hacks. For example players could use hacks that only show ores exposed to air or cave finders. This is what air in hidden-blocks will prevent to a certain degree.

Arigatou! Helped a ton!

Thanks!

Hi, I copied everything but the nether anti xray still doesn't work. The overworld works perfect but the nether doesn't. I renamed the world to be the same as what is the name on mine and nothing. I can see all the ores and even the overworld ores as well. Is there a fix for this please, thanks in advance.

Hi, missing whitespaces (indentation) and wrong positioning are the most common issues that people are facing when trying to apply these settings. Indentation and correct structure is very important in YAML. Also make sure that your editor doesn't insert tabs when pasting.

Please take a look at this comment. It explains some common mistakes and also includes an example paper.yml. If that doesn't solve your problem, please join the PaperMC Discord server for further help.

I copied everything(Default settings, Recommended settings - Engine-Mode 2) but the anti xray still doesn't work... T.T
Any solution?

Hello!

if i do it, my server going shutdown
https://pastebin.com/8sQ0twi5 (paper-1.16.5-779)

I copied everything(Default settings, Recommended settings - Engine-Mode 2) but the anti xray still doesn't work... T.T
Any solution?

Hello!

if i do it, my server going shutdown
https://pastebin.com/8sQ0twi5 (paper-1.16.5-779)

You will find your answers in previous comments. I have gone over this multiple times now. If that still doesn't solve your problems, please join the PaperMC Discord server for further help.

hey, When I enable the anti-xray feature in the paper file, the chunks on the server are loaded too late.
how to fix ?

Yeni.projee.mp4

Hello, can I ask for help? I use config for engine mode 2 and Anti-xray doesn't work correctly in nether - ancient debris is not replaced. What am I doing wrong?
https://pastebin.com/pUKYGtMH

Wrong indentation. See previous comments.

I cant find the nether x-ray thing can someone help me?

I am having strange issues that chunks are loading so slow I had to disable Antix-ray, when enabled chunks really load really really slow, I have optimized settings and everything but chunks just load slow ;(. I try to improve it by deleting ores I don't need to hide but still issues, and I try engine 1 and 2 no difference with chunk issue.
Using Purpur. 1.17.1

I am having strange issues that chunks are loading so slow I had to disable Antix-ray, when enabled chunks really load really really slow, I have optimized settings and everything but chunks just load slow ;(. I try to improve it by deleting ores I don't need to hide but still issues, and I try engine 1 and 2 no difference with chunk issue.
Using Purpur. 1.17.1

same issue here, also waiting for a fix.
I'm also on Purpur 1.17.1, using engine-mode: 1

Well I don't see anyone reporting to purpur about it so not sure if it will be fixed soon xD

Well I don't see anyone reporting to purpur about it so not sure if it will be fixed soon xD

So why not report it yourself...

@stonar96
You should remove:

      chunk-edge-mode: 2
      max-chunk-section-index: 3

from your guide. These options are long gone in paper.

I cant find the nether x-ray thing can someone help me?

By default only the default: section exists, which applies to all worlds. For world specific settings you must create your own sections using the world names. This is described in the linked document above. See general. There is also a linked example paper.yml in the comments above.

I am having strange issues that chunks are loading so slow I had to disable Antix-ray, when enabled chunks really load really really slow, I have optimized settings and everything but chunks just load slow ;(. I try to improve it by deleting ores I don't need to hide but still issues, and I try engine 1 and 2 no difference with chunk issue. Using Purpur. 1.17.1

Please open a proper issue including detailed information about your server (system specs, available cores, timings report, number of players when the issue occurs, etc.). Note that this isn't necessarily a bug. This could also be caused by a slow internet connection or using too few cpu cores. There's not much I can do here. Sorry.

@stonar96 You should remove:

      chunk-edge-mode: 2
      max-chunk-section-index: 3

from your guide. These options are long gone in paper.

I'm aware and this is even documented in default-settings. There is no reason to remove them tho. Ofc you can remove them when pasting into your paper.yml, if you want. I'm keeping them intentionally here.

I would love to think that way however while using 1.16.5 version with the x-ray settings it was fine without any issue at all, the chunk issue started with 1.17 :(, the specs should be good enough, specially that issue start with 4-5 players on the server where without it can hold 50 players no issue and chunks work like crazy ;) enable anti-xray and it's gone all to the bin xD

I start to use https://www.spigotmc.org/resources/orebfuscator-anti-x-ray.82710/ as the build in paper.yml is just so bad.
Couple of things to note:
Paper.yml - After enabling chunks were loading so bad while i just added 1 or 2 ore of testing to hide (Using engine 1)
The plugin from the link uses engine 2 and no chunk issues and all blocks are obfuscated like all and no issue what so ever

The end result:
Paper anti-xray is just bad xD
(Note paper anti-xray is bad from 1.17 version bellow should be fine with paper antix-ray like 1.16 and down

Please try to reproduce the issue you are facing on paper, then report it to the paper team so we can take a look (as stonar already told you ages ago...).
You are the first person to ever report issues like that so you most likely did something wrong and we can easily help you.

Should hidden-blocks include blocks of raw copper, iron and gold?

Should hidden-blocks include blocks of raw copper, iron and gold?

Yes, thanks. I think I will add them. The blocks should definitely be added to hidden-blocks in engine-mode: 1.

I'm not sure yet if I should recommend them in engine-mode: 2 because adding more and more hidden-blocks also affects performance and effectiveness of Anti-Xray. The fact that those blocks can also be exposed to air in caves would suggest adding them to hidden-blocks. However, adding them to replacement-blocks will also eliminate them almost entirely.

How to make anti xray 1.18 under Y = 0 ?

It works fine below 0 since it was released for 1.17. No special settings required.

It does. Please make sure you are not using an outdated config. New blocks types have been added to the world, especially below 0.

Can we get a version of engine 2 that is slightly less effective but offers better performance and ping for players?

@LucidAPs thats basically engine 1.