ModRoster

ModRoster

ModRoster is a Forge 1.20.1 mod that checks each client’s mod list during the login phase and rejects clients that don’t match the roster the server allows. Players are refused before they enter the world, so no join/leave messages appear. Discord bridges such as SDLink also see nothing.

Install the same jar on the server and on every client.

Features

• Required / optional roster: define which mods every player must have and which they may have. Anything else is rejected.
• Version and hash checks: each entry can pin versions and jar SHA-256 hashes. An entry with no versions/hashes acts as a wildcard.
• Audit mode: log what would be rejected without kicking anyone. Good for rolling out to an existing server.
• Build the roster from a real client: /modroster copy player <name> required, review the preview, then /modroster confirm. A client’s own report can be copied straight into the roster.
• Backups and restore: roster.json is backed up on every change, and /modroster restore brings a previous one back.
• Audit log: logs/modroster-audit.log records time, result, player name, UUID, and what was missing or violated.
• Cross-check with the Forge mod list (on by default), so a client can’t simply omit mods from its own report.
• Timeout: clients that never send their report are disconnected (timeoutSeconds, default 10).
• Hash results are cached on the client, so only the first launch is slow.
• English and Japanese (ja_jp) language files included.

Quick start

1. Put the jar in mods on the server and on all clients.
2. Start the server once. config/modroster-common.toml and config/modroster/roster.json are created.
3. Set enabled = true and auditMode = true, then run /modroster reload.
4. Join with a correctly configured client, then run /modroster copy player <name> required followed by /modroster confirm.
5. Move optional mods with /modroster move <modid> optional.
6. When AUDIT entries stop appearing in logs/modroster-audit.log, set auditMode = false and run /modroster reload.

Commands

Limitations

• This is not anti-cheat. The mod list is reported by the client, so a modified client can fake it. ModRoster prevents accidental mismatches in mod setups.
• Clients without ModRoster are rejected by Forge’s channel check, even with enabled=false.
• The hash of minecraft and forge itself is not reliable, so these stay in alwaysAllow by default.
• On a very large modpack, the first-launch hash calculation may exceed timeoutSeconds (max 25).
• The list of rejected reports shown by the commands is kept in memory only and is cleared on server restart.

Links

• Source / issues: https://github.com/okonomiyak/ModRoster
• License: MIT