WhitelistGate is a server-side-only Forge mod that provides an independent, nickname-based whitelist. It is designed to work in both online and offline mode and never reads or modifies Minecraft's vanilla whitelist.json.
- Minecraft 1.20.1
- Forge 47.2.0 or newer in the Forge 47.x line
- Java 17
Build with gradlew build, then copy the JAR from build/libs into the dedicated server's mods directory. Do not install it on player clients: vanilla clients and Forge clients without WhitelistGate can connect, and the mod performs no custom network handshake.
All commands require permission level 3 and can be run by operators or from the dedicated server console:
/whitelistgate enable
/whitelistgate disable
/whitelistgate add <nickname>
/whitelistgate remove <nickname>
/whitelistgate list
/whitelistgate reload
Enabling does not kick connected players. Disabling immediately stops WhitelistGate from restricting new connections.
The file is created automatically at config/whitelistgate/whitelist.json:
{
"enabled": false,
"players": []
}Nicknames must match [A-Za-z0-9_]{3,16}. Admission requires an exact, case-sensitive match with the spelling stored in JSON: for example, WaterFlane does not allow waterflane. Duplicate detection and removal remain case-insensitive so conflicting case variants cannot be stored. Changes made by commands are saved immediately. Edit the file manually only while taking care to keep valid JSON, then run /whitelistgate reload.
On an offline-mode server, a player can choose another player's nickname. A nickname whitelist controls which names may connect; it does not authenticate a person or prove ownership of a Minecraft nickname.
Import the root build.gradle as a Gradle project in IntelliJ IDEA and use the generated Forge run configurations. See the testing guide in the project handoff for the dedicated-server launch steps.
Licensed under Apache License 2.0.