OrangeWhitelist

By default, name checks run during asynchronous pre-login. With permission bypass enabled, the permission decision moves to the player login event where available. A join safety check removes players who still do not qualify; servers without the login event use that fallback.

Enabling the whitelist and reloading its files applies the selected access rules to players already online. Removing a name also removes its connected player when whitelist enforcement is enabled and the player has no valid bypass.

The list is based on names, not authenticated identity. Accepted names contain letters, numbers and underscores, optionally preceded by up to three characters from the supported prefix set. The entire name must be at most 16 characters; names with spaces are not accepted.

Supported prefix characters: . * ! ~ # $ % & + = ? @ ^ -
Examples: Steve, Player_01, .Steve

Internal PLUGIN bans are keyed by the actual player UUID in Bans.yml and remain active when the whitelist is disabled. After /owl add <player> saves a new list entry, it lifts matching internal bans. An already-listed name is reported without a new add operation. Existing internal bans are checked before bypass permission.

The optional LiteBans hook uses litebans:ban <name> <reason> from the console. If LiteBans is unavailable, internal bans are used instead. Adding a player does not automatically remove LiteBans or vanilla Minecraft bans; use those systems’ own pardon or unban tools.

OrangeWhitelist maintains its own list. If the server’s vanilla whitelist is also enabled, players must satisfy that list as well.

Screenshot from an earlier build. The current refusal message is fully configurable.

/whitelist enable

Enable the whitelist and apply its rules to online Minecraft players.

/whitelist disable

Disable whitelist enforcement; existing bans remain.

/whitelist add player:<name>

Add a player name; the required option is named player. It uses the same add operation as the Minecraft command.

/whitelist remove player:<name>

Remove a player name, respecting AntiRemove for protected online players. The required option is named player.

/whitelist list

Show the count and player names in a private reply. Long lists are shortened to fit the reply.

These commands work inside Discord servers, not direct messages. The required add/remove option is named player. There is no Discord reload command.

Whitelist list replies and permission-denied replies are private. Authorized change commands reply in the channel. Player names are escaped and replies do not generate Discord mentions.

1. Create your bot application in the Discord Developer Portal. Invite it to your Discord server with the bot and applications.commands scopes. No privileged intents are required by this client.

2. Copy its token into Discord-Bot.Token in your private Settings.yml and set Discord-Bot.Enabled: true.

3. Turn on Discord developer mode, copy the staff role IDs and enter them as quoted values under Discord-Bot.Authorized-Roles.

4. Choose the bot language, presence status and activity. Run /owl reload, then use /whitelist inside your Discord server.

Discord-Bot:
  Enabled: true
  Token: "YOUR_DISCORD_BOT_TOKEN_HERE"
  Language: English
  Status: "online"
  Activity-Type: 0
  Activity-Name: "Minecraft"
  Authorized-Roles:
    - "123456789012345678"

The token and role ID above are examples. Use your own values and keep the token private. No manually configured Application-ID is needed.

Minecraft permission nodes do not authorize Discord users. A Discord member needs a configured role or must be the application owner or an accepted member of its owning team. Discord server ownership or an administrator role alone does not grant access.

With Authorized-Roles: [], only the application owner/team is eligible. The default command visibility may require Manage Server, but visibility itself does not grant authorization.

Whitelist operation replies use your Messages settings as plain text, without Minecraft colors or the command prefix. The Language setting controls the bot’s own replies and slash descriptions.

If credentials or a fatal Discord gateway error stop the bot, correct the configuration and run /owl reload to retry. Other interrupted sessions reconnect automatically.

Main command: /orangewhitelist. Aliases: /owl, /orangewl, /orangewhl, /orangew, /dwl and /dragonwhl. All six operations are available to players with permission and to the console.

/owl enable

Default permission: orangewhitelist.set OR orangewhitelist.admin Enable the whitelist, save the setting and apply its access rules to players already online. Unlisted players without an enabled bypass are removed using the selected KICK or BAN mode.

/owl disable

Default permission: orangewhitelist.set OR orangewhitelist.admin Disable whitelist enforcement and save the setting. Existing OrangeWhitelist internal bans and LiteBans bans are not removed.

/owl add <player>

Default permission: orangewhitelist.manage OR orangewhitelist.admin Validate and add a player name. After a new entry is saved, matching internal PLUGIN bans are lifted. This does not pardon vanilla Minecraft or LiteBans bans. An already-listed name is reported without changing its records.

/owl remove <player>

Default permission: orangewhitelist.manage OR orangewhitelist.admin Remove an existing name. AntiRemove can reject removal of a protected online player. When the whitelist is enabled, an online player who no longer qualifies is removed using the selected mode.

/owl list

Default permission: orangewhitelist.manage OR orangewhitelist.admin Show the whitelist count and player names, or the configured empty-list message.

/owl reload

Default permission: orangewhitelist.reload OR orangewhitelist.admin Reload Settings.yml, Whitelist.yml and Bans.yml, refresh the Discord bot and apply access rules to online players. Files reload independently: an unreadable file retains its previous loaded values while other valid files may apply.

