Skip to content

Instantly share code, notes, and snippets.

@stonar96
Last active March 4, 2024 15:16
Star You must be signed in to star a gist
Save stonar96/ba18568bd91e5afd590e8038d14e245e to your computer and use it in GitHub Desktop.
Recommended Paper Anti-Xray settings by stonar96

❗ 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.

Anti-Xray modes

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.

@stonar96
Copy link
Author

stonar96 commented Jul 2, 2021

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.

@1000tree
Copy link

1000tree commented Jul 3, 2021

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

@bluruz
Copy link

bluruz commented Jul 5, 2021

Hello!

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

@stonar96
Copy link
Author

stonar96 commented Jul 5, 2021

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.

@giantfurkii
Copy link

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

@DedKob1
Copy link

DedKob1 commented Oct 3, 2021

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

@stonar96
Copy link
Author

stonar96 commented Oct 3, 2021

Wrong indentation. See previous comments.

@RdxOverLord
Copy link

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

@arturek1666
Copy link

arturek1666 commented Oct 20, 2021

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

@QuanTrieuPCYT
Copy link

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

@arturek1666
Copy link

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

@andrewkm
Copy link

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...

@andrewkm
Copy link

andrewkm commented Oct 27, 2021

@stonar96
You should remove:

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

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

@stonar96
Copy link
Author

stonar96 commented Oct 27, 2021

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.

@arturek1666
Copy link

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

@arturek1666
Copy link

arturek1666 commented Dec 5, 2021

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

@MiniDigger
Copy link

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.

@AnttiMK
Copy link

AnttiMK commented Dec 27, 2021

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

@stonar96
Copy link
Author

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.

@blackydev
Copy link

How to make anti xray 1.18 under Y = 0 ?

@stonar96
Copy link
Author

stonar96 commented Jan 8, 2022

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

@stonar96
Copy link
Author

stonar96 commented Jan 9, 2022

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

@LucidAPs
Copy link

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

@protected22
Copy link

@LucidAPs thats basically engine 1.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment