# ModGuard<\/p>\n
**Server-side mod and hack-client detection for Paper\/Spigot Minecraft servers. Detects disallowed client modifications and kicks, bans, logs, or restricts them based on your rules. No client-side companion mod required.**<\/p>\n
—<\/p>\n
## Requirements<\/p>\n
– Paper 1.21 or later
\n– Java 21 or later
\n– Optional: ViaVersion for cross-version client support<\/p>\n
—<\/p>\n
## Installation<\/p>\n
1. Drop `ModGuard.jar` into your server’s `plugins\/` folder
\n2. Restart the server
\n3. Edit `plugins\/ModGuard\/config.yml` and `plugins\/ModGuard\/messages.yml`
\n4. Run `\/mg reload` to apply changes<\/p>\n
—<\/p>\n
## Configuration<\/p>\n
`config.yml`<\/p>\n
“`yaml
\nsettings:
\n punishment: kick # Default: kick, ban, log, disable
\n log-detections: true # Log to console
\n notify-admins: true # Alert players with modguard.notify
\n scan-delay-ticks: 20
\n rescan-interval-ticks: 1200
\n bypass-uuids: []<\/p>\n
detection:
\n brand: true
\n channels: true
\n sign-scan: true<\/p>\n
scan-protection:
\n blackout: true # Black screen during verification
\n freeze-movement: true
\n block-inputs: true
\n prevent-damage: true
\n prevent-falling: true<\/p>\n
minimap-control:
\n enabled: false # Restrict minimaps for ALL players
\n xaero-minimap: true
\n xaero-worldmap: true
\n journeymap: true
\n voxelmap: true
\n“`<\/p>\n
## Adding a blocked mod<\/p>\n
### Minimum required:<\/p>\n
“`yaml
\nmods:
\n cool-mod:
\n name: “Cool Mod”
\n punishment: kick
\n“`<\/p>\n
### Full options:<\/p>\n
“`yaml
\nmods:
\n cool-mod:
\n name: “Cool Mod”
\n channels: [“cool-mod:”, “cool”] # Channel patterns (wildcards supported)
\n brands: [“coolclient”] # Client brand strings
\n keys: # Translation keys from the mod’s lang file
\n – “key.cool-mod.toggle”
\n – “category.cool-mod”
\n punishment: ban # kick \/ ban \/ log \/ disable
\n“`<\/p>\n
If you don’t specify `channels:` or `keys:`, sensible defaults are auto-generated from the mod’s ID.<\/p>\n
## Punishment types<\/p>\n
| Type | Behavior |
\n|——|———-|
\n| `kick` | Disconnect with a kick message |
\n| `ban` | Add to the server banlist |
\n| `log` | Record the detection, take no action |
\n| `disable` | Restrict the mod’s features (Xaero, JourneyMap, VoxelMap only) |<\/p>\n
When multiple mods are detected with different punishments, the harshest applies: `ban` > `kick` > `disable` > `log`.<\/p>\n
### Finding translation keys for a mod<\/p>\n
Some mods need specific translation keys that can’t be auto-generated. To find them:<\/p>\n
1. Open the mod’s JAR file with any zip tool (7-Zip, WinRAR, or rename to `.zip`) `messages.yml`<\/p>\n All player-facing text is customizable. Supports MiniMessage formatting and these placeholders:<\/p>\n – `{player}` \u2014 player name “`yaml —<\/p>\n ## Commands<\/p>\n **All commands are aliased as `\/mg` or `\/modguard`.**<\/p>\n | Command | Description | —<\/p>\n ## Permissions<\/p>\n | Permission | Default | Description | —<\/p>\n ## Included default detections<\/p>\n – Wurst Client (ban) Edit, remove, or add to any of these in `config.yml`.<\/p>\n —<\/p>\n ## What players experience<\/p>\n ### Clean players ### Players with blocked mods ### Players with “disable”-punished mods —<\/p>\n ## Troubleshooting<\/p>\n ### A clean player got flagged ### A mod isn’t being detected ### “Scan timeout” appears in logs ### Sign placement failed ### Player has stuck blindness ### `\/mg reload` didn’t apply a change —<\/p>\n ## Limitations to know about<\/p>\n – Some mods can’t be detected. Pure texture-based X-ray mods and mods with no translation keys or plugin channels have no unique signature. No detection plugin can catch these without a client-side helper. —<\/p>\n ## Tips<\/p>\n – Test with an alt account before deploying. Join with various mods and watch the logs. **Thanks for the support!** This plugin allows you to blacklist mods from clients before they join your server to keep a fair and equal play experience.<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"_minecraft_slug":"modguard_mc","_minecraft_project_id":"XCi4EPjq","_minecraft_author":"waffleboiiiiii","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":5,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"modguard_mc.zip","_minecraft_size_bytes":44172,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-16T12:26:01.550093Z","_minecraft_date_created":"2026-04-28T20:32:03.538435Z","_minecraft_date_modified":"2026-04-16T10:25:30.673821Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/modguard_mc","_minecraft_icon_attachment_id":0,"_minecraft_imported_at":"2026-06-06T00:28:41+00:00","_minecraft_import_hash":"e6d51d35b8db545eeec21da989c5b0d2","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,89,126,127,128,129,123,92],"mod_loader":[130,132,133,134],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-104489","mod","type-mod","status-publish","hentry","mod_category-bukkit","mod_category-game-mechanics","mod_category-management","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_category-technology","mod_category-utility","mod_loader-bukkit","mod_loader-paper","mod_loader-purpur","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
\n2. Navigate to `assets\/
\n3. Copy the keys from that file into your config under `keys:`<\/p>\n
\n– `{mods}` \u2014 comma-separated detected mod names
\n– `{count}` \u2014 number of detected mods
\n– `{server}` \u2014 server name<\/p>\n
\nkick: “
\nban: “
\n“`<\/p>\n
\n|———|————-|
\n| `\/mg reload` | Reload config.yml and messages.yml |
\n| `\/mg list` | List all configured mods |
\n| `\/mg info
\n| `\/mg add
\n| `\/mg remove
\n| `\/mg check
\n| `\/mg scan
\n|————|———|————-|
\n| `modguard.admin` | op | Grants all permissions |
\n| `modguard.reload` | op | `\/mg reload` |
\n| `modguard.list` | op | `\/mg list` |
\n| `modguard.info` | op | `\/mg info` |
\n| `modguard.add` | op | `\/mg add` |
\n| `modguard.remove` | op | `\/mg remove` |
\n| `modguard.check` | op | `\/mg check` and `\/mg scan` |
\n| `modguard.notify` | false | Receive detection alerts |
\n| `modguard.bypass` | false | Skip ALL checks |
\n| `modguard.bypass.
\n– Meteor Client (ban)
\n– Advanced XRay (ban)
\n– Baritone (kick)
\n– Freecam \u2014 hashalite and Zergatul (kick)
\n– Xaero’s Minimap & World Map (disable \u2192 fair-play mode)
\n– JourneyMap (disable)
\n– VoxelMap (disable)<\/p>\n
\nBrief “Verifying your client…” screen during the normal “Loading terrain” phase, then gameplay as usual. Most players won’t notice any extra wait.<\/p>\n
\nDisconnected with the configured kick or ban message before they can load into the world.<\/p>\n
\nJoin normally. Their minimap’s cave mode and entity radar are disabled; their JourneyMap\/VoxelMap are restricted. They see a chat message explaining what was restricted.<\/p>\n
\nCheck the console logs for the `[DETECT]` line. If the detection looks wrong, report it with the full log output.<\/p>\n
\nMost often the translation keys in your config don’t match what the mod actually uses. Pull the real keys from the mod’s JAR (`assets\/
\nThe player’s client didn’t respond to the verification check. This usually means they have a protection mod installed or there’s severe network latency. Decide whether to treat this as suspicious or allow it based on your server’s policy.<\/p>\n
\nA protection plugin (WorldGuard, etc.) is blocking block placement at the player’s location. Whitelist ModGuard in your region protection plugin, or add a bypass region near your spawn.<\/p>\n
\nShouldn’t happen but if it does: `\/effect clear
\nThe `rescan-interval-ticks` setting requires a full server restart. Everything else reloads live.<\/p>\n
\n– Xaero’s World Map can still be opened with M even when “disable” is set \u2014 only cave mode and radar are restricted. This is a limitation of Xaero’s compliance protocol.
\n– Version mismatches through ViaVersion can occasionally affect detection accuracy. Most modern versions (1.20+) work fine.
\n– Detection \u2260 cheating. A player having Freecam installed doesn’t mean they used it. Consider using `log` punishment for ambiguous mods during initial rollout so you can see what your players run before deciding on stricter action.<\/p>\n
\n– Start with `log` punishment for new mod entries to see detection patterns before enabling `kick`\/`ban`.
\n– Watch the console \u2014 `[DETECT]` lines show exactly what was caught and why.
\n– Keep keys updated \u2014 mod authors occasionally rename translation keys between versions. Re-pull keys from the JAR if detection stops working for a previously-caught mod.<\/p>\n
\n_**Developed by waffleboiiiiii**_<\/p>\n","protected":false},"excerpt":{"rendered":"