[INDL] Xray Detected: The Ultimate Resource Pack Guardian

Stop cheaters in their tracks! INDL Xray Detected is a powerful, lightweight anti-cheat solution designed to keep your server fair by detecting X-Ray resource packs in real-time — no server-side world scanning, no lag, no false promises.

Requires the mod on both server AND client. This mod works by having each connected player's client scan their own installed resource packs and report the results back to the server. It must be installed on the server and distributed to your players (as a required client mod) to work.

📖 How does it actually work? (Plain English)

Think of it as a "resource pack inspector" that runs automatically, both when a player joins your server and periodically while they play:

1. A player joins your server. A couple of seconds after logging in, their client quietly scans every resource pack sitting in their resourcepacks folder — in the background, so there's no lag or freezing.
2. The scan checks each pack in several ways:
   • By name — does the pack's file/folder name contain a suspicious word (xray, cheat, wallhack, ore-finder, etc.)?
   • By hidden models — does the pack contain hidden /xray/ folders or blockstate files that redirect solid blocks to invisible models? (This is how most "renamed" X-Ray packs actually work under the hood.)
   • By texture transparency — are textures for solid blocks like Stone, Deepslate, or Dirt suspiciously see-through? The mod measures the percentage of transparent pixels in each texture.
   • By known fingerprint (SHA-256 hash) — does a texture's unique digital fingerprint match a texture from a previously-detected X-Ray pack? This catches renamed packs instantly, without even needing to re-analyze the image.
   • By pack description — does the pack's pack.mcmeta description mention words like "xray" or "see through"?
