PendingWhitelist

PendingWhitelist keeps track of players who tried to join while your server whitelist was enabled. Instead of losing those attempts in the console, staff can review them later from an in-game interface and manage the whitelist.

How it works

1. A player tries to join while the whitelist is enabled.
2. PendingWhitelist records the rejected join attempt.
3. Staff can review the player from /wl or the paginated chat list.
4. The player can be added to the whitelist directly from the GUI or with /wl add <player>.

Features

• Records rejected join attempts with player identity, attempt count, and timestamps.
• In-game dashboard for whitelist and pending-player management.
• Separate views for pending and whitelisted players.
• Pending, online, offline, Java, and Bedrock players are organised automatically.
• Shift-click support for adding or removing all players on the current page.
• Clickable join notifications for staff with pendingwhitelist.admin.
• Configurable notification cooldown and automatic cleanup of old pending requests.
• Background skin loading with local caching.
• Floodgate support for Bedrock players.
• Optional SkinsRestorer integration for offline-mode skin lookups.
• /wl version support for checking the latest stable Modrinth release.

Requirements

• Paper or Purpur using the Paper API 1.20.1 or newer.
• Java 21 or newer.
• Floodgate is optional.
• SkinsRestorer is optional.

Use the Java version required by your server release when it is newer than the minimum listed above.

Installation

1. Stop the server.
2. Place PendingWhitelist-<version>.jar in the server's plugins folder.
3. Start the server.
4. Adjust plugins/PendingWhitelist/config.yml when needed.

No separate bStats installation is required; bStats is bundled with the plugin.

Commands

Command	Description
/wl	Open the admin dashboard.
/wl add	Open the Add Players GUI.
/wl add <player>	Add a player to the whitelist.
/wl list [page]	List whitelisted players in chat.
/wl remove	Open the Whitelisted Players GUI.
/wl remove <player...>	Remove players from the whitelist.
/wl pl [page]	List pending players in chat.
/wl rpl	Open the Add Players GUI.
/wl rpl <player...>	Remove players from pending storage.
/wl on	Enable the server whitelist.
/wl off	Disable the server whitelist.
/wl reload	Reload PendingWhitelist configuration.
/wl version	Check for a newer stable release on Modrinth.

All administration commands require pendingwhitelist.admin.

GUI

Add Players

Pending requests are shown first, followed by online players and then previously joined offline players. Bedrock players are shown before Java players within the pending and online groups.

Left-click adds the selected player. Shift-click adds every player on the current page. Navigation controls are only shown when another page is available.

Whitelisted Players

The whitelist GUI lists the current whitelist and supports direct removal. Left-click removes the selected player; shift-click removes every player on the current page.

Join notifications

When a non-whitelisted player is rejected, staff with pendingwhitelist.admin can receive a notification with clickable actions. Repeated notifications are limited by the configured cooldown.

Configuration

The main settings cover debug logging, chat page size, join-attempt notifications, notification cooldown, and automatic pending-request cleanup.

See the configuration guide for the complete list of options.

Data and privacy

PendingWhitelist stores rejected join attempts locally in plugins/PendingWhitelist/pending.json. Paper continues to manage the normal whitelist.json file.

PendingWhitelist also reports anonymous usage statistics through bStats. You can view the current statistics on the PendingWhitelist bStats page. bStats can be disabled through its global configuration.

Support

For bug reports and feature requests, use the GitHub issue tracker.

For development information and the full source code, visit the GitHub repository.