🍊OrangeWhitelist

OrangeWhitelist is a safe, modern and customizable whitelist plugin for Minecraft servers. This plugin provides comprehensive whitelist management with multiple enforcement modes, Discord integration, and support for popular ban plugins like LiteBans.

Main Features

🛡️ Advanced Whitelist System

• Flexible Enforcement: Choose between KICK or BAN modes for non-whitelisted players

• Real-time Management: Add/remove players from whitelist without server restart

• Auto-kick System: Automatically removes non-whitelisted players when whitelist is enabled

• Permission-based Access: Fine-grained permission control for all operations

🔧 Multiple Ban Hooks

• Internal Hook: Built-in kick/ban system

• LiteBans Integration: Automatic detection and integration with LiteBans plugin

• Smart Fallback: Automatically switches to internal hook if LiteBans is not found

• Customizable Messages: Different messages for kicks and bans

🤖 Discord Bot Integration

• Multi-language Support: English, Español, Français, 中文

• Custom Status: Configurable bot status and activity

• Role Authorization: Restrict bot commands to specific Discord roles

• Real-time Sync: Manage whitelist directly from Discord

⚡ Performance & Reliability

• Async Operations: Non-blocking operations for optimal server performance

• Thread-safe: Safe concurrent access to whitelist data

• Auto-updates: Built-in update checker with notifications

• Clean Joins/Leaves: Suppresses join/leave messages for kicked players

Configuration

Complete Configuration File

# Version of the configuration file / plugin, do not
# modify this file or you will disrupt the
# version and a new file will be created.
Config-Version: 3.0
Plugin-Version: 3.6

###############################
##      Plugin Config        ##
###############################
# Main settings for the plugin.
Plugin-Config:
  # Enable or disable the Whitelist feature.
  Enabled-Whitelist: true
  # Select the mode for non-whitelisted users: KICK or BAN.
  Mode: KICK # Options: KICK - BAN

###############################
##      Kick-Ban Hooks       ##
###############################
# Configuration of hooks for handling kicks and bans.
# This section determines the method used to enforce penalties on players
# who are not on the whitelist.
# Available options:
#   PLUGIN: Uses the internal hook of the plugin (InternalBanHook).
#   LiteBans: Uses LiteBans to ban the player via console command
#             (/litebans:ban), provided LiteBans is installed on the server.

Kick-Ban-Hooks:
  # Specifies the hook to use. If "LiteBans" is selected but not found,
  # it will automatically switch to "PLUGIN" and update this configuration.
  Hook: PLUGIN
  # Message displayed to the player when they are kicked for not being on the whitelist.
  Kick-Message: 'You are not in the Whitelist of this server'
  # Message displayed to the player when they are banned for not being on the whitelist.
  Ban-Message: 'You are not in the Whitelist of this server!!!'


###############################
##      Plugin Messages      ##
###############################
# Messages that will be displayed to players.
Messages:
  Prefix: '<aqua>Fruit<white>Forge <dark_gray><bold>» <reset>'
  No-Perms: '<red>You dont have permission to do that'
  No-Args: '<red>Command is missing arguments'
  Reload: '<green>Plugin ready!'
  W-ON: '<green>The whitelist has been activated'
  W-OFF: '<red>The whitelist has been deactivated'
  Added: '<green>The user %player% was added to the whitelist'
  Removed: '<red>The user %player% was removed to the whitelist'
  No-Whitelisted-Player: '<red>This player does not exist or was no longer on the Whitelist'
  Already-Whitelisted: '<green>The player is already on the Whitelist'
  Kick-Message: |-
    <dark_gray>|-------------------------------------|
    <aqua>Fruit<white>Forge <yellow>Studios
    
    <red>You are not on the server Whitelist!</red>
    
    <dark_purple>Discord: https://fruitforge.com/discord</dark_purple>
    <dark_gray>|-------------------------------------|

###############################
##    Plugin Permissions     ##
###############################
# Define the permissions required to perform plugin actions.
Permissions:
  # Permission to enable or disable the whitelist.
  Enable-Disable: orangewhitelist.set
  # Permission to add or remove players from the whitelist.
  Add-Remove: orangewhitelist.manage
  # Permission to reload the plugin configuration.
  Reload: orangewhitelist.reload
  # Grants all permissions related to the plugin.
  ALL: orangewhitelist.admin

###############################
##         Whitelist         ##
###############################
# List of players allowed on the server when whitelist is active.
Whitelist:
  - Notch
  - TeoremalDev