Missing or unknown arguments show usage. Tab completion suggests allowed subcommands. Add suggestions include recently refused players and online players missing from the list; remove suggestions use existing list entries.

orangewhitelist.admin — Operator by default. Allows all six Minecraft commands and update notices. Its declared children are set, manage and reload; it does not grant bypass or anti-remove. Configuration key: Permissions.ALL

orangewhitelist.set — Operator by default. Allows /owl enable and /owl disable. The configured admin node also permits these commands. Configuration key: Permissions.Enable-Disable

orangewhitelist.manage — Operator by default. Allows /owl add, /owl remove and /owl list. The configured admin node also permits these commands. Configuration key: Permissions.Add-Remove

orangewhitelist.reload — Operator by default. Allows /owl reload. The configured admin node also permits this command. Configuration key: Permissions.Reload

orangewhitelist.bypass — Not granted by default, including to operators. Allows joining without being listed only when Enable-Permission-Bypass is true. Does not override an existing internal ban. Configuration key: Bypass-Permission.Permission

orangewhitelist.antiremove — Not granted by default, including to operators. Prevents removal of an online player with this node only when Enable-AntiRemove is true. Offline entries are not protected. Configuration key: AntiRemove.Permission

All six permission names are configurable. If you rename them, grant the new names through your permission manager. Declared operator grants and child relationships apply to the default names. Blank permission names fall back to their defaults.

Bypass and AntiRemove require their own enabled switches. Operators and holders of the admin permission do not automatically receive these two exemptions. Discord authorization uses role IDs independently.

Merge the following sections into the generated Settings.yml; keep its generated version fields and Messages section. The example keeps Discord, bypass and AntiRemove disabled and uses KICK mode.

# Merge into Settings.yml; retain generated version fields and Messages.
Plugin-Config:
  Enabled-Whitelist: true
  Mode: KICK
  Update-Checker: true

Kick-Ban-Hooks:
  Hook: PLUGIN
  Ban-Message: "<gray>You are not on this server's whitelist.</gray>"

Permissions:
  Enable-Disable: "orangewhitelist.set"
  Add-Remove: "orangewhitelist.manage"
  Reload: "orangewhitelist.reload"
  ALL: "orangewhitelist.admin"

Bypass-Permission:
  Enable-Permission-Bypass: false
  Permission: "orangewhitelist.bypass"

AntiRemove:
  Enable-AntiRemove: false
  Permission: "orangewhitelist.antiremove"

Discord-Bot:
  Enabled: false
  Token: "YOUR_DISCORD_BOT_TOKEN_HERE"
  Language: English
  Status: "online"
  Activity-Type: 0
  Activity-Name: "Minecraft"
  Authorized-Roles: []

• Plugin-Version / Config-Version. Managed version fields. Leave their generated values unchanged. Supported settings are kept and changed configuration files receive an old-configs/ backup.

• Plugin-Config.Enabled-Whitelist. Default true. A fresh install starts with an empty whitelist. Add your own name from the console before connecting, or deliberately disable enforcement while you prepare the list.

• Plugin-Config.Mode. KICK refuses unlisted players while enabled. BAN refuses them and records a ban using the selected hook. Invalid values fall back to KICK with a console warning.

• Plugin-Config.Update-Checker. Default true. Checks Spigot for updates and notifies the console and admins; it does not install updates.

• Kick-Ban-Hooks.Hook. PLUGIN uses OrangeWhitelist’s UUID-keyed Bans.yml. LiteBans dispatches litebans:ban when that plugin is available. If unavailable, the plugin falls back to its own list and logs the fallback.

• Kick-Ban-Hooks.Ban-Message. Reason used for BAN mode and subsequent internal-ban refusals. LiteBans receives a plain-text reason. The initial whitelist refusal uses Messages.Kick-Message.

• Permissions.Enable-Disable. Permission for enabling and disabling the whitelist. Default orangewhitelist.set.

• Permissions.Add-Remove. Permission for add, remove and list. Default orangewhitelist.manage.

• Permissions.Reload. Permission for reloading all three local files. Default orangewhitelist.reload.

• Permissions.ALL. Administrative command permission and update notices. Default orangewhitelist.admin; it does not imply bypass or anti-remove.

• Bypass-Permission.Enable-Permission-Bypass. Default false. When true, access can be granted using the configured permission rather than list membership. Permission checking uses the login event where available, with a join safety check as fallback.

• Bypass-Permission.Permission. Default orangewhitelist.bypass. Grant only to players who should join without being listed; an existing internal ban is still checked earlier.

• AntiRemove.Enable-AntiRemove. Default false. When true, protected online players cannot be removed from the plugin’s list. This is not protection for offline names.

• AntiRemove.Permission. Default orangewhitelist.antiremove. Effective only for an online target while AntiRemove is enabled.

