# ModBlocker
\n**Restrict which mods are allowed on your server.**<\/p>\n
—<\/p>\n
## \ud83d\udccc Overview<\/p>\n
**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.<\/p>\n
—<\/p>\n
## \u2699\ufe0f Features<\/p>\n
– **Mod Detection** \u2014 Detects client modifications via channel-based handshake inspection (e.g. `wurst:init` identifies the `wurst` client)
\n– **Blacklist & Whitelist Modes** \u2014 Choose between blocking specific mods outright or only allowing an approved list via `use-whitelist-mode`
\n– **Per-Permission Bypass** \u2014 Grant trusted players or staff the ability to bypass restrictions using the `modblocker.bypass` permission node
\n– **Custom Kick Messages** \u2014 Define fully customizable kick messages using **MiniMessage** format with `{player}` and `{mods}` placeholders
\n– **Configurable Check Delay** \u2014 Adjustable tick delay before channel inspection on join, since mod channels are not registered instantly
\n– **Debug Mode** \u2014 Enable debug logging to see all registered player channels in the console
\n– **Reload Support** \u2014 Reload configuration at runtime without restarting the server via `\/modblocker reload`<\/p>\n
—<\/p>\n
## \ud83d\udd27 Commands<\/p>\n
| Command | Description | Permission | —<\/p>\n ## \ud83d\udd11 Permissions<\/p>\n | Permission Node | Description | Default | —<\/p>\n ## \ud83d\udcc4 Configuration<\/p>\n “`yaml # Blacklist mode \u2014 common hack client IDs: # Whitelist mode \u2014 only these mods are allowed (minecraft\/paper\/bukkit always allowed) # Messages \u2014 MiniMessage format | Placeholders: {player}, {mods} —<\/p>\n ## \ud83d\udda5\ufe0f Requirements<\/p>\n – **Server Software:** Paper (1.19+) —<\/p>\n *Found a bug or have a feature request? Contact me on Discord !*<\/p>\n","protected":false},"excerpt":{"rendered":" Restrict which mods are allowed on your server.<\/p>\n","protected":false},"featured_media":104084,"template":"","meta":{"_minecraft_slug":"modblocker","_minecraft_project_id":"1qVJQYqy","_minecraft_author":"az_ttv","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":112,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"modblocker.zip","_minecraft_size_bytes":34578,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T19:31:38.801112Z","_minecraft_date_created":"2026-03-04T23:23:39.461032Z","_minecraft_date_modified":"2026-03-03T01:07:02.752834Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/modblocker","_minecraft_icon_attachment_id":104084,"_minecraft_imported_at":"2026-06-05T23:46:48+00:00","_minecraft_import_hash":"364fe692e22edf57e7e1d466d272e785","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,89,126,127,129,92],"mod_loader":[130,132,134],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-104083","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-game-mechanics","mod_category-management","mod_category-paper","mod_category-spigot","mod_category-utility","mod_loader-bukkit","mod_loader-paper","mod_loader-spigot","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n|—|—|—|
\n| `\/modblocker list` | Displays all currently blocked or whitelisted mods depending on the active mode | `modblocker.admin` |
\n| `\/modblocker check
\n| `\/modblocker add
\n| `\/modblocker remove
\n| `\/modblocker reload` | Reloads the plugin configuration from disk | `modblocker.admin` |<\/p>\n
\n|—|—|—|
\n| `modblocker.admin` | Grants access to all ModBlocker commands (list, check, add, remove, reload) | OP |
\n| `modblocker.bypass` | Bypasses all mod restrictions \u2014 useful for trusted players or staff | false |<\/p>\n
\n# ============================================================
\n# ModBlocker \u2014 Configuration
\n# Block players from joining with certain client mods
\n# ============================================================
\nsettings:
\n # Delay (in ticks) before checking a player’s channels after join.
\n # 40 ticks (2 seconds) is recommended \u2014 channels aren’t registered instantly.
\n check-delay-ticks: 40
\n # Whitelist mode: if true, only mods in ‘whitelisted-mods’ are allowed.
\n # If false, only mods in ‘blocked-mods’ are blocked (blacklist mode).
\n use-whitelist-mode: false
\n # Enable debug logging to see all registered channels in console
\n debug: false<\/p>\n
\nblocked-mods:
\n – wurst
\n – meteor-client
\n – inertia
\n – aristois
\n – kami
\n – lambda
\n – xray
\n – killaura<\/p>\n
\nwhitelisted-mods:
\n – fabric
\n – optifine
\n – sodium
\n – lithium
\n – iris<\/p>\n
\nmessages:
\n kick-message: |
\n
\n
\n
\n
\n no-permission: “
\n“`<\/p>\n
\n– **Java:** Java 17 or higher
\n– **Dependencies:** None \u2014 completely standalone<\/p>\n