###############################
##      Discord Bot Config   ##
###############################
Discord-Bot:
  # Enable or disable the Discord bot integration.
  # Set to "true" to activate the bot, or "false" to disable it.
  Enabled: false

  # The bot token from the Discord Developer Portal.
  # Replace this with your bot's token to authenticate it with Discord.
  Token: "YOUR_DISCORD_BOT_TOKEN_HERE"

  # The application ID of the bot.
  # Obtain this from the Discord Developer Portal under your bot's application settings.
  Application-ID: "YOUR_APPLICATION_ID_HERE"

  # Language for bot responses.
  # Options: English, Español, Français, 中文
  # The language will apply for everything about the bot, for example commands, descriptions and messages
  Language: English

  # Bot status configuration
  # The status of the bot. This controls how the bot appears on Discord.
  # Possible values:
  # - "online": The bot is online and active.
  # - "idle": The bot is idle (yellow status).
  # - "dnd": Do not disturb (red status).
  # - "invisible": The bot appears offline but is still active.
  # Default: "online"
  Status: "online"

  # Bot activity configuration
  # The type of activity the bot is performing. This is a number that defines the activity type.
  # Possible values:
  # - 0: Playing (e.g., "Playing Minecraft")
  # - 1: Streaming (e.g., "Streaming a game")
  # - 2: Listening (e.g., "Listening to Spotify")
  # - 3: Watching (e.g., "Watching a movie")
  # Default: 0
  Activity-Type: 0

  # The name of the activity.
  # This is the text that appears next to the activity type, e.g., "Minecraft" for "Playing Minecraft".
  # If left empty (""), no activity will be shown.
  Activity-Name: "Minecraft"

  Autorized-Roles:
    - 1332172805093064736
    - 1332165152228905052

Configuration Options

Plugin Configuration

Plugin-Config

• Enabled-Whitelist: true/false - Enable or disable the whitelist feature globally

• Mode: KICK/BAN - Choose enforcement mode for non-whitelisted players

Kick-Ban Hooks

Kick-Ban-Hooks

• Hook: PLUGIN/LiteBans - Select the ban system to use

  • PLUGIN: Uses internal kick/ban system

  • LiteBans: Integrates with LiteBans plugin (auto-detects installation)

• Kick-Message: Message shown when a player is kicked from whitelist

• Ban-Message: Message shown when a player is banned from whitelist

Plugin Messages

All plugin messages support MiniMessage formatting:

• Prefix: Plugin message prefix

• No-Perms: No permission message

• No-Args: Missing arguments message

• Reload: Plugin reload success message

• W-ON: Whitelist enabled message

• W-OFF: Whitelist disabled message

• Added: Player added to whitelist message (supports %player% variable)

• Removed: Player removed from whitelist message (supports %player% variable)

• No-Whitelisted-Player: Player not in whitelist error message

• Already-Whitelisted: Player already whitelisted message

• Kick-Message: Custom kick message displayed to non-whitelisted players

Permissions

Permission Nodes

• Enable-Disable: orangewhitelist.set - Permission to enable/disable whitelist

• Add-Remove: orangewhitelist.manage - Permission to manage whitelist players

• Reload: orangewhitelist.reload - Permission to reload plugin configuration

• ALL: orangewhitelist.admin - Grants all plugin permissions

Whitelist

Player List

• Whitelist: List of player names allowed on the server when whitelist is active

• Case-insensitive player name matching

• Supports any valid Minecraft username

Discord Bot Configuration

Discord-Bot Settings

• Enabled: true/false - Enable Discord bot integration

• Token: Discord bot token from Developer Portal

• Application-ID: Bot application ID from Developer Portal

• Language: Bot language (English, Español, Français, 中文)

Bot Status

• Status: Bot presence status

  • online: Green online status

  • idle: Yellow idle status

  • dnd: Red do not disturb status

  • invisible: Appears offline but functional

Bot Activity

• Activity-Type: Type of activity displayed

  • 0: Playing

  • 1: Streaming

  • 2: Listening

  • 3: Watching

• Activity-Name: Activity description text

Authorization

• Authorized-Roles: List of Discord role IDs that can use bot commands

Commands

/orangewhitelist <subcommand> [arguments]

Main command for all whitelist operations.

Subcommands

/orangewhitelist on

• Description: Enable the whitelist

• Permission: orangewhitelist.set or orangewhitelist.admin

• Effect: Activates whitelist and kicks non-whitelisted players

/orangewhitelist off

• Description: Disable the whitelist

• Permission: orangewhitelist.set or orangewhitelist.admin

• Effect: Deactivates whitelist allowing all players to join

/orangewhitelist add <player>

• Description: Add a player to the whitelist

• Permission: orangewhitelist.manage or orangewhitelist.admin

• Arguments: <player> - Player name to add

• Effect: Adds player to whitelist and saves configuration

/orangewhitelist remove <player>

• Description: Remove a player from the whitelist

• Permission: orangewhitelist.manage or orangewhitelist.admin

