Phantom

Phantom is an advanced anti-xray plugin for Paper and Folia servers. It hides underground terrain, ores, containers, entities, dungeons, mineshafts, and other valuable information until players legitimately see that area.

Instead of only replacing individual ores, Phantom conceals deeper terrain and reveals it naturally as players travel underground. A ray tracer then shows ores, containers, and entities only when the player has a clear line of sight. This makes cave-finder, freecam, xray, and underground structure exploits far less useful while keeping normal gameplay smooth.

Features

• Hides underground terrain from players above the configured reveal level
• Reveals caves and tunnels naturally as players explore
• Ray-traced ore and container hiding — blocks stay hidden until the player’s eye has line of sight
• Ray-traced entity hiding — living entities stay hidden until they are actually visible
• Conceals dungeon and mineshaft spawner rooms until the player is close
• Optional amethyst geode hiding (off by default)
• Optional memory of chunks a player has already seen (remember-visited, off by default)
• Cave decorations like glow lichen and dripstone do not seal tunnels from reveal rays
• Per-world enable and disable lists
• Configurable replacement block
• Optional permission bypass
• Optional skip for Geyser/Floodgate players
• Existing config.yml files keep their values; missing keys are added on load
• Paper and Folia support
• Performance controls for larger servers

Recommended Paper Anti-Xray Setup

For the best protection, use Phantom alongside Paper’s built-in anti-xray with Engine Mode 1 enabled.

Paper Engine Mode 1 randomly replaces ores so clients cannot trust raw chunk data. Phantom then adds deeper terrain hiding, ray-traced ore and entity reveal, structure concealment, and exploration-based cave visibility. Using both provides much stronger coverage than either system alone.

Do not use Paper Engine Mode 2 with Phantom. Phantom already handles per-block ore hiding with line-of-sight reveal.

Installation

1. Download Phantom-1.2.0.jar.
2. Place it in your server’s plugins folder.
3. Restart the server.
4. Configure Phantom in plugins/Phantom/config.yml.
5. Use /phantom status to confirm protection is active.

Phantom requires PacketEvents 2.13.0. If PacketEvents is not already installed, Phantom will attempt to download and load that version automatically.

Commands

Alias: /ph

• /phantom — Show command help
• /phantom help — Show command help
• /phantom status — View the current protection status
• /phantom on — Enable protection
• /phantom off — Pause protection
• /phantom reload — Reload the configuration and resync online players
• /phantom refresh <player> — Refresh a player’s terrain
• /phantom refreshall — Refresh all online players
• /phantom check [player] — Inspect a player’s protection state
• /phantom worlds — View configured and loaded worlds
• /phantom version — Show the installed version

Permissions

• phantom.admin — Access all Phantom commands
• phantom.bypass — Bypass protection when access.allow-bypass is true

Default Configuration

# Phantom — anti-xray protection
# Toggle everything without unloading the plugin.
enabled: true

# ---------------------------------------------------------------------------
# Depth (block Y)
# ---------------------------------------------------------------------------
# Terrain at or below this Y is replaced with the fill block for protected clients.
mask-y: 16
# Players at or below this Y are treated as "revealed" (no depth obfuscation).
# Should usually be at or above mask-y.
clear-y: 24

# ---------------------------------------------------------------------------
# Worlds
# ---------------------------------------------------------------------------
worlds:
  # Worlds where Phantom protection is enabled. At least one world is required.
  enabled:
    - world
  # Worlds where Phantom protection is always disabled (even if also listed under enabled).
  disabled:
    - world_nether
    - world_the_end
    - spawn

# ---------------------------------------------------------------------------
# Access
# ---------------------------------------------------------------------------
access:
  # When true, players with phantom.bypass skip protection.
  allow-bypass: true
  # Skip Geyser/Floodgate players (UUID starts with 000000).
  skip-bedrock-players: false

# ---------------------------------------------------------------------------
# Fill (what hidden terrain looks like)
# ---------------------------------------------------------------------------
fill:
  enabled: true
  # Any solid block material name (e.g. DEEPSLATE, STONE, NETHERRACK).
  block: DEEPSLATE

