ModGuard

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.

---

Requirements

• Paper 1.21 or later
• Java 21 or later
• Optional: ViaVersion for cross-version client support

---

Installation

1. Drop ModGuard.jar into your server's plugins/ folder
2. Restart the server
3. Edit plugins/ModGuard/config.yml and plugins/ModGuard/messages.yml
4. Run /mg reload to apply changes

---

Configuration

config.yml

settings:
  punishment: kick             # Default: kick, ban, log, disable
  log-detections: true         # Log to console
  notify-admins: true          # Alert players with modguard.notify
  scan-delay-ticks: 20
  rescan-interval-ticks: 1200
  bypass-uuids: []

detection:
  brand: true
  channels: true
  sign-scan: true

scan-protection:
  blackout: true               # Black screen during verification
  freeze-movement: true
  block-inputs: true
  prevent-damage: true
  prevent-falling: true

minimap-control:
  enabled: false               # Restrict minimaps for ALL players
  xaero-minimap: true
  xaero-worldmap: true
  journeymap: true
  voxelmap: true

Adding a blocked mod

Minimum required:

mods:
  cool-mod:
    name: "Cool Mod"
    punishment: kick

Full options:

mods:
  cool-mod:
    name: "Cool Mod"
    channels: ["cool-mod:", "cool"]       # Channel patterns (wildcards supported)
    brands: ["coolclient"]                # Client brand strings
    keys:                                 # Translation keys from the mod's lang file
      - "key.cool-mod.toggle"
      - "category.cool-mod"
    punishment: ban                       # kick / ban / log / disable

If you don't specify channels: or keys:, sensible defaults are auto-generated from the mod's ID.

Punishment types

Type	Behavior
kick	Disconnect with a kick message
ban	Add to the server banlist
log	Record the detection, take no action
disable	Restrict the mod's features (Xaero, JourneyMap, VoxelMap only)

When multiple mods are detected with different punishments, the harshest applies: ban > kick > disable > log.

Finding translation keys for a mod

Some mods need specific translation keys that can't be auto-generated. To find them:

1. Open the mod's JAR file with any zip tool (7-Zip, WinRAR, or rename to .zip)
2. Navigate to assets/<modid>/lang/en_us.json
3. Copy the keys from that file into your config under keys:

messages.yml

All player-facing text is customizable. Supports MiniMessage formatting and these placeholders:

• {player} — player name
• {mods} — comma-separated detected mod names
• {count} — number of detected mods
• {server} — server name

kick: "<red><b>ModGuard</b></red> <dark_gray>»</dark_gray> <white>Blocked: <yellow>{mods}</yellow></white>"
ban: "<red>You have been banned for using: <yellow>{mods}</yellow></red>"

---

Commands

All commands are aliased as /mg or /modguard.

Command	Description
/mg reload	Reload config.yml and messages.yml
/mg list	List all configured mods
/mg info <mod-id>	Details about a specific mod entry
/mg add <id> <name> [punishment]	Add a mod to the blocklist
/mg remove <id>	Remove a mod from the blocklist
/mg check <player>	Check a player
/mg scan <player>	Force a full scan on a player

---

Permissions

Permission	Default	Description
modguard.admin	op	Grants all permissions
modguard.reload	op	/mg reload
modguard.list	op	/mg list
modguard.info	op	/mg info
modguard.add	op	/mg add
modguard.remove	op	/mg remove
modguard.check	op	/mg check and /mg scan
modguard.notify	false	Receive detection alerts
modguard.bypass	false	Skip ALL checks
modguard.bypass.<modid>	false	Skip checks for one specific mod

---

Included default detections

• Wurst Client (ban)
• Meteor Client (ban)
• Advanced XRay (ban)
• Baritone (kick)
• Freecam — hashalite and Zergatul (kick)
• Xaero's Minimap & World Map (disable → fair-play mode)
• JourneyMap (disable)
• VoxelMap (disable)

Edit, remove, or add to any of these in config.yml.

---

What players experience

Clean players

Brief "Verifying your client..." screen during the normal "Loading terrain" phase, then gameplay as usual. Most players won't notice any extra wait.

Players with blocked mods

Disconnected with the configured kick or ban message before they can load into the world.

Players with "disable"-punished mods

Join 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.

---

Troubleshooting

A clean player got flagged

Check the console logs for the [DETECT] line. If the detection looks wrong, report it with the full log output.

A mod isn't being detected

Most 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/<modid>/lang/en_us.json) and paste them into the config under that mod's keys: list.

"Scan timeout" appears in logs

The 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.

Sign placement failed

A 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.

Player has stuck blindness

Shouldn't happen but if it does: /effect clear <player>.

/mg reload didn't apply a change

The rescan-interval-ticks setting requires a full server restart. Everything else reloads live.

---

Limitations to know about

• 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.
• Xaero's World Map can still be opened with M even when "disable" is set — only cave mode and radar are restricted. This is a limitation of Xaero's compliance protocol.
• Version mismatches through ViaVersion can occasionally affect detection accuracy. Most modern versions (1.20+) work fine.
• Detection ≠ 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.

---

Tips

• Test with an alt account before deploying. Join with various mods and watch the logs.
• Start with log punishment for new mod entries to see detection patterns before enabling kick/ban.
• Watch the console — [DETECT] lines show exactly what was caught and why.
• Keep keys updated — mod authors occasionally rename translation keys between versions. Re-pull keys from the JAR if detection stops working for a previously-caught mod.

Thanks for the support! Developed by waffleboiiiiii