Overview

HalosAntiXray

HalosAntiXray protects your Minecraft server against X-Ray and ESP cheating with three independent layers: Anti X-Ray, Anti ESP, and Fake Ores with detection scoring. This page covers every option in config.yml and how to tune it.

For commands and permissions, see the Commands & Permissions page.

---

Table of Contents

• Anti X-Ray

• Anti ESP

• Fake Ores

  • Detection & Alerts

  • Per-World Generation

• Bypass System

• Threads

• Player Data Storage

• Ghost Block Environment

• Folia Compatibility

• Admin Command

---

Anti X-Ray

Prevents X-Ray clients from seeing ore blocks. Each entry maps a list of ores to a single replacement block.

anti-xray:
  replacements:
    - ores:
        - coal_ore
        - iron_ore
        - copper_ore
        - gold_ore
        - redstone_ore
        - emerald_ore
        - lapis_ore
        - diamond_ore
      replacement: stone

    - ores:
        - deepslate_coal_ore
        - deepslate_iron_ore
        - deepslate_copper_ore
        - deepslate_gold_ore
        - deepslate_redstone_ore
        - deepslate_emerald_ore
        - deepslate_lapis_ore
        - deepslate_diamond_ore
      replacement: deepslate

    - ores:
        - nether_gold_ore
        - nether_quartz_ore
        - ancient_debris
      replacement: netherrack

Invalid ore or replacement names are logged as warnings on startup and skipped.

{% hint style="info" %} Match the replacement to the surrounding terrain (stone for the stone layer, deepslate for the deepslate layer, netherrack for the Nether). Mismatched replacements create visible patches. {% endhint %}

---

Anti ESP

Hides container-style blocks (chests, furnaces, hoppers, spawners, etc.) from players until those blocks become visible to them.

anti-esp:
  anti-esp-blocks:
    - chest
    - trapped_chest
    - furnace
    - blast_furnace
    - smoker
    - crafting_table
    - anvil
    - chipped_anvil
    - damaged_anvil
    - enchanting_table
    - end_portal_frame
    - spawner
    - trial_spawner
    - dropper
    - dispenser
    - hopper
    - barrel
    - '*_bed'
    - nether_portal
    - end_portal
    - ender_chest

Pattern matching

Pattern	Matches
chest	Exact match only — chest itself, not trapped_chest or ender_chest
*_bed	Every bed colour (white_bed, orange_bed, …) but not bedrock
*_door	Every door variant (oak_door, iron_door, …)
*bed*	Anything containing bed — including bedrock

Patterns matching zero block types are logged as warnings on startup. Invalid names without wildcards are warned about and skipped.

{% hint style="warning" %} Anti ESP is more expensive than Anti X-Ray. Only add blocks that aren't generated naturally in bulk — adding common natural blocks (stone, dirt) will severely impact server performance. {% endhint %}

---

Fake Ores

Generates decoy ore clusters to detect X-Ray cheaters. Cheaters who try to mine these decoys reveal themselves.

fake-ores:
  enabled: true
  view-distance: 3

Option	Description
enabled	Master switch for fake ore generation.
view-distance	Radius (in chunks) around the player where fake ores are active.

{% hint style="warning" %} Disabling fake-ores.enabled also disables detection scoring. The detection layer depends on fake ores being active. {% endhint %}

Detection & Alerts

fake-ores:
  detection:
    enabled: true
    low-confidence: 30
    high-confidence: 40

    alerts:
      default-enabled: true
      check-interval: 60

Option	Description
detection.enabled	Toggles detection scoring and staff alerts.
low-confidence	Score threshold for a "possible cheater" alert. Lower = more sensitive, more false positives.
high-confidence	Score threshold for a "likely cheater" alert.
alerts.default-enabled	Default alert preference for staff. Each player can override their own via /hax alerts.
alerts.check-interval	How often (in seconds) the plugin re-evaluates player scores for alerting.

Tuning:

• Too many false alerts? Raise the thresholds.

• Suspected cheaters slipping through? Lower the thresholds.

Adjust one threshold at a time and give the server a day or two of activity before re-tuning.

Per-World Generation

Fake ore generation is configured per world. Only worlds listed and marked enabled: true receive fake ores. World names are matched case-insensitively.

