BETA: v1.1.0-beta1

New beta release of the v1.1.0 brings new changes.

CHANGELOG v1.1.0-beta1

• Whitelist command itself now requires a root permission node betterwhitelist (defaults to op). Be sure to update your permission group for whitelist operator to include this root node.
• /wl list now sorts players in alphabetical order, and divides list into pages. Use /wl list p:# to list other pages (replace # with page number).
• /wl add and /wl remove now supports multiple players specification. Separate with spaces.
• Added support for custom kick message. Currently only manually configured from config.yml file (modify and run /wl reload to apply changes).
• Fixed a critical bug that was introduced due to Mojang changing their API. That bug made it impossible to add new players to the whitelist.

How to install this update

1. As usual, replace the old JAR file with the new one (move/upload BetterWhitelist-v1.1.0-beta1.jar into plugins/ directory and delete the old JAR file). That will replace your old version with this newest beta release.
2. Because plugin still doesn't support automatic config update, you'll have to update manually. Backup your current config and your language files, delete the config.yml file and delete the language files, and let the plugin create a new file in place. Then copy over your backup and replace the older configuration defaults with your values (make sure to leave all new entries). If you had a custom kick message in your language files, you can copy them from backup to the config.yml file and replace thus the default value of custom-kick-message option. To use the custom kick message though, you have to set custom-kick-message-enabled option to true. A command to set this option will be added later. Do not delete the whitelist.yml file, otherwise you'll have to fill your whitelist again.
3. After you perform these steps, restart the server to apply changes.

More features are planned in future beta releases. Watch this repository for notifications.

HOT BUGFIX RELEASE v1.0.1

Previous hot bugfix snapshot has been released. No changes have been made to this release since snapshot. Download below.

NEXT HOTFIXES WON'T BE RELEASED AS SNAPSHOTS

HOT BUGFIX BETA: v1.0.1-SNAPSHOT

Hot bugfix was issued, which covers slight inconsistency with kicking players that are not whitelisted. This prerelease addresses an issue where players can for a very brief moment join the whitelisted server before being kicked. That causes their in-game profile being created and join/leave message to appear for all players. That issue can clog the server file system with inactive player data and some other plugins can work with these data as well, which for example may bias your server stats. This prerelease will be in test for about a month and will be released in main channel and on SpigotMC.org as a proper version, unless a new bug is found. Download below.

RELEASE v1.0

First release is here! Changes to the release candidate in this release are as following:

• Removed GitHub Pages documentation (for now)
• Added version subcommand and autocomplete
• Tweaking existing language entries and autocomplete

Download new version from down below.

RELEASE CANDIDATE: v1.0-RC1

Skipped a beta phase straight to release candidate. I feel this plugin is more or less ready to be released, given its simplicity and how quickly it turned out to be implemented. Since the plugin is so simple, it doesn't have tons of features that need to be tested more thoroughly, and testing is more or less done. So I decided to make few minor changes and make a release candidate. If no bug reports or feature requests turn up, this release candidate becomes the first stable version that will be finally released on SpigotMC.org websites.

Changes

• While server is in online mode, whitelist now takes username change into account and when someone joins the server and isn't found on whitelist under his current name, plugin searches through all the entries for a matching online UUID, and once found, updates the entry (makes a new one with matching set of UUIDs and deletes the old one). Offline mode still works the same as before.

About release candidates

Release candidates are basically production ready releases. The last release candidate practically becomes the final release of the proposed version. Release candidates are made to ensure that the final product is bug free as much as possible. They're still considered a testing release, they're just made with production ready release in mind, not for development purposes like alpha and beta releases.

Download and install

Download the BetterWhitelist-v1.0-RC1.jar file from down below to use it. Shut down the server, make sure to delete the old release and replace it with this new, and restart the server to enable the new version. For usage refer to readme file.

ALPHA: v0.1.1-SNAPSHOT [HOT bug fix]

Hot bug fix

This pre-release fixes two major bugs that were found in production:

• Offline UUID generator was given null
  when specified player wasn't found in Mojang's
  database (offline mode servers)
• When reloading config, only the basic configuration
  was reloaded, everything else was ignored

Download this new hotfix and report new bugs if you find them.
For usage refer to readme file.

ALPHA: v0.1-SNAPSHOT

First ALPHA version test release: v0.1-SNAPSHOT is here! Keep in mind this plugin is still in active alpha testing phase. If you encounter a bug, please report it so it can be resolved. I consider this plugin done if no bug is found in months so plugin development enters final stage of updates for new Minecraft versions when necessary.

Features

This is just whitelist so there's only one feature that can be expected, and that is (surprise surprise) whitelist, but instead of relying on Minecraft profile existing when specified player isn't online yet, this plugin generates set of two different unique user IDs of specified player.

