ModBlocker

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

- Reload Support — Detects client modifications via channel-based handshake inspection (e.g. `wurst:init` identifies the `wurst` client) - Reload Support — Choose between blocking specific mods outright or only allowing an approved list via `use-whitelist-mode` - Reload Support — Grant trusted players or staff the ability to bypass restrictions using the `modblocker.bypass` permission node - Reload Support — Define fully customizable kick messages using Reload Support format with `{player}` and `{mods}` placeholders - Reload Support — Adjustable tick delay before channel inspection on join, since mod channels are not registered instantly - Reload Support — 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

```yaml

============================================================

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

- Dependencies: Paper (1.19+) - Dependencies: Java 17 or higher - Dependencies: None — completely standalone

---

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