fake-ores:
  worlds:
    world:
      enabled: true
      generation:
        - stone-ore-type: coal_ore
          deepslate-ore-type: deepslate_coal_ore
          vein-size: 16
          min-height: 0
          max-height: 127
          rarity: 0.95
        - stone-ore-type: diamond_ore
          deepslate-ore-type: deepslate_diamond_ore
          vein-size: 8
          min-height: -64
          max-height: 16
          rarity: 0.7

    world_nether:
      enabled: true
      generation:
        - ore-type: ancient_debris
          vein-size: 4
          min-height: 0
          max-height: 24
          rarity: 0.65

Option	Description
stone-ore-type	Ore variant used at stone-layer heights (overworld).
deepslate-ore-type	Ore variant used at deepslate-layer heights. Optional — omit to use stone-ore-type everywhere.
ore-type	Single ore type for non-overworld worlds (e.g. Nether) without stone/deepslate variants.
vein-size	Cluster size. Higher = larger veins.
min-height	Minimum Y level for generation.
max-height	Maximum Y level for generation.
rarity	Spawn frequency from 0.0 to just under 1.0. Lower = rarer.

{% hint style="danger" %} Never set rarity to 1.0 or higher. This will freeze the fake-ore generator. Treat the valid range as 0.0 to 0.99. {% endhint %}

{% hint style="info" %} Mirror vanilla ore distributions when picking heights — diamonds at Y=80 look wrong, diamonds at Y=-50 look natural. {% endhint %}

---

Bypass System

Per-player bypass flag — when enabled, that player sees the unfiltered world (all three protection layers skipped). Useful for staff verification and trusted players you don't want flagged.

There is no config option for bypass; it's managed entirely through /hax toggle (see Commands & Permissions). Bypass state is persisted via the configured player-data storage and survives restarts.

---

Threads

Performance tuning per subsystem.

threads:
  fake-ore-generator: 1
  ghost-block-ticker: 2
  outgoing-packet-handler: 4
  force-async-block-checks: false

Option	Recommended	Purpose
fake-ore-generator	1/8 of CPU cores (1/4 for higher view-dist.)	Threads for fake ore generation.
ghost-block-ticker	1/4 of CPU cores	Threads for ongoing block updates.
outgoing-packet-handler	1/2 of CPU cores	Threads for outbound packet processing.
force-async-block-checks	false	See warning below.

{% hint style="danger" %} force-async-block-checks: Disabled by default on Minecraft versions below 1.13 because older Bukkit, Spigot, and Paper builds are not thread-safe. Forcing this on pre-1.13 servers causes ghost blocks and undefined behaviour. Use at your own risk. {% endhint %}

---

Player Data Storage

The plugin persists per-player flags (bypass status, alert preferences) between sessions.

player-data:
  storage: sqlite

Backend	Notes
sqlite	Efficient at any player count. Recommended for production.
yaml	Human-readable, easy to hand-edit, but rewrites the entire file on each change. Use only at small scale.

Unrecognized values fall back to sqlite with a warning logged.

{% hint style="warning" %} Switching backends does not migrate data. Players fall back to defaults until re-flagged. {% endhint %}

---

Ghost Block Environment

Throttles for how aggressively the plugin processes block updates each tick. These are per-player limits.

ghost-block-environment:
  unchecked-ghost-blocks-per-tick: 1500
  tickable-blocks-per-tick: 200

Option	Description
unchecked-ghost-blocks-per-tick	Max new Anti X-Ray block updates processed per tick, per player.
tickable-blocks-per-tick	Max ongoing Anti ESP block updates processed per tick, per player.

Raise if players see delayed ore-reveal on chunk load. Lower if you see tick lag on busy worlds.

---

Folia Compatibility

HalosAntiXray supports Folia. On Folia:

• threads.fake-ore-generator and threads.ghost-block-ticker are ignored — Folia uses its own region-based scheduler.

• threads.outgoing-packet-handler still applies.

• No additional configuration required.

---

Admin Command

hax-command: 'hax'

Default is /hax. Change this if it conflicts with another plugin. See Commands & Permissions for full command and permission details.

---

Quick Reference: Disabling Features

To disable…	Set…
Anti X-Ray for an ore	Remove that ore from anti-xray.replacements
Anti ESP for a block	Remove that block from anti-esp.anti-esp-blocks
Fake ore generation	fake-ores.enabled: false
Detection alerts	fake-ores.detection.enabled: false
Fake ores in one world	fake-ores.worlds.<name>.enabled: false
All staff alerts by default	fake-ores.detection.alerts.default-enabled: false
Protection for one player	/hax toggle <player> (persistent — survives restart)