• Discord-Bot.Enabled. Default false. Turns the integrated Discord bot on or off. Reload after changing the setting.

• Discord-Bot.Token. Your bot token from the Discord Developer Portal. Keep it private. The example is a placeholder, not a working credential. No Application-ID setting is needed.

• Discord-Bot.Language. English, Español, Français or 中文. Language aliases en, es, fr and zh are accepted. Unknown languages fall back to English. Localizes command descriptions and bot feedback; whitelist operation replies use Messages.

• Discord-Bot.Status. online, idle, dnd or invisible. Invalid values fall back to online.

• Discord-Bot.Activity-Type. 0 Playing, 1 Streaming, 2 Listening, 3 Watching, 4 custom text, 5 Competing. Values are clamped to 0–5. No stream URL setting is provided.

• Discord-Bot.Activity-Name. Activity text. Set to an empty string to display no activity.

• Discord-Bot.Authorized-Roles. Quoted Discord role IDs allowed to use /whitelist inside Discord servers. Application owners and accepted members of its owning team can also use it. Empty means application owner/team only, not every server member.

Minecraft messages accept MiniMessage colors and styles, legacy & codes and HEX colors. Full RGB requires Minecraft 1.16 or newer; older versions use the nearest legacy color. Text is serialized to Bukkit strings, so interactive hover and click components are not part of the message output.

Set a command feedback message to "" to silence it. An empty Prefix removes the prefix; an empty kick message still refuses access. The plugin’s built-in brace variables do not require PlaceholderAPI.

• Messages.Prefix. Prefix for Minecraft command feedback. Set to an empty string to remove it. It is not added to kick screens or Discord replies.

• Messages.No-Perms. A Minecraft command is denied by permissions.

• Messages.No-Args. Usage for missing or unknown command arguments.

• Messages.Reload. Successful reload feedback.

• Messages.W-ON. The whitelist has been enabled.

• Messages.W-OFF. The whitelist has been disabled.

• Messages.Added. Successful add operation; variable {player}.

• Messages.Removed. Successful remove operation; variable {player}.

• Messages.No-Whitelisted-Player. The requested name is not on the list.

• Messages.Already-Whitelisted. The requested name is already listed.

• Messages.Invalid-Name. The requested name fails validation; variable {player}.

• Messages.Cant-Remove. Removal is denied by AntiRemove for a protected online player.

• Messages.List. List output; variables {count} and {players}.

• Messages.List-Empty. Feedback when the list contains no names.

• Messages.Write-Failed. A file could not be read or written; variable {file}. See the console for details. Reload reads the three files independently.

• Messages.Update-Available. New-version notice; variables {version} and {current}.

• Messages.Kick-Message. Screen shown on the initial whitelist refusal. Use for multiple lines; no command prefix is added.

The separate Kick-Ban-Hooks.Ban-Message controls the ban reason and later internal-ban refusal screen.

Messages:
  Prefix: "<color:#BD987A><bold>OrangeWhitelist</bold></color> <dark_gray>» </dark_gray>"
  Added: "<gray>{player} is now on the list.</gray>"
  Removed: "<gray>{player} was removed from the list.</gray>"
  List: "<gray>Whitelist ({count}): <white>{players}</white></gray>"
  Kick-Message: "<color:#BD987A>OrangeWhitelist</color><newline><gray>You are not on this server’s whitelist.</gray>"

Whitelist.yml stores names under Players. Names are compared without case sensitivity. Add and remove operations confirm success after saving; temporary-file replacement reduces the chance of a partial list write.

Players:
  - "YourName"
  - ".Steve"

Bans.yml is used by the internal PLUGIN hook and records UUID, name and date. An absent file means there are no internal ban records. Do not delete it merely to turn whitelist enforcement off.

Before upgrading from version 3, back up the plugin folder, stop the server, replace the old JAR and start again. Existing player names migrate from the old Settings.yml Whitelist section into Whitelist.yml before configuration is updated. Legacy example entries are preserved rather than silently removed; review your imported list.

Supported user values are preserved, missing settings are restored, and changed Settings.yml files are backed up under old-configs/. Legacy Discord-Bot.Autorized-Roles, Bypass-Permission.Bypasss-Whitelist-Permission and AntiRemove.Anti-Remove-Permission migrate to their current names. Old %player%, %count% and %players% message tokens become brace variables.

Older bans created in Minecraft’s own ban list remain there. If you deliberately want to lift one, use /pardon <name>. LiteBans bans remain in LiteBans. /owl add <player> handles newly added names and matching internal version 4 PLUGIN bans.

Reload reads the three local files independently. An unreadable file is left intact and keeps its previous loaded values; other valid files may still apply. A failed whitelist read also blocks list mutations until the file is fixed and reloaded.

If Settings.yml cannot be read on startup, bundled defaults are used: whitelist enabled, KICK mode, Discord off and bypass off. An unreadable startup whitelist starts with no loaded names; an unreadable startup ban file starts with no loaded internal bans. Fix the reported file and reload before relying on its records.