OrangeWhitelist 4.0

A community starts with the people you invite. OrangeWhitelist gives you a clear way to manage who may join, with commands in Minecraft, optional staff tools in Discord and settings you can make your own.

Keep a player-name list, choose what happens to unlisted players and decide where staff exemptions belong. Manage it with /owl from Minecraft or the server console.

• Check at the door. The default setup checks unlisted names before the player joins the world. Existing access refusals from other plugins are respected.
• Choose your response. Use KICK for whitelist refusals, or BAN with the plugin’s internal ban list or an optional LiteBans hook. Customize the refusal screen and ban reason.
• Make exemptions deliberate. Permission bypass is opt-in and disabled by default. Admin permissions alone do not exempt a player from the list.
• Keep online staff listed. Optional AntiRemove stops removal of connected players with your chosen permission. Offline names remain editable.
• Use familiar names. Names are matched without case sensitivity. Selected prefixes such as .Steve are supported within the 16-character limit.

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.

Enable the integrated Discord bot to let authorized staff manage the same Minecraft list from your Discord server. The bot is optional; all Minecraft commands work without it.

• Five slash operations. Enable, disable, add, remove and list with /whitelist. Changes use the same whitelist operations as the Minecraft commands.
• Authorize your roles. Use Discord role IDs to choose who may manage access. The application owner and its accepted owning-team members are also eligible.
• Useful suggestions. Add autocomplete suggests recently refused names and online players not yet listed. Remove autocomplete suggests current list entries.
• Choose a language. English, Spanish, French and Chinese are available for the bot’s command descriptions and its own feedback.
• Stay connected. The bot handles heartbeats, resumable sessions and automatic reconnects. Invalid credentials stop retries until a reload or restart.

/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.

Version 4 rebuilds whitelist management around separate local files and bundles its text libraries in the JAR. Upgrade your existing list or start a new community with the same straightforward setup.

• Minecraft: 1.8.8–26.3 on Spigot and Paper. Install OrangeWhitelist-4.0.jar on the Minecraft server.
• Java: use your server software’s required Java version. The plugin targets Java 8 bytecode; modern Minecraft servers still need their own newer Java runtime.
• Dependencies: no additional plugin is required. LiteBans is optional, and the Discord client is included. There is no PlaceholderAPI integration.
• Files: Settings.yml holds configuration, Whitelist.yml holds player names and Bans.yml holds internal bans when used. No database setup is needed.

Install & configure

1. Place OrangeWhitelist-4.0.jar in the server’s plugins folder and start the server.
2. A new install enables the whitelist with an empty list. From the console, run owl add YourName before connecting. Add the rest of your players, or use owl disable while preparing access.
3. Open plugins/OrangeWhitelist/Settings.yml. Choose KICK or BAN, messages, command permissions and any optional bypass, AntiRemove or Discord settings.
4. Run /owl reload, then /owl list. Test with a listed name and an unlisted name before inviting your community.

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 <newline> 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.

Need help with access rules or the Discord bot? Share your Minecraft and plugin versions, the relevant console error and a configuration excerpt with the bot token removed.

Teramont is our hosting partner. Get 15% off your first month with code Byte.