• Arguments: <player> - Player name to remove

• Effect: Removes player from whitelist and kicks if online

/orangewhitelist list

• Description: Display all whitelisted players

• Permission: orangewhitelist.manage or orangewhitelist.admin

• Effect: Shows current whitelist in chat

/orangewhitelist reload

• Description: Reload plugin configuration

• Permission: orangewhitelist.reload or orangewhitelist.admin

• Effect: Reloads config and restarts Discord bot if enabled

Permissions

Permission	Description	Default
orangewhitelist.set	Enable/disable whitelist	OP
orangewhitelist.manage	Add/remove players from whitelist	OP
orangewhitelist.reload	Reload plugin configuration	OP
orangewhitelist.admin	All whitelist permissions	OP

Available Variables

In messages you can use the following variables:

• %player% - Username of the player being added/removed from whitelist

Hook System

Internal Hook (Default)

• Built-in kick and ban system

• No external dependencies

• Immediate enforcement

• Customizable kick/ban messages

LiteBans Integration

• Automatic detection of LiteBans plugin

• Uses LiteBans console commands for enforcement

• Maintains ban history in LiteBans database

• Automatic fallback to internal hook if LiteBans not found

Discord Bot Features

Multi-language Support

The bot supports multiple languages for all commands and messages:

• English: Default language

• Español: Spanish language

• Français: French language

• 中文: Chinese language

Discord Commands

When enabled, the Discord bot provides commands to manage the whitelist directly from Discord:

• Whitelist management commands

• Player status checking

• Real-time server information

Role-based Authorization

Only users with specified Discord roles can use bot commands, ensuring secure access to whitelist management.

How It Works

Player Join Process

1. Player Connects: Player attempts to join the server

2. Whitelist Check: Plugin checks if whitelist is enabled

3. Name Verification: If enabled, verifies player name against whitelist

4. Enforcement: If not whitelisted, applies configured action (KICK/BAN)

5. Message Suppression: Suppresses join/leave messages for rejected players

Whitelist Management

1. Add Player: Player name added to configuration whitelist

2. Remove Player: Player name removed and kicked if online

3. Enable/Disable: Instant whitelist state change with automatic enforcement

4. Real-time Updates: All changes take effect immediately without restart

Discord Integration

1. Bot Initialization: Bot connects to Discord with configured token

2. Command Registration: Slash commands registered for whitelist management

3. Authorization: Role-based access control for security

4. Real-time Sync: Changes made in Discord sync immediately with server

Installation

Basic Installation

1. Download OrangeWhitelist plugin

2. Place the .jar file in your server's plugins/ folder

3. Restart the server

4. Configure the generated config.yml file

5. Set up permissions as needed

6. Use /orangewhitelist reload to apply changes

Discord Bot Setup (Optional)

1. Create a Discord application at https://discord.com/developers/applications

2. Create a bot and copy the token

3. Copy the application ID

4. Enable the Discord bot in configuration:

   Discord-Bot:
     Enabled: true
     Token: "YOUR_BOT_TOKEN_HERE"
     Application-ID: "YOUR_APPLICATION_ID_HERE"

5. Add authorized role IDs to the configuration

6. Reload the plugin to activate the bot

LiteBans Integration (Optional)

1. Install LiteBans plugin on your server

2. Configure OrangeWhitelist to use LiteBans:

   Kick-Ban-Hooks:
     Hook: LiteBans

3. Reload OrangeWhitelist configuration

4. Plugin will automatically detect and integrate with LiteBans

Compatibility

• Minecraft Version: 1.8 - 1.21.7

• Server Software: Spigot, Paper, and forks

• Dependencies: None (LiteBans optional)

• Discord Integration: Optional Discord bot functionality

Advanced Features

Thread Safety

• All whitelist operations are thread-safe

• Async operations prevent server lag

• Main thread scheduling for Bukkit API calls

Performance Optimization

• Efficient player name lookup

• Minimal memory footprint

• Non-blocking configuration saves

Error Handling

• Graceful fallback systems

• Comprehensive error logging

• Automatic configuration validation

Troubleshooting

Common Issues

Whitelist not working

• Verify Enabled-Whitelist: true in configuration

• Check player permissions

• Ensure correct player names in whitelist

Discord bot not responding

• Verify bot token and application ID

• Check authorized roles configuration

• Ensure bot has necessary Discord permissions

LiteBans integration failing

• Verify LiteBans plugin is installed and enabled

• Check server logs for integration messages

• Plugin will auto-fallback to internal hook

Debug Information

• Plugin logs important events to console

• Configuration validation on startup

• Automatic hook detection and fallback

Support

For support, bug reports, or feature requests:

• Discord: https://fruitforge.com/discord

---

Plugin developed by FruitForge Studio