3. If anything suspicious is found, the client sends a report to the server (this report is sanitized and rate-limited server-side, so it can't be abused to spam or crash the server).
4. The server reacts based on what you configured: it can simply log it, alert your online staff, and/or automatically warn/kick/ban the player — either immediately or through a fair "strike" system (see below).
5. The scan repeats periodically (every few minutes, configurable) in case a player installs an X-Ray pack mid-session, and can also be triggered manually by staff at any time.

Because the check is based on the content of the pack (hidden folders, transparent pixels, known fingerprints) and not just its file name, renaming MyXrayPack.zip to Faithful32x.zip will not fool the detector.

🔒 Why it can't be tampered with (v1.2.0+)

Starting in v1.2.0, the mod's configuration is server-authoritative. In previous versions, each player's client read its own local copy of the settings — meaning a player could, in theory, edit their own config file to turn off scanning or stretch the check interval to make detection meaningless.

That loophole is now closed: your server pushes its configuration to every connecting client automatically (this is a built-in Minecraft Forge mechanism, not something that can be intercepted or spoofed by a modified client config). Only the values YOU set on the server are ever used — a player's local config file is completely ignored for anything that matters.

🔍 Advanced Detection Engine

• JSON Model Analysis: Identifies hidden /xray/ folders and transparent model definitions.
• Blockstate Surveillance: Scans for redirects to illegal transparent models.
• Smart Transparency Check: Analyzes PNG files for suspicious transparency on solid blocks like Stone, Deepslate, or Dirt.
• SHA-256 Hash Database: Instantly detects known X-Ray textures by their unique hash signature, even if renamed.
• pack.mcmeta Analysis: Scans pack descriptions for suspicious keywords like "xray", "cheat", or "wallhack".
• Self-Learning: Every newly detected transparent texture is automatically remembered, so the next time it's seen (even in a different, renamed pack) it's caught instantly.
• Deep Mod Support: Ready for the most popular mods including Aether, Biomes O' Plenty, and Create.

⚡ Key Features

• ✅ Automatic Scans: Runs instantly when a player joins and at configurable intervals afterwards.
• ✅ Real-Time Staff Alerts: Detailed in-chat notifications for OPs with the exact reason for detection.
• ✅ Bypass Proof: Detects X-Ray regardless of the filename, and (as of v1.2.0) regardless of client-side config tampering.
• ✅ Zero Lag: Optimized code with async scanning (runs on a background thread) and smart caching.
• ✅ Fully Configurable: Customize keywords, whitelist trusted packs, and set scan times — all from the server.
• ✅ Progressive Strike System: Give players fair warnings before kick/ban, instead of an instant hammer.
• ✅ Smart Scan Cache: Avoids re-scanning unchanged packs for better performance.
• ✅ Global Statistics: Track total scans, detections, kicks, and bans over time.
• ✅ Admin Scan Command: Force an immediate rescan on any player.
• ✅ Rate Limiting: Prevents report spam and abuse from reaching your server/log files.

🧬 SHA-256 Hash Detection — how the "fingerprint" system works

Every texture file has a unique digital "fingerprint" called a SHA-256 hash — a 64-character code calculated from its exact pixel data. Even if a cheater renames their X-Ray pack or its files, the fingerprint of the underlying image never changes:

stone.png (transparent xray texture) → Hash: "a3f8b2c1..."
piedra.png (same file, renamed)      → Hash: "a3f8b2c1..." ✅ Still matches, still detected!

Detection flow for each texture

Texture Found
      ↓
Calculate SHA-256 Hash
      ↓
Exists in known-hash database?
      ↓                    ↓
     YES                   NO
      ↓                    ↓
🔴 DETECTED           Analyze pixel transparency
 (instant, cheap)           ↓
                      Is it suspiciously transparent?
                            ↓
                           YES → Remember this hash + 🔴 DETECTED
                           NO  → ✅ Looks fine

Self-learning database 🧠 (server-side as of v1.2.1)

Whenever a new suspicious transparent texture is found on any connected client, its hash and a short description are sent to the server as part of the detection report. The server (not the client) validates and remembers it. This means:

• The database is shared by your entire server — once one player's pack is fingerprinted, every other player benefits instantly, not just the one who triggered the scan.
• You, the admin, can actually find and edit the file — it lives on your server, not scattered across your players' individual computers.
• Hashes are collected no matter how the pack was originally flagged (by name, by pack.mcmeta, by hidden /xray/ folders, or by the transparency check itself) — as long as a genuinely transparent block texture is found in it.

Older versions (before v1.2.1) mistakenly saved discovered hashes to the client's own config folder, where the server admin could never see or benefit from them. This has been fixed — the file is now created and updated exclusively on the server.

Where the file lives & adding your own known hashes (optional, advanced)

This is the same single file used for both automatic learning and manual editing — there's no separate "auto" file vs. "admin" file:

config/xraydetected/known_hashes.txt on your server

You can open it in any text editor and add/remove lines yourself at any time:

# Format: hash # description  (the description is optional)
a3f8b2c1d4e5f6789...deadbeef # Popular Xray Pack v2
b7c9d0e1f2a3b4c5...cafef00d # Stone Transparent Texture

Note: as of v1.2.0 the mod ships with no pre-loaded example hashes (previous placeholder entries were unverifiable and have been removed) — the database grows organically as your server detects real X-Ray packs, or you can seed it yourself with confirmed hashes. Run /xraydetected reload after editing this file manually to apply changes without restarting.

Performance comparison

• Without hash match: analyzes every pixel of the texture (~50–100ms, a bit of CPU work).
• With hash match: compares a 64-character string (~0.1ms) — effectively free.

🛡️ Progressive Strike System — fair warnings before punishment

Instead of an instant, potentially unfair kick/ban on the very first detection (which could be a false positive), the mod can use a strike system:

Strikes automatically reset after a configurable time period (default: 1 week) if the player stops triggering detections — so an old, resolved false positive doesn't follow them forever. You can view or clear anyone's current strikes with /xraydetected strikes.

🛠️ Commands & Permissions

Note: All commands require OP Level 2 or higher.

⚙️ Configuration — where to find it and how to edit it

📍 File location

As of v1.2.0, the configuration file is server-authoritative and lives inside your world save folder, not in the global config/ folder:

• Dedicated server: <server folder>/world/serverconfig/xraydetected-server.toml (replace world with your actual level-name if you changed it in server.properties)
• Singleplayer / LAN world: saves/<your world name>/serverconfig/xraydetected-server.toml

The file is created automatically with sensible defaults the first time the world/server starts with the mod installed — you don't need to create it by hand. Just start the server once, stop it, edit the file, and start it again (or use /xraydetected reload for most settings without a restart).

🔒 Why this matters

Because this file lives on the server and is a SERVER-type Forge config, Forge automatically sends its values to every connecting client, overriding anything the player might have locally. In other words: you, the server owner, are always in control — players cannot weaken detection by editing their own client files.

✏️ How to edit it

1. Stop your server (or at least be ready to use /xraydetected reload afterwards for most changes to apply without a full restart).
2. Open xraydetected-server.toml in any plain text editor (Notepad, VS Code, Notepad++, etc.).
3. Change the value you want (see the reference below — every option has a comment above it explaining what it does).
4. Save the file, then either restart the server or run /xraydetected reload in-game/console.

📋 Full configuration reference

[detection]
# Keywords that mark a pack name as suspicious (case-insensitive, partial match)
keywords = ["xray", "x-ray", "ore-finder", "cheat", "fullbright", "wallhack"]

# Pack names to always ignore, e.g. legitimate shader/ray-tracing packs
whitelist = ["raytracing", "rtx", "seus", "bsl"]

# If true, actually open and analyze pack contents (folders/textures), not just the name.
# Slower but far more accurate — strongly recommended to keep enabled.
scanPackContent = true

# How often (in minutes) to automatically re-scan a player's resource packs while
# they're online. Set to 0 to only scan once, right when they join.
checkIntervalMinutes = 5

# If true, compare texture fingerprints (SHA-256) against the known-hash database
# for instant detection of previously-seen X-Ray textures.
useHashDatabase = true

# If true, also scan each pack's pack.mcmeta description for suspicious wording.
analyzePackMcmeta = true

[performance]
# Maximum number of files to inspect inside a single ZIP resource pack, to prevent
# lag/abuse from unusually large or malicious pack files. 0 = unlimited.
maxZipEntries = 5000

# If true, remember scan results for unchanged packs so they aren't re-scanned
# every single interval — meaningfully reduces CPU usage on repeat scans.
useScanCache = true

[actions]
# If true, ping all online staff (OPs) in chat the moment something is detected.
notifyAdmins = true

# If true, automatically kick players once they've been detected enough times
# (see [strikes] below, or immediately if useStrikeSystem = false).
autoKick = false

# If true, automatically ban players once they've been detected enough times.
# Use with caution — make sure your detection settings fit your community first!
autoBan = false

# Delay (in seconds) between a detection and the resulting auto-kick/auto-ban,
# giving staff a short window to intervene/verify manually if needed.
actionDelaySeconds = 10

# Message shown to a player when they are auto-kicked for xray.
kickMessage = "Xray texture pack detected! Remove it and rejoin."

# Message shown to a player when they are auto-banned for xray.
banMessage = "Banned for using Xray texture pack. Appeal at your server's Discord."

[strikes]
# If true, use the progressive warning system instead of punishing on the very
# first detection. Strongly recommended to avoid false-positive overreactions.
useStrikeSystem = true

# How many total detections ("strikes") before autoKick triggers.
strikesBeforeKick = 2

# How many total detections ("strikes") before autoBan triggers.
strikesBeforeBan = 3

# After this many hours with no new detections, a player's strikes reset to 0.
# Set to 0 to never reset automatically. Default is 168 hours (1 week).
strikeResetHours = 168

[logging]
# If true, write every detection to config/xraydetected/logs/ (both a global log
# and a per-player log file) for later review.
logToFile = true

# If true, also print detections to the server console/log.
logToConsole = true

📊 Global Statistics

Track your server's security posture at a glance with /xraydetected stats:

• Total scans performed
• Total detections
• Total kicks & bans
• Most frequently detected packs
• Daily statistics

❓ Frequently Asked Questions

Do my players need to install anything? Yes — this mod must be installed on both the server and every client that connects, since the actual scanning happens on the client side. Mark it as a required client-side mod in your modpack/launcher.

What if a player refuses to install the mod, or their client "fails" to load it? Standard Forge behavior applies: if you mark the mod as mandatory in your modpack, players without it (or with a mismatched version) will be blocked from connecting, same as any other required mod.

Will this cause false positives on legitimate shader/resource packs? It's designed to minimize them (the whitelist option exists exactly for this — ray-tracing/shader packs like SEUS, BSL, and Complementary are whitelisted by default), but if you find a false positive, just add the pack's name to the whitelist list in the config and reload.

Can a player bypass this by editing their own files? Not the configuration (fixed in v1.2.0, see the security section above). The detection logic itself runs from the mod's own code, which is loaded the same way for every client — a player would need to build and distribute a modified/patched version of the mod itself to bypass detection outright, which is a much higher bar than simply editing a text file.

Does this lag the server or the client? No. Scanning always runs asynchronously on a background thread, never on the main game/server thread, and results are cached so unchanged packs aren't re-scanned unnecessarily.

I just updated from v1.1.0 (or older) — why does the config look empty/reset? As explained above, v1.2.0 moved the configuration file to a new location and a new Forge config type (world/serverconfig/xraydetected-server.toml). Your old config/xraydetected-common.toml is no longer used — copy over your preferred values manually into the new file.

⚠️ Important Notes

• Players must have the mod installed client-side for scanning to actually happen — the server cannot scan a player's local files by itself.
• The mod acts as an honest-effort detection layer for your community; it is not a substitute for reviewing suspicious in-game behavior manually.
• False positives are rare and can be easily resolved via the whitelist option in the config file.
• v1.2.0 moves the config file to a new location (world/serverconfig/xraydetected-server.toml) — see the FAQ above.