How To Stop XRay on a Minecraft Server

If you're running a Minecraft server, stopping players from using XRay cheats is essential for fair gameplay. Luckily, newer versions of the Minecraft server software Purpur and Paper include a built-in anti-XRay system, which you can configure easily without third-party plugins. Here's a step-by-step guide to help you set it up.

🗒 The anti-XRay covered in this article will only work on Paper and PurPur servers. If you have a Forge, Fabric, NeoForge, or Vanilla server, it will not work.

Difference Between Paper & Purpur

Paper is generally considered more stable compared to Purpur, as it is the core foundation upon which Purpur is built. Paper focuses on performance optimizations and bug fixes for Minecraft servers while maintaining stability, and it is widely regarded as one of the most reliable server software choices.

📖TLDR: Paper prioritizes stability and performance.

Purpur, is a fork of Paper that adds additional features, customization options, and gameplay tweaks. While it provides more flexibility for server owners looking to modify game mechanics or enhance certain features, it introduces more changes, which could potentially introduce instability or bugs not present in Paper.

📖 TLDR: Purpur offers more customization but may introduce some instability depending on the complexity of the server set up.

Step 1: Install Paper or Purpur and Launch Your Server

Make sure you're running a newer version of Paper or Purpur (version 1.9 or later) on your server. This ensures the needed Anti-XRay options are available.

💡 Use the one of the following guides to install Paper or Purpur on your server:

How To Install Paper on a Minecraft Server
How To Install PurPur on a Minecraft Server

Step 2: Access the Server Configuration Files

1. Stop your server using your server's console.
2. Open your server's File Manager.

3. Locate the 'config' folder. Inside the config folder, open the 'paper-world-defaults.yml' file.

Step 3: Enable Anti-XRay & Configuring an Engine Mode for your Overworld

PaperMC offers recommended configuration options based on the engine mode you select and the world you're configuring. It’s recommended to use their settings for optimal performance and results.

⚠️ Differences in Engine Modes

Engine Mode 1: Replaces hidden blocks with "fake" blocks, such as stone, deepslate, netherrack, or end_stone depending on the dimension.
Engine Mode 2: Replaces both hidden and replacement blocks with randomly generated hidden blocks. (Recommended)
Engine Mode 3: Randomizes blocks per layer of the chunk.

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

OVERWORLD ENGINEMODE EXAMPLES

THE NETHER WORLD ENGINEMODE EXAMPLES

1. Find one of the recommended configuration options here.

2. Once you found the configuration you want to use for your Overworld, copy the configuration using the copy button at the top right of the file.

3. Return to the tab where you have the 'paper-world-defaults.yml' file open. Locate the line labeled 'anti-xray', then select all the text starting from that line down to the 'use-permission' line (make sure to include the 'use-permission' line as well). Once selected, paste the recommended configuration you copied earlier in Step 1.

4. Scroll down look for the line that says 'generate-random-seeds-for-all:', Change this option from false to true. Once that's done, click the Save Content button at the top right of the file.

💡 Enabling this option makes seed cracking/reversing a lot more difficult for those trying to use X-Ray on your server. Especially for custom worlds.

Step 6: Configure for the Nether (Optional)

💡 Engine Mode 1 is recommend for the Nether but any other engine mode can be used.

1. Go back to your server's file manager tab then look for the 'world_nether' folder and open it.2. Open the 'paper-world.yml' file.
3. Find one of the recommended configuration options here. Similar to the Overworld set up process. Find the engine mode you wish to use and paste the configuration under the '_version: line'.
4. Save the file using the Save Content button at the top right of the file.

Step 7: Start Your Server

Now that your Anti-Xray configurations are set, head back to your server's console and start the server.

🥳 Congratulations! Anti-XRay is now enabled across your worlds on your Paper/Purpur server!

📝Additional Information 📝

The End World: There's need to set up Anti-XRay in The End, as there are no ores in this dimension.
Plugins for Extra Protection: If you'd like additional protection, consider using Anti-XRay plugins from sites like Spigot, Modrinth, or Bukkit. Just be sure to follow the installation and configuration instructions provided by the plugin developers.
Server Performance: Enabling Anti-XRay in Paper/Purpur should not cause significant lag to your server. The way it works is by modifying the packets sent to the client rather than altering the actual world data. This means the server isn't constantly replacing blocks in the world, but instead, it sends "fake" block data to players using XRay mods.

🚧Troubleshooting Tips 🚧

Check your Server Version: Ensure your server is running a supported version of Paper/Purpur. If Anti-XRay options are not appearing or not working as expected, verify that your server version is up-to-date. You can check this by running the /version command in your server console.
Verify Config Files: Open the 'paper-world-defaults.yml' or 'paper-world.yml' configuration files again to confirm that your changes were saved properly. Ensure the 'anti-xray' setting is set to 'enabled: true', and verify that you've chosen the correct engine mode under the 'engine' field. Additionally, double-check that you're editing the correct files for each specific world (such as the overworld or nether).
Check for Typos or Formatting Issues: YAML files are sensitive to formatting. Ensure that Indentation is correct (using spaces, not tabs). Also make sure, there are no extra or missing colons, commas, or quotation marks in the configuration file.
Review Server Logs for Errors: If Anti-XRay still isn’t working, check your server logs for any error messages related to Anti-XRay or configuration loading. Look for lines mentioning anti-xray, engine mode, or paper-world.yml. You can access server logs in your console or the logs folder. Errors in the log files may indicate specific issues, like improper configuration or missing settings.
View PaperMC FAQ: Check out the FAQ PaperMC created for their anti-xray option HERE.