CheatDetector 🔍🛡️

CheatDetector is an advanced client-side cheat detection utility for Paper/Spigot servers. It exposes player hacks (like Meteor Client, Wurst, Freecam, ItemScroller, Tweakeroo, etc.) using a unique zero-bypass hybrid sign-translation check, Netty packet interception, and absolute movement lockdown.

✨ Features

• Zero-Bypass Translation Scan: Forces the client to resolve hidden translation components and keybinds, exposing cheat-specific language registers instantly.
• Absolute Tick-0 Lockdown: Freezes movement, blinds vision, blocks chat/commands/portals from the very first tick they join to prevent escaping.
• Naked Inventory Mode: Backs up and completely clears inventories during scans, stopping bypass exploits (like right-clicking DeluxeMenus compasses) with 100% item safety.
• Netty Pipeline Interceptor: Captures player response packets at a low network level, preventing Spigot/Paper or anti-cheat engines from blocking or ignoring packets.
• NoSignGUI Bypass Protection: Kicks players automatically after a 5-second timeout if they use NoSignGUI/AntiSignExploit mods, providing clear troubleshooting instructions.
• Pre/Post Teleportation Options: Teleports players to a secure inspection coordinate before the scan (optionally sending them back after), or teleports them to a spawn/hub location after a successful scan.

---

🏗️ How It Works (The Mechanics)

CheatDetector utilizes client-side rendering behaviors to query the player's client for cheat registries silently and securely.

1. Hybrid Sign-Translation Check

Minecraft translates translation keys (e.g. key.meteor-client.open-gui) and keybinds on the client side using local lang files.

• Vanilla Player: Cannot resolve the key. The client displays the fallback key or text and returns it.
• Modded Player: Instantly resolves it to a readable name (e.g. "Open Click GUI"). The client sends the resolved plain text back to the server. CheatDetector matches this string and flags the cheat.

2. Low-Level Packet Capture (Netty)

Paper engines drop sign update packets if a physical sign block doesn't exist in the world. CheatDetector places a temporary sign in the world for 4 ticks, opens the editor, and hides it by sending an AIR block change to the player. The Netty interceptor captures the incoming response packet before Paper evaluates it, avoiding packet drops and bypasses.

---

📥 Installation & Setup

1. Drop CheatDetector.jar into your server's plugins folder.
2. Restart the server.
3. Open plugins/CheatDetector/config.yml to customize settings, checks, and messages.
4. Run /cd reload in-game or console to apply changes.

---

📝 Configuration (config.yml)

The plugin generates a highly customizable config file:

# Cheat Detector - Configuration

settings:
  # Delay in ticks before the scan starts. (20 ticks = 1 second)
  # 40 ticks is recommended to allow lobby items to load first.
  scan-delay: 40
  
  # Enable/disable the sign translation check system.
  sign-detect: true

  # Hide the temporary sign placement by putting it out of player's sight
  hide-check-location: true
  behind-player-distance: 3
  below-player-min-offset: 2
  below-player-max-offset: 4

  # Teleport the player to a secure location before the check starts
  tp-before-check:
    enabled: false
    world: "world"
    x: 0.0
    y: 100.0
    z: 0.0
    yaw: 0.0
    pitch: 0.0
    restore-old-location: true # Restore their original location upon clean scan completion
  # Teleport the player here after a clean scan completes
  after-check-tp-to-here:
    enabled: false
    world: "world"
    x: 0.0
    y: 100.0
    z: 0.0
    yaw: 0.0
    pitch: 0.0

# Command executed when a cheat is verified.
# %player% -> Player Name, %client% -> Mod Name, %warning% -> Warning message
punish-commands:
  - "kick %player% %warning%"

# Check types: KEYBIND (for key bindings) or TRANSLATABLE (for translation keys)
sign-checks:
  meteor_client_1:
    mode: "TRANSLATABLE"
    key: "key.meteor-client.open-gui"
    fallback: "key.meteor-client.open-gui"
    warning: "Meteor Client is forbidden!"
  freecam_standard_1:
    mode: "KEYBIND"
    key: "key.freecam.toggle"
    warning: "Freecam Mod is forbidden!"
  # [More checks listed in config...]

# Fully customizable messages (Color codes supported)
messages:
  timeout-kick: "&c[CheatDetector] No response to scan!\n\n&7If you are not hacking, this could be caused by:\n&e- Using NoSignGUI, AntiSignExploit, or mods blocking signs.\n&e- Experiencing high ping or connection issues.\n\n&aSolution: Please disable mods that close sign screens and reconnect."
  timeout-admin-log: "&8[&bCheatDetector&8] &e%player% &7did not respond to the sign packet (Timeout/NoSignGUI)."
  cheat-found-admin-log: "&8[&bCheatDetector&8] &c%player% &7was flagged for: &e%cheat%"
  player-clean-admin-log: "&8[&bCheatDetector&8] &a%player% &7is clean (Vanilla)."
  op-bypass-message: "&c[CheatDetector] &7You bypassed the timeout because you are OP, but your client did not respond."
  chat-blocked: "&cYou cannot chat during the scan!"
  command-blocked: "&cYou cannot use commands during the scan!"

➕ How to Add Custom Checks

You can easily expand the detection library by adding your own custom checks inside the sign-checks section of the config.yml.

1. Finding Mod Keys

Open the target mod's .jar file using a zip tool (like WinRAR or 7-Zip), navigate to assets/<mod-id>/lang/en_us.json (or .toml lang files), and find the translation keys for:

• Keybindings (e.g. key.modname.toggle_fly): Set the mode to KEYBIND.
• GUI Titles / Translatable Text (e.g. modname.menu.title): Set the mode to TRANSLATABLE.

2. Adding to config.yml

Insert your new definition under sign-checks:

  my_custom_mod_check:
    mode: "KEYBIND"                   # Either KEYBIND or TRANSLATABLE
    key: "key.custommod.gui"          # The exact translation or keybind key
    fallback: "key.custommod.gui"     # (Optional) Fallback text (ignored in KEYBIND mode)
    warning: "Custom Mod is forbidden!" # Warning shown to player / punisher command

---

🆘 Troubleshooting

• Players are getting kicked for "No response to scan!":
  • This happens when a client uses optimization/utility mods like NoSignGUI or AntiSignExploit which block sign editing screens entirely. Inform players to remove these mods to pass the lobby scan.
  • Check the server connection. High network packet loss/ping might delay the response packet beyond the 5-second timeout window.
• A specific mod is not being detected:
  • Double-check if the mod uses a KEYBIND or TRANSLATABLE check. If it is registered as a keybind in the mod's code, ensure mode is set to KEYBIND in config.yml.
• Players lose lobby items after scan:
  • Ensure the scan-delay in config.yml is set to at least 40 (2 seconds) so lobby plugins have enough time to deliver items before CheatDetector backs them up.