As you might know, server behaves differently when it's an online mode or offline mode. Online mode is the recommended one, which basically enables user authentication at Mojang servers that verify if the player connecting is a legitimate player connecting to the server (in other words user with a paid copy of the game currently logged in to the game). In this case, the UUID of the player is reported from Mojang servers and stays the same even if the player changes their nickname, it's randomly generated at the time of account creation. If the server is in an offline mode, server skips authorization of players at Mojang and instead generates a fake UUID (also called "offline" UUID) from the player's nickname (which is also why the player loses all their items and other data from inventory if they change their in-game nick - the server treats them as completely new players), and this UUID is instead used. Offline mode is often used for testing purposes only, or when you're using a server with no internet access. Some servers prefer to run in offline mode to allow players with illegal copy of the game join, which isn't recommended, but there are already plugins that add a simpler authentication method for cracked servers. This plugins is aimed to solve issue with vanilla whitelist not working properly when server is running in an offline insecure mode to allow cracked players to join.

Vanilla whitelist however doesn't apply to this state and doesn't generate fake UUID for a given player. If the player is online, addition to the whitelist takes the player nick and current UUID and adds it to the whitelist. If the player isn't online, vanilla whitelist instead looks the player up in Mojang database and takes their IGN and UUID from there, which therefore creates an issue for offline mode servers that suddenly cannot find player joining in the whitelist despite being present in whitelist - their UUIDs simply do not match.

This plugin solves this issue by taking into account which mode the server is running in. It replaces the vanilla whitelist command, which can be accessed using /minecraft:whitelist command. It is recommended to use this plugin alongside with an authentication plugin that adds at least some sort of protection against game profile theft if your server runs in an offline mode. Even if the player is whitelisted, unless their profile is somehow protected, anyone can join with their IGN and play, which isn't good.

If you are running an online mode server only, it is recommended to use vanilla whitelist instead of plugin like this. Vanilla whitelist on an online mode server works just how you would expect the whitelist to work, and there's no need to add another plugin that does the same thing. You might want to use permissions system to give a player whitelist management permissions, which means they are in charge of adding and removing players from whitelist (and of course seeing the whitelist content). I'm not sure if vanilla whitelist can be used in such way it allows partial permissions, which is why you may want to use a plugin for this. If you're using whitelist on mostly an offline mode server, but you're forced to switch it to online mode temporarily, this plugin may come to aid for you as it will allow you to manage whitelisted players while retaining their ability to join the server. You may also want to customize the kick message in case the player isn't whitelisted, which is also why you might want to use the plugin.

Usage:

Use /whitelist <subcommand> [argument] or /wl <subcommand> [argument] with following subcommands:

• status - Checks the status of whitelist (enabled or disabled), requires betterwhitelist.admin permission to run
• on - Turns the whitelist on, requires betterwhitelist.admin permission to run
• off - Turns the whitelist off, requires betterwhitelist.admin permission to run
• list - Lists all whitelisted players, requires betterwhitelist.list permission to run
• add <playername> - Adds specified player to the whitelist, requires betterwhitelist.add permission to run
• remove <playername> - Removes specified player from the whitelist, requires betterwhitelist.remove permission to run
• import - Imports players from vanilla whitelist to be used with this plugin, requires betterwhitelist.admin permission to run
• lang <language code> - Checks or changes language of the plugin messages, requires betterwhitelist.admin permission to run
• reload - Reloads the whitelist and configuration from the plugin files (used mainly if you do manual edits - not recommended), requires betterwhitelist.admin permission to run

Permissions

If you're using permissions plugin, this is a list of available permissions you'll need to use. All permissions default to server operators (op).

• betterwhitelist.* - This is a wildcard permission, which is equivalent for betterwhitelist.admin. It's recommended to use the named permission.
• betterwhitelist.admin - This is a super permission that allows you to access all subcommands, including add, remove and list.
• betterwhitelist.add - This permission allows you to add players into whitelist. Does not grant you removal and list permissions.
• betterwhitelist.remove - This permission allows you to remove players from whitelist. Does not grant you add and list permissions.
• betterwhitelist.list - This permission allows you to list whitelisted players. Does not grant you add and remove permissions.

It is recommended to assign add, remove and list permissions simultaneously for player that is in charge of managing whitelist, but cannot be trusted with full access to all the commands. Each individual permission only grants an access to the single command it is assigned to. If you want some player to be able just list the whitelisted players, assign only list permission to them.

Installation

Drop the downloaded JAR file into plugins folder of your Spigot server (Minecraft 1.18+ recommended) and restart your server. Plugin generates a new folder inside that contains all the configuration files necessary for the plugin to work properly. It is recommended to avoid messing with these files unless you know what you're doing.

You can add your own translations for the plugin if you like, all language files are annotated with comments explaining what variables can be used and what color and format codes can be used. Do not change message identificators as this will render the plugin not working properly. If you want to contribute your translation for the plugin, you can fork this repository and send a pull request from resources/languages directory of forked repository with new language files. Make sure that the file contains your nick (preferably Minecraft IGN, doesn't have to be a registered account).