> For the complete documentation index, see [llms.txt](https://wiki.halosdev.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.halosdev.com/halos-anti-xray/overview.md).

# 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](/halos-anti-xray/commands.md) page.

***

### Table of Contents

* [Anti X-Ray](#anti-x-ray)
* [Anti ESP](#anti-esp)
* [Fake Ores](#fake-ores)
  * [Detection & Alerts](#detection-and-alerts)
  * [Per-World Generation](#per-world-generation)
* [Bypass System](#bypass-system)
* [Threads](#threads)
* [Player Data Storage](#player-data-storage)
* [Ghost Block Environment](#ghost-block-environment)
* [Folia Compatibility](#folia-compatibility)
* [Admin Command](#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.

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

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

```yaml
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

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

```yaml
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](/halos-anti-xray/commands.md)). Bypass state is persisted via the configured `player-data` storage and survives restarts.

***

### Threads

Performance tuning per subsystem.

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

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

```yaml
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](https://papermc.io/software/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

```yaml
hax-command: 'hax'
```

Default is `/hax`. Change this if it conflicts with another plugin. See [Commands & Permissions](/halos-anti-xray/commands.md) 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) |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wiki.halosdev.com/halos-anti-xray/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.