ModBlocker

Restrict which mods are allowed on your server.

---

📌 Overview

ModBlocker is a lightweight yet powerful Paper plugin that gives server administrators full control over which client-side mods players are allowed to use. Whether you're running a competitive PvP server, an RPG experience, or a vanilla-faithful community, ModBlocker ensures a fair and consistent environment for all players.

---

⚙️ Features

• Mod Detection — Detects client modifications via channel-based handshake inspection (e.g. wurst:init identifies the wurst client)
• Blacklist & Whitelist Modes — Choose between blocking specific mods outright or only allowing an approved list via use-whitelist-mode
• Per-Permission Bypass — Grant trusted players or staff the ability to bypass restrictions using the modblocker.bypass permission node
• Custom Kick Messages — Define fully customizable kick messages using MiniMessage format with {player} and {mods} placeholders
• Configurable Check Delay — Adjustable tick delay before channel inspection on join, since mod channels are not registered instantly
• Debug Mode — Enable debug logging to see all registered player channels in the console
• Reload Support — Reload configuration at runtime without restarting the server via /modblocker reload

---

🔧 Commands

Command	Description	Permission
/modblocker list	Displays all currently blocked or whitelisted mods depending on the active mode	modblocker.admin
/modblocker check <player>	Checks what mods a connected player has registered	modblocker.admin
/modblocker add <mod>	Adds a mod to the active blacklist or whitelist at runtime	modblocker.admin
/modblocker remove <mod>	Removes a mod from the active blacklist or whitelist at runtime	modblocker.admin
/modblocker reload	Reloads the plugin configuration from disk	modblocker.admin

---

🔑 Permissions

Permission Node	Description	Default
modblocker.admin	Grants access to all ModBlocker commands (list, check, add, remove, reload)	OP
modblocker.bypass	Bypasses all mod restrictions — useful for trusted players or staff	false

---

📄 Configuration

# ============================================================
#  ModBlocker — Configuration
#  Block players from joining with certain client mods
# ============================================================
settings:
  # Delay (in ticks) before checking a player's channels after join.
  # 40 ticks (2 seconds) is recommended — channels aren't registered instantly.
  check-delay-ticks: 40
  # Whitelist mode: if true, only mods in 'whitelisted-mods' are allowed.
  # If false, only mods in 'blocked-mods' are blocked (blacklist mode).
  use-whitelist-mode: false
  # Enable debug logging to see all registered channels in console
  debug: false

# Blacklist mode — common hack client IDs:
blocked-mods:
  - wurst
  - meteor-client
  - inertia
  - aristois
  - kami
  - lambda
  - xray
  - killaura

# Whitelist mode — only these mods are allowed (minecraft/paper/bukkit always allowed)
whitelisted-mods:
  - fabric
  - optifine
  - sodium
  - lithium
  - iris

# Messages — MiniMessage format | Placeholders: {player}, {mods}
messages:
  kick-message: |
    <red><bold>ModBlocker</bold></red>
    <white>Unauthorized mods detected:</white>
    <red>{mods}</red>
    <yellow>Please remove them before joining.</yellow>
  no-permission: "<red>You don't have permission to use this command."

---

🖥️ Requirements

• Server Software: Paper (1.19+)
• Java: Java 17 or higher
• Dependencies: None — completely standalone

---

Found a bug or have a feature request? Contact me on Discord !