Описание
# ViperAntiXray (1.21.x 26.x)
---
## What Is ViperAntiXray?
ViperAntiXray is a **server-side only** Fabric mod that completely eliminates X-ray cheating by obfuscating chunk packets sent to clients. Unlike texture-pack based solutions or client-side "anti-cheat" mods, ViperAntiXray operates at the network layer the server sends fake block data for unexposed ores, and only reveals real blocks when players legitimately mine adjacent blocks, trigger explosions, or gain direct line-of-sight.
**Key differentiator:** Zero client installation required for per tick packet precisison, to eliminate fake ore discovery even on high ping. Vanilla players connect normally and see legitimate world generation. X-ray users see only stone, deepslate, and configurable fake ores.
---
## Core Anti-Xray Engine (Unmodified)
The heart of ViperAntiXray is a **faithful port of Paper's Async Anti-Xray patch** the same battle-tested engine protecting thousands of Paper/Spigot servers since 1.17. We did **not** modify the core obfuscation logic. Instead, we wrapped it in a Fabric/Architectury module and extended it with event-driven feature modules.
### Engine Modes
| Mode | Name | Behavior | Performance | Best For |
|------|------|----------|-------------|----------|
| **1** | **Hide** | Replace all fully obscured (no air around) blocks from `hiddenBlocks` with blocks from `replacementBlocks` | Lowest CPU | Budget servers, basic protection |
| **2** | **Multiply** | Replace all blocks from `hiddenBlocks` and `replacementBlocks` with random blocks from `hiddenBlocks` | Medium CPU | High-value economies, anarchy |
| **3** | **Smart (Recommended)** | Works very similar to engine mode 2, but works better with slow connections | Medium CPU | General purpose, mixed ping |
### How It Works (Simplified)
```
Chunk Packet Sent Async Worker Thread Palette Analysis Block Classification
Reveal? Adjacent Air/Transparent? Hidden Block?
Yes Send Real Block No Send Fake/Replacement
```
- **Async processing:** Chunk packet transformation runs on dedicated worker threads (configurable pool size)
- **Zero main-thread impact:** World generation, entity ticking, and player movement never block on obfuscation
- **Per-dimension config:** Each dimension can use different engine modes, heights, and block lists
> **Enhance your server setup!** Check out my other server-side mods over at : [Fabric Server Essentials](https://modrinth.com/organization/fabric-server-essentials)
---
## Configuration
**File:** `config/viperantixray-fabric.toml` (auto-generated on first run)
### Default Configuration
```toml
# Default values
enabled = false
usePermission = false
# World specific values
[overworld]
enabled = true
engineMode = 3
maxBlockHeight = 256
updateRadius = 2
lavaObscures = false
hiddenBlocks = ["#c:ores", "raw_copper_block", "raw_iron_block", "raw_gold_block", "!#viperantixray:hidden_only_ores"]
replacementBlocks = ["#viperantixray:hidden_only_ores", "stone", "deepslate", "andesite", "calcite", "diorite", "dirt", "granite", "gravel", "sand", "tuff", "mossy_cobblestone", "obsidian", "clay", "infested_stone", "amethyst_block", "budding_amethyst", "chest"]
[the_nether]
enabled = true
engineMode = 1
maxBlockHeight = 128
updateRadius = 2
lavaObscures = true
hiddenBlocks = ["ancient_debris", "nether_quartz_ore", "nether_gold_ore", "gold_block", "gilded_blackstone"]
```
### Config Option Overview
| Option | Type | Description |
|--------|------|-------------|
| `enabled` | `bool` | If set to true, anti-xray will be active in the specified world |
| `engineMode` | `int` | Can be 1, 2, or 3 see [Engine Modes](#engine-modes) |
| `maxBlockHeight` | `int` | Controls the max height at which blocks should get obfuscated |
| `updateRadius` | `int` | Controls how many blocks away from shown blocks obfuscation should start (if your players see fake ores, increase this value) |
| `lavaObscures` | `bool` | If true, blocks next to lava will get obscured |
| `hiddenBlocks` | `string[]` | List of blocks to hide (Engine mode 1) or list of blocks to use for obfuscation (Engine mode 2/3) |
| `replacementBlocks` | `string[]` | List of blocks that will be obfuscated, but not used as fake blocks (Engine mode 2/3 only) |
> **Note:** Blocks / block tags can be prefixed `!` to remove them from the block list. Rules are applied left-to-right; removals should be specified after additions. (since 1.4.10)
### Custom Dimensions
To configure ViperAntiXray in custom dimensions, specify the dimension ID:
```toml
[dimensions."custom:cool_world"]
enabled = true
engineMode = 3
maxBlockHeight = 256
updateRadius = 2
lavaObscures = false
hiddenBlocks = ["#c:ores", "raw_copper_block"]
replacementBlocks = ["stone", "deepslate"]
```
---
## Engine Mode Details
### EngineMode 1 Hide
Replaces all **fully obscured** (no air around) blocks from `hiddenBlocks` with blocks from `replacementBlocks`. Only hidden blocks completely surrounded by other blocks are affected.
### EngineMode 2 Multiply
Replaces **all** blocks from `hiddenBlocks` and `replacementBlocks` with random blocks from `hiddenBlocks`. Creates a field of fake ores that overwhelm X-ray HUDs.
### EngineMode 3 Smart (Recommended)
Works very similar to engine mode 2, but works better with slow connections. Uses packet coalescing to reduce desync for high-ping players.
### Legit Player View
Legit players won't notice any changes when this mod is installed (unless they have high ping or modify a lot of blocks at once, e.g., explosions).
---
## Mod Developers
Ore blocks added to the `#viperantixray:hidden_only_ores` block tag will be hidden from the world, but **not used as fake ore**. This is useful if your ore has effects (particles, sounds) that could cause problems.
```json
// data/viperantixray/tags/block/hidden_only_ores.json
{
"replace": false,
"values": [
"mymod:custom_ore",
"mymod:rare_gem_ore"
]
}
```
---
## What Was Added (11 New Feature Modules)
All features are implemented as **independent modules** in `me.drex.viperantixray.common.features.*` they hook via Fabric events and **never touch the core engine**.
---
### 1. Honey-Pot / Fake Ore Traps
> **Generates fake ore veins deep underground that only X-ray users can see. Mining them instantly flags the cheater.**
- **Placement:** Configurable density per chunk (default: 0.1% of blocks below Y=16)
- **Blocks:** Diamond, Emerald, Ancient Debris, custom ores via tag `#viperantixray:honey_pots`
- **Detection:** When a player mines a honey-pot block:
- Increments `suspicion_score` in `viperantixray:player_data` NBT
- Sends alert to all ops with `viperantixray.alerts` permission
- Optional Discord webhook with embed (player, coords, block, timestamp)
- Logs to `logs/viperantixray/honeypot.log` (JSONL format for SIEM ingestion)
---
### 2. Mining Analytics & Suspicion Scoring
> **Tracks every block break per player, computes Mining Efficiency Ratio (ores/stone), and flags statistical outliers.**
- **Metrics:** `total_blocks_mined`, `ores_mined` (by type), `stone_broken`, `efficiency_ratio = ores / stone`, `session_time`, `chunks_visited`, `depth_distribution`
- **Suspicion Algorithm:** Rolling mean/stddev per dimension; flagged when `efficiency_ratio > mean + (threshold * stddev)` (default: 3.5)
- **Commands:** `/viperantixray audit `, `/viperantixray auditlist`
---
### 3. Proximity & Raycast Decaying
> **Dynamically disables obfuscation along the player's direct line of sight using fast voxel raycasting.**
- **Raycast every N ticks** (default: 4 ticks = 5x/sec per player)
- **Radius:** Configurable cone angle (default: 15) and distance (default: 48 blocks)
- **Bandwidth savings:** ~40% fewer fake blocks sent to clients on high-pop servers
---
### 4. Adaptive Engine Modes
> **Automatically downgrades engine mode under load to prevent ghost blocks, desync, and TPS crashes.**
| Trigger | Condition | Action | Recovery |
|---------|-----------|--------|----------|
| **Low TPS** | TPS < 18.0 for 10s | Mode 32, Mode 21 | TPS > 19.5 for 30s upgrade |
| **High Ping** | Avg ping > 250ms | Mode 32, Mode 21 | Ping < 200ms for 60s upgrade |
| **Packet Queue** | Async queue > 80% | Immediate downgrade | Queue < 40% upgrade |
| **Memory** | Heap > 85% | Mode 31 immediately | Heap < 70% upgrade |
---
### 5. Async Thread Pool
> **Offloads entire chunk packet obfuscation pipeline off the main thread.**
- **Worker threads:** Configurable (default: CPU cores / 2, min 2, max 8)
- **Queue:** Bounded blocking queue (default: 128 chunks)
- **Backpressure:** Falls back to synchronous processing if queue full (logged)
---
### 6. Sub-Chunk Culling
> **Restricts obfuscation to sub-chunks (161616) at or below player's Y-level + margin.**
- **Culling logic:** Only process sections where `sectionY > 4) + cullingMargin`
- **Default margin:** 2 sections (32 blocks above player)
- **Savings:** ~60% fewer palette analyses per chunk packet on surface players
---
### 7. Sound & Light Concealment
> **Mutes block sounds for fully encased blocks, defeating sound-based ESP/X-ray.**
- **Blocks covered:** Amethyst chimes, Sculk vibrations, Lava pops, Pointed dripstone drips
- **Mechanism:** Fully surrounded sound-emitting blocks never send the state that triggers sounds
---
### 8. Explosion & Vein-Miner Protection
> **Batch-reveals all hidden ores in a single packet during large-scale block destruction.**
- **Triggers:** TNT, beds, respawn anchors, VeinMiner/Excavator, WorldEdit, large creepers
- **Mechanism:** Collects changes in 5-tick window, sends ONE consolidated chunk packet
- **Prevents:** Ghost stone rendering lag, desync, client FPS drops
---
### 9. Built-in Dimension Profiles
> **Zero-config protection for vanilla and popular modded dimensions.**
Pre-configured profiles for: Overworld, Nether, End, Deep Dark, Aether, Twilight Forest, Betweenlands (auto-detected if mod present).
---
### 10. In-Game Admin Inspection
> **Ops in spectator mode can toggle "Anti-Xray Vision" to see exactly what players see instantly, no relog.**
- **Command:** `/viperantixray inspect [on|off|toggle]`
- **Visual:** Obfuscated blocks highlighted with green outline particles (client-side only)
- **HUD:** Engine mode, culling status, async queue depth, TPS impact
---
### 11. Live Block List Editing
> **Modify hidden/replacement blocks at runtime with instant hot-reload no server restart.**
| Command | Example | Description |
|---------|---------|-------------|
| `/viperantixray addhidden ` | `addhidden minecraft:copper_ore` | Add to hidden list |
| `/viperantixray removehidden ` | `removehidden minecraft:copper_ore` | Remove from hidden list |
| `/viperantixray addreplacement ` | `addreplacement minecraft:dirt` | Add to replacement list |
| `/viperantixray removereplacement ` | `removereplacement minecraft:dirt` | Remove from replacement list |
| `/viperantixray listhidden` | | Show current hidden blocks |
| `/viperantixray listreplacements` | | Show current replacement blocks |
| `/viperantixray reload` | | Hot-reload config.toml |
- **Supports tags:** `#c:ores`, `#minecraft:deepslate_ores`, `#viperantixray:honey_pots`
- **Negation:** `!#tag` removes from list (processed left-to-right)
---
## Commands Reference
| Command | Aliases | Permission | Description |
|---------|---------|------------|-------------|
| `/viperantixray` | `/vx`, `/antixray` | `viperantixray.admin` | Show help |
| `/viperantixray status` | `st` | `viperantixray.admin` | Engine status, TPS, queue, workers |
| `/viperantixray inspect [on\|off\|toggle]` | `ins` | `viperantixray.inspect` | Toggle X-ray vision |
| `/viperantixray audit ` | `aud` | `viperantixray.admin` | Show mining stats & suspicion |
| `/viperantixray auditlist` | `audl` | `viperantixray.admin` | Top 20 suspicious players |
| `/viperantixray addhidden ` | `ah` | `viperantixray.admin` | Add to hidden list |
| `/viperantixray removehidden ` | `rh` | `viperantixray.admin` | Remove from hidden list |
| `/viperantixray addreplacement ` | `ar` | `viperantixray.admin` | Add to replacement list |
| `/viperantixray removereplacement ` | `rr` | `viperantixray.admin` | Remove from replacement list |
| `/viperantixray listhidden` | `lh` | `viperantixray.admin` | List hidden blocks |
| `/viperantixray listreplacements` | `lr` | `viperantixray.admin` | List replacement blocks |
| `/viperantixray reload` | `rl` | `viperantixray.admin` | Hot-reload config |
| `/viperantixray alerts` | `al` | `viperantixray.alerts` | View honeypot triggers |
| `/viperantixray version` | `ver` | | Show mod version |
**Permission defaults:** All `viperantixray.*` default to **op only**. Use LuckPerms to grant to staff roles.
---
## Performance Benchmarks
*Tested on: i7-12700K, 32GB DDR5-5600, Paper 1.21.1 baseline, 20 players simulated via Spark profiler*
| Scenario | Players | Mode | TPS Impact | Heap | Avg Chunk Latency |
|----------|---------|------|------------|--------|-------------------|
| Vanilla survival | 20 | 3 | **