Anti-xray on docker compose based minecraft server

I've been managing a Minecraft server with docker compose. It's great, but it took forever to figure out how to configure papermc's anti-xray feature. Hopefully this will save you some time if you have a similar setup.

Problem

I'm running PaperMC in with docker compose using itzg/docker-minecraft-server. Anti-xray is configured with a yml file per world, in its respective directory. I can bind mount these directories, but a i'd rather not mix level data and configuration source files.

Solution

I ended up using the docker image's patch files feature. It seemed tedious and complicated at first, but I found that AI did a good job of writing these when given sufficient context.

To use these patch files yourself, place them in a directory, mount that inside the container and give it's path to the PATCH_DEFINITIONS environment variable. Anti-xray should be enabled when you restart the container.

docker-compose.yml

services:
  mc:
    image: itzg/minecraft-server
    ports:
      - "25565:25565"
    environment:
      EULA: true
      TYPE: "PAPER"
      VERSION: 1.21.8
      PATCH_DEFINITIONS: /patches
    volumes:
      - ./patches:/patches:ro

patches/world-defaults-anti-xray.json

{
  "file": "/data/config/paper-world-defaults.yml",
  "ops": [
    {
      "$put": {
        "path": "$",
        "key": "anticheat",
        "value": {
          "anti-xray": {
            "enabled": true,
            "engine-mode": 3,
            "hidden-blocks": [
              "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"
            ],
            "lava-obscures": false,
            "max-block-height": 64,
            "replacement-blocks": [
              "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"
            ],
            "update-radius": 2,
            "use-permission": false
          }
        }
      }
    }
  ]
}

patches/the-end-anti-xray.json

{
  "file": "/data/world_the_end/paper-world.yml",
  "ops": [
    {
      "$put": {
        "path": "$",
        "key": "anticheat",
        "value": {
          "anti-xray": {
            "enabled": false
          }
        }
      }
    }
  ]
}

patches/nether-anti-xray.json

{
  "file": "/data/world_nether/paper-world.yml",
  "ops": [
    {
      "$put": {
        "path": "$",
        "key": "anticheat",
        "value": {
          "anti-xray": {
            "enabled": true,
            "engine-mode": 3,
            "hidden-blocks": [
              "ancient_debris",
              "bone_block",
              "glowstone",
              "magma_block",
              "nether_bricks",
              "nether_gold_ore",
              "nether_quartz_ore",
              "polished_blackstone_bricks"
            ],
            "lava-obscures": false,
            "max-block-height": 128,
            "replacement-blocks": [
              "basalt",
              "blackstone",
              "gravel",
              "netherrack",
              "soul_sand",
              "soul_soil"
            ],
            "update-radius": 2,
            "use-permission": false
          }
        }
      }
    }
  ]
}

References

Written by Kasper Alfarnes. Published 1st of December 2025.