mWL Updated - UUID based whitelisting

!Divider

Overview

mWL is a whitelist plugin for Paper, Spigot, and Bukkit servers. It gives you full control over who can join, with temporary whitelist entries, permission-based bypass, and a choice of MongoDB or JSON storage. It runs on anything from 1.18.x up to Paper 26.2.

Note: mWL requires your server to run in online-mode (premium/licensed accounts). Offline/cracked UUIDs are not supported.

Useful for private servers, whitelisted communities, or any server that needs more control than vanilla's built-in whitelist.

!Divider

Features

Also lightweight, with async database operations so lookups don't freeze the server, and works with LuckPerms and other permission plugins out of the box.

!Divider

Configuration

Some of what you can configure:

• Whitelist on/off toggle, via command or config
• Temporary whitelist with flexible time syntax (e.g. 1d12h30m)
• Permission bypass, assignable via any permission plugin
• Periodic player check with configurable interval
• Expiry notify threshold
• MongoDB connection settings
• bStats metrics toggle (enableMetrics: true/false)

whitelist:
  status: false # Whitelist enabled
  remove-on-expired: false # Remove player from database on join if their time has expired
  kick-on-remove: false # Kick player from server when removed from the whitelist via command
  bypass:
    permission:
      enabled: true # Enable bypass via permission
      permission: mwl.whitelist.bypass
  player-check: # Periodically re-checks online players and kicks them if no longer whitelisted or expired
    enabled: false
    delay: 60000 # Milliseconds between checks
  expired-notify: # Warns a player once their remaining time drops below expired-notify.time
    enabled: true
    time: 86400000 # Milliseconds before expiry
database:
  type: JSON # JSON or MONGO

!Divider

Commands & Permissions

Commands

Permissions

• mwl.command.add: add players
• mwl.command.remove: remove players
• mwl.command.addtemp: add temporary players
• mwl.command.settemp: set expiry time
• mwl.command.extendtemp: extend expiry time
• mwl.command.check: check whitelist status
• mwl.command.list: list whitelisted players
• mwl.command.toggle: toggle whitelist
• mwl.command.info: view plugin info
• mwl.command.reload: reload config
• mwl.command.help: view help
• mwl.whitelist.bypass: bypass whitelist check entirely

!Divider

Database Support

mWL supports two storage backends:

• JSON (default): zero setup, stores data locally in whitelist.json
• MongoDB: for larger servers or shared data setups; configure the connection URL in config.yml

You can switch between backends at any time by changing database.type in the config and restarting.

!Divider

Addon API

depend: [mWL]

RegisteredServiceProvider<WhitelistAPI> provider =
        Bukkit.getServicesManager().getRegistration(WhitelistAPI.class);

if (provider == null) return; // mWL not installed

WhitelistAPI whitelistApi = provider.getProvider();

WhitelistAPI whitelistApi = MWhitelist.getAPI();

UUID uuid = player.getUniqueId();

whitelistApi.addPlayer(uuid, player.getName());
whitelistApi.addPlayerTemp(uuid, player.getName(), Duration.ofDays(7).toMillis());
whitelistApi.isWhitelisted(uuid);
whitelistApi.removePlayer(uuid);

whitelistApi.setPlayerTemp(uuid, Duration.ofHours(12).toMillis());   // overwrite expiry
whitelistApi.extendPlayerTemp(uuid, Duration.ofHours(12).toMillis()); // add to current expiry

whitelistApi.addPlayer("Notch").thenAccept(success -> { /* ... */ });

Optional<WhitelistEntry> entry = whitelistApi.getEntry(uuid);
entry.ifPresent(e -> {
    e.getUuid();
    e.getName();
    e.getAddedAt();     // epoch millis
    e.getExpiresAt();   // epoch millis, only meaningful if !isPermanent()
    e.isPermanent();
});

List<WhitelistEntry> all = whitelistApi.getAll();
int size = whitelistApi.getWhitelistSize();

whitelistApi.isWhitelistEnabled();
whitelistApi.setWhitelistEnabled(true);

@EventHandler
public void onAdd(PlayerWhitelistAddEvent event) {
    getLogger().info(event.getName() + " was whitelisted (temp: " + event.isTemp() + ")");
}

!Divider

Requirements

• Minecraft: 1.18.x+ (compatible with 1.18.x through 1.21.x and Paper 26.2)
• Server: Paper, Spigot, Bukkit, or Paper forks (Purpur, etc.)
• Java: 17+ (Java 25+ required for Paper 26.x)

Credits

Original Plugin: mWL by TRUEC0DER

This is an updated fork, coordinated with and known to the original author, since the original plugin is now EOL (end of life) and no longer maintained. This fork adds bug fixes, broader version compatibility (1.18.x through 26.2), and additional features for modern Paper, Spigot, and Bukkit servers.

License

This project is licensed under the MIT License. See the LICENSE file for details.