# ---------------------------------------------------------------------------
# Structures
# ---------------------------------------------------------------------------
structures:
  dungeons:
    enabled: true
    # Resend a dungeon room when the player is this close (blocks).
    reveal-distance: 6
    # Nearby cobblestone/mossy cobblestone required to treat a spawner as a vanilla dungeon.
    min-cobblestone: 5
    # Helps avoid hiding custom spawner builds. Set 0 to only require cobblestone/chests.
    min-mossy-cobblestone: 2

  amethyst-geodes:
    enabled: false
    # Resend a geode when the player is this close (blocks).
    reveal-distance: 6
    # Minimum nearby amethyst blocks/buds plus geode-shell signature blocks.
    min-signature-blocks: 4

  mineshafts:
    enabled: true
    # Resend a mineshaft spawner room when the player is this close (blocks).
    reveal-distance: 6
    # Hide spawner rooms that have at least this many nearby cobwebs.
    min-cobwebs: 6

# ---------------------------------------------------------------------------
# Reveal (ray-based cave / tunnel visibility)
# ---------------------------------------------------------------------------
reveal:
  # How often (in ticks) to re-evaluate visibility for online players.
  check-every-ticks: 2
  # When true, chunks that leave the reveal area are hidden again for that player.
  # When false, once revealed they stay visible for the session.
  rehide-when-leaving: false
  # When true, chunks a player has already seen stay unobfuscated and are saved to visited.sqlite.
  # Set true to remember visited chunks.
  remember-visited: false
  # Skip redundant movement-triggered reveal work when the player barely moved. The periodic
  # check-every-ticks retry still reruns the trace for chunk-loading races.
  optimized-movement: true
  # Base number of rays cast for cave visibility (higher = denser, more CPU).
  ray-count: 64
  # Extra chunks beyond the calculated radius to keep visible.
  extra-chunk-radius: 3
  # Hard ceiling on reveal radius in chunks.
  max-chunk-radius: 4

  # Continuously re-send nearby chunks while a player is underground.
  continuous:
    enabled: true
    radius: 4
    # Max chunks queued for resend per player per tick (higher = faster catch-up, more bandwidth).
    max-chunks-per-tick: 192
    # Soft cap on total revealed chunks tracked per player (0 = unlimited).
    total-limit: 0

# ---------------------------------------------------------------------------
# Ore trace (RayTraceAntiXray-style per-block hiding)
# ---------------------------------------------------------------------------
# Air-exposed ores and containers are replaced with stone / deepslate /
# netherrack / end stone when a chunk is sent. A background ray tracer then
# reveals a block only when the player's eye has a clear line of sight to it.
ore-trace:
  enabled: true
  # Also trace third-person (F5) camera positions. More CPU.
  third-person: false
  # Blocks farther than this stay in their last hidden/revealed state.
  distance: 64.0
  # Re-hide blocks the player can no longer see.
  rehide: true
  # At or beyond this distance a previously revealed block is treated as hidden.
  rehide-distance: 60.0
  # Cap on initially hidden, ray-traced positions per chunk (bottom-up).
  max-blocks-per-chunk: 100
  # How often (in ticks) to re-trace tracked ores.
  update-ticks: 2
  # Empty list uses the built-in ore + container catalog.
  blocks: []
  # Materials that stay revealed once seen, even if rehide is true.
  never-rehide: []

# ---------------------------------------------------------------------------
# Entity trace (ray-traced entity hiding)
# ---------------------------------------------------------------------------
# Living entities are hidden until a line of sight from the player's eye is
# clear. Work is budgeted and skipped when neither the viewer nor the entity
# moved enough.
entity-trace:
  enabled: true
  distance: 64.0
  rehide: true
  # Max entities traced per player per tick.
  max-per-tick: 48
  hide-players: false
  hide-items: false
  hide-projectiles: false

# ---------------------------------------------------------------------------
# Performance
# ---------------------------------------------------------------------------
performance:
  # Prefer handling packet work off the main server thread when possible.
  # Disable only if you hit async-related errors.
  async-packets: true
  # Background worker threads for obfuscation/reveal work.
  worker-threads: 2

Compatibility

• Paper
• Folia
• Minecraft 1.21.x
• Java 21
• PacketEvents 2.13.0

For the strongest anti-xray setup, combine Phantom with Paper Anti-Xray Engine Mode 1.