ModGuard
适用于 Paper/Spigot Minecraft 服务器的服务端模组与作弊客户端检测工具。检测未授权的客户端修改,并根据你的规则踢出、封禁、记录或限制它们。无需安装任何客户端辅助模组。
要求
- Paper 1.21 或更高版本
- Java 21 或更高版本
- 可选:ViaVersion 以支持跨版本客户端
安装
- 将
ModGuard.jar 放入服务器的 plugins/ 文件夹中
- 重启服务器
- 编辑
plugins/ModGuard/config.yml 和 plugins/ModGuard/messages.yml
- 运行
/mg reload 应用更改
配置
config.yml
settings:
punishment: kick # 默认值:kick, ban, log, disable
log-detections: true # 记录到控制台
notify-admins: true # 向拥有 modguard.notify 权限的玩家发送警报
scan-delay-ticks: 20
rescan-interval-ticks: 1200
bypass-uuids: []
detection:
brand: true
channels: true
sign-scan: true
scan-protection:
blackout: true # 验证期间黑屏
freeze-movement: true
block-inputs: true
prevent-damage: true
prevent-falling: true
minimap-control:
enabled: false # 限制所有玩家的迷你地图功能
xaero-minimap: true
xaero-worldmap: true
journeymap: true
voxelmap: true
添加被禁止的模组
最低要求:
mods:
cool-mod:
name: "Cool Mod"
punishment: kick
完整选项:
mods:
cool-mod:
name: "Cool Mod"
channels: ["cool-mod:", "cool"] # 频道模式(支持通配符)
brands: ["coolclient"] # 客户端品牌字符串
keys: # 来自模组语言文件的翻译键
- "key.cool-mod.toggle"
- "category.cool-mod"
punishment: ban # kick / ban / log / disable
如果你没有指定 channels: 或 keys:,系统会根据模组的 ID 自动生成合理的默认值。
惩罚类型
| 类型 |
行为 |
kick |
断开连接并显示踢出消息 |
ban |
添加到服务器封禁列表 |
log |
记录检测结果,不采取其他行动 |
disable |
限制该模组的功能(仅适用于 Xaero、JourneyMap、VoxelMap) |
当检测到多个具有不同惩罚措施的模组时,最严厉的惩罚生效:ban > kick > disable > log。
查找模组的翻译键
某些模组需要特定的翻译键,无法自动生成。要找到它们:
- 使用任意压缩工具(7-Zip、WinRAR 或重命名为
.zip)打开模组的 JAR 文件
- 导航至
assets/<modid>/lang/en_us.json
- 从该文件中复制键名,并将其粘贴到你配置中的
keys: 下
messages.yml
所有面向玩家显示的文本均可自定义。支持 MiniMessage 格式以及以下占位符:
{player} — 玩家名称
{mods} — 逗号分隔的检测到的模组名称
{count} — 检测到的模组数量
{server} — 服务器名称
kick: "<red><b>ModGuard</b></red> <dark_gray>»</dark_gray> <white>已阻止:<yellow>{mods}</yellow></white>"
ban: "<red>由于使用了以下模组,你已被封禁:<yellow>{mods}</yellow></red>"
命令
所有命令均支持别名 /mg 或 /modguard。
| 命令 |
描述 |
/mg reload |
重新加载 config.yml 和 messages.yml |
/mg list |
列出所有已配置的模组 |
/mg info <mod-id> |
查看特定模组条目的详细信息 |
/mg add <id> <name> [punishment] |
将模组添加到黑名单 |
/mg remove <id> |
从黑名单中移除模组 |
/mg check <player> |
检查某位玩家 |
/mg scan <player> |
强制对某位玩家进行全盘扫描 |
权限
| 权限 |
默认值 |
描述 |
modguard.admin |
op |
授予所有权限 |
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 和 /mg scan |
modguard.notify |
false |
接收检测警报 |
modguard.bypass |
false |
跳过所有检查 |
modguard.bypass.<modid> |
false |
跳过针对特定模组的检查 |
包含的默认检测项
- Wurst Client (ban)
- Meteor Client (ban)
- Advanced XRay (ban)
- Baritone (kick)
- Freecam — hashalite 和 Zergatul (kick)
- Xaero's Minimap & World Map (禁用 → 公平竞技模式)
- JourneyMap (禁用)
- VoxelMap (禁用)
你可以在 config.yml 中编辑、移除或添加这些检测项。
玩家体验说明
正常玩家
在正常的“加载地形”阶段会短暂出现“正在验证你的客户端...”界面,随后正常游戏。大多数玩家不会察觉到额外的等待时间。
携带被禁模组的玩家
在进入世界之前,会被断开连接并显示配置好的踢出或封禁消息。
携带“禁用”惩罚模组的玩家
可以正常加入游戏。他们的迷你地图的地底模式和实体雷达功能被禁用;JourneyMap/VoxelMap 受到限制。他们会收到一条聊天消息,解释哪些功能受到了限制。
故障排除
正常玩家被误标记
请检查控制台中是否包含 [DETECT] 行日志。如果检测结果看起来不正确,请提供完整的日志输出进行报告。
某个模组未被检测到
通常是因为配置文件中的翻译键与该模组实际使用的键不匹配。从模组的 JAR 文件中提取真实的键(位于 assets/<modid>/lang/en_us.json),并将它们粘贴到该模组配置下的 keys: 列表中。
日志中出现“Scan timeout”(扫描超时)
玩家的客户端未能响应验证检查。这通常意味着他们安装了防护类模组,或者存在严重的网络延迟。根据你的服务器策略,决定将其视为可疑行为还是予以放行。
告示牌放置失败
一个保护类插件(如 WorldGuard 等)正在阻止玩家位置处的方块放置。在你的区域保护插件中将 ModGuard 加入白名单,或在出生点附近添加一个绕过区域。
玩家卡住失明
正常情况下不应出现此问题,但如果发生了:/effect clear <玩家>。
/mg reload 未应用更改
rescan-interval-ticks 设置需要完整重启服务器。其他所有内容均可实时重载。
需要注意的限制
- 某些模组可能无法被检测。纯基于纹理的 X 射线模组以及没有翻译键或插件信道的模组没有唯一的特征码,没有客户端辅助程序的检测插件无法捕获这些模组。
- 即使设置为“禁用”,仍可使用 M 键打开 Xaero's World Map —— 仅限制洞穴模式和雷达功能。这是 Xaero's 合规协议的局限性。
- 通过 ViaVersion 导致的版本不匹配偶尔会影响检测准确性。大多数现代版本(1.20+)运行良好。
- 检测 ≠ 作弊。玩家安装了 Freecam 并不意味着他们使用了它。在初期部署阶段,建议对存在歧义的模组使用
log(记录日志)作为处罚措施,以便你在决定采取更严格的行动之前了解玩家实际运行的模组。
提示
- 在部署前使用备用账号进行测试。加入各种模组并观察日志。
- 对新加入的模组条目先采用
log(记录)惩罚,以便在启用 kick(踢出)/ ban(封禁)之前了解检测模式。
- 关注控制台 ——
[DETECT] 行会清晰显示具体捕获到了什么以及原因。
- 保持密钥更新 —— 模组作者偶尔会在不同版本间重命名翻译键。如果之前能成功检测的模组突然失效,请从 JAR 文件中重新提取密钥。
感谢您的支持!
由 waffleboiiiiii 开发
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
- Drop
ModGuard.jar into your server's plugins/ folder
- Restart the server
- Edit
plugins/ModGuard/config.yml and plugins/ModGuard/messages.yml
- 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:
- Open the mod's JAR file with any zip tool (7-Zip, WinRAR, or rename to
.zip)
- Navigate to
assets/<modid>/lang/en_us.json
- 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
评论 0
登录后参与评分
还没有评论,来抢沙发吧