SWhitelist | Group & Player Whitelist with Temporary Access

✦ SWhitelist ✦
Advanced player and group whitelist management with temporary and date-based access.

SWhitelist is a powerful and easy-to-use whitelist plugin with temporary access, exact expiration dates, LuckPerms group support, configurable bypass permissions, custom kick behavior, multiple languages, and automatic configuration migrations. It takes control of Minecraft's native whitelist so server access can be managed from one consistent system.

Features

• Player & Group Whitelisting: Whitelist individual player names or complete LuckPerms groups.
• Offline Player Support: Add players by name while they are offline or even before they join the server for the first time.
• Duration-Based Access: Grant temporary access with values such as 30m, 12h, 3d12h, or 2w.
• Date-Based Access: Grant access until an exact date and time with -d, including 12-hour and 24-hour time formats.
• Natural Date Shortcuts: Use today, tomorrow, weekday names such as monday, or expressions such as next friday.
• Exact Expiration: Temporary entries expire at their scheduled time and are removed automatically.
• LuckPerms Integration: Whitelist ranks or groups and allow their members to join automatically.
• Native Whitelist Control: Automatically disables Minecraft's native whitelist and redirects /whitelist to SWhitelist, preventing conflicting access rules and messages.
• Multi-Language Support: Includes English, Turkish, German, French, Spanish, Chinese, Russian, Portuguese, Japanese, Korean, and Polish language files.
• Automatic Migrations: Configuration and language files are upgraded without overwriting customized values.
• Consistent Bypass System: Operators, administrators, and players with the configured bypass permission can enter while the whitelist is active.
• Dynamic Access Enforcement: Optionally kick unauthorized players when the whitelist is enabled or when access is removed. Online access is also rechecked at the configured interval.
• Custom Messages & Sounds: Configure kick messages, expiration messages, join messages, and sound feedback for supported in-game management actions.
• Advanced Tab Completion: Friendly suggestions for commands, targets, durations, exact dates, natural date shortcuts, and time formats.

Supported Versions
(Tested Versions)

SWhitelist officially supports Minecraft 1.16.5 through 26.2 on Spigot and Paper. Testing is performed using the latest available builds for the supported versions. Please use the discussion section for bug reports and support requests.

Unsupported Versions

SWhitelist may start on versions older than 1.16.5, including some builds of 1.8.8 and 1.12.2, but these versions are not fully tested or officially supported.
Use on unsupported versions at your own risk. Support cannot be provided for version-specific issues below 1.16.5.

Date-Based Access

The -d option uses the server's local time zone. Dates use the month.day.year format and accept either 12-hour or 24-hour times. If no time is provided, access expires at 23:59:59 on the selected day. Past or invalid dates are rejected.

/swl add player Steve -d 2.23.2027 11:59 pm
/swl add player Alex -d tomorrow
/swl add group vip -d monday 18:00
/swl add group beta -d next friday 9:30 am

Commands & Permissions

• /swhitelist on
  • Enables the SWhitelist access check.
  • Permission: swhitelist.cmd.on
• /swhitelist off
  • Disables the SWhitelist access check and allows players to join without a whitelist entry.
  • Permission: swhitelist.cmd.off
• /swhitelist status
  • Shows the whitelist state and entry counts.
  • Permission: swhitelist.cmd.status
• /swhitelist add <player|group> <name> [-t <duration> | -d <date>]
  • Adds a permanent entry, a duration-based entry with -t, or a date-based entry with -d.
  • Permission: swhitelist.cmd.add
• /swhitelist remove <player|group> <name>
  • Removes a player or group from the whitelist.
  • Permission: swhitelist.cmd.remove
• /swhitelist temp <player|group> <name> <duration>
  • Legacy shortcut for adding a temporary player or group entry.
  • Permission: swhitelist.cmd.temp
• /swhitelist info <name>
  • Shows detailed entry information and detects access granted through a LuckPerms group.
  • Permission: swhitelist.cmd.info
• /swhitelist list [players|p|groups|g] [page]
  • Lists whitelist entries with optional filtering and pagination.
  • Permission: swhitelist.cmd.list
• /swhitelist reload
  • Reloads the configuration, messages, whitelist entries, aliases, and expiration tasks.
  • Permission: swhitelist.cmd.reload

Default aliases: /swl and /wl
Bypass permission: swhitelist.bypass
Administrator permission: swhitelist.admin (includes every SWhitelist command permission and bypass access)

Installation & Setup

1. Download the SWhitelist jar file from SpigotMC.
2. Place the jar in your server's plugins directory.
3. Restart or start the server to generate the configuration files.
4. Configure plugins/SWhitelist/config.yml according to your preferences.
5. Optionally install LuckPerms to enable group-based whitelisting.
6. Use /swhitelist reload after configuration changes, or restart the server.

Default Configuration (config.yml)

# ========================================
#       SWhitelist Configuration
# ========================================

# DO NOT CHANGE THIS
config-version: 4

# Language selection
# Available: en, tr, de, fr, es, zh, ru, pt, ja, ko, pl
language: en

# Whitelist toggle option
# Default: false
whitelist:
  enabled: false

# Command settings
commands:
  # Command aliases (it requires reload)
  aliases:
    - "swl"
    - "wl"
    #- "newcmd"
  # The permissions for each command, it can be customized.
  permissions:
    'list': "swhitelist.cmd.list"
    'add': "swhitelist.cmd.add"
    'remove': "swhitelist.cmd.remove"
    'temp': "swhitelist.cmd.temp"
    'on': "swhitelist.cmd.on"
    'off': "swhitelist.cmd.off"
    'status': "swhitelist.cmd.status"
    'info': "swhitelist.cmd.info"
    'reload': "swhitelist.cmd.reload"

# Kick settings
kick:
  # Kick message for players not on the whitelist
  message: "&c&lSWhitelist\n\n&fYou are not whitelisted on this server.\n&7Contact an administrator."
  # Kick message when a temporary whitelist entry expires
  expired-message: "&c&lSWhitelist\n\n&fYour whitelist access has expired.\n&7Contact an administrator."
  # Kick online player when removed from whitelist?
  kick-on-remove: true
  # Kick non-whitelisted online players when whitelist is enabled?
  kick-on-enable: true

# Send a message to whitelisted players when they join while whitelist is active
# Default: true
join-message:
  enabled: true

# Players with this permission bypass the whitelist
bypass-permission: "swhitelist.bypass"
# How often to re-check online players' whitelist access (in seconds)
expiration-check-interval: 5

# Sound Settings
# Default: true
sounds:
  enabled: true
  success:
    sound: ENTITY_EXPERIENCE_ORB_PICKUP
    volume: 1.0
    pitch: 1.2
  error:
    sound: ENTITY_VILLAGER_NO
    volume: 1.0
    pitch: 1.0

# Integration Settings
hooks:
  # Enable LuckPerms for group whitelist feature.
  # If it is enabled, the players who have the specified groups
  # will be whitelisted automatically.
  # It's required restart server for changes.
  # Default: false
  luckperms: false

Message File (en.yml)

# ========================================
#   SWhitelist Messages - English (en)
# ========================================
# Supports color codes: &a, &b, &c, etc.
# Supports HEX colors: &#FF5555
# Placeholders: {player}, {group}, {name}, {duration}, {date}, {count}, {type}, {remaining}, etc.

# DO NOT CHANGE THIS - used for automatic messages migration
messages-version: 5

prefix: "&6[SWhitelist] &r"

messages:
  # General
  no-permission: "&cYou don't have permission to use this command!"
  reload: "&aConfiguration, messages and whitelist have been reloaded."

  # Whitelist toggle
  enabled: "&aWhitelist has been enabled."
  disabled: "&cWhitelist has been disabled."
  already-enabled: "&eWhitelist is already enabled."
  already-disabled: "&eWhitelist is already disabled."

  # Add/Remove
  player-added: "&a{player} &fhas been added to the whitelist."
  group-added: "&a{group} &fgroup has been added to the whitelist."
  temp-player-added: "&a{player} &fhas been added to the whitelist for &e{duration}&f."
  temp-group-added: "&a{group} &fgroup has been added to the whitelist for &e{duration}&f."
  date-player-added: "&a{player} &fhas been added to the whitelist until &e{date}&f."
  date-group-added: "&a{group} &fgroup has been added to the whitelist until &e{date}&f."
  player-removed: "&a{player} &fhas been removed from the whitelist."
  group-removed: "&a{group} &fgroup has been removed from the whitelist."
  already-added: "&c{name} is already on the whitelist."
  not-found: "&c{name} was not found on the whitelist."

  # Status
  status-header: "&6&lWhitelist Status"
  status-state: " &7State: {state}"
  status-on: "&aEnabled"
  status-off: "&cDisabled"
  status-players: " &7Players: &f{count}"
  status-groups: " &7Groups: &f{count}"
  status-temp: " &7Temporary entries: &f{count}"

  # List
  list-header: "&6&lWhitelist ({filter}) &7- Page {page}/{total_pages}"
  list-entry: " &7- &e{name} &7[{type}] &8| &f{remaining}"
  list-empty: " &7No entries found."
  list-footer: " &7Use &e/swl list <filter> <page> &7to navigate."

  # Info
  info-header: "&6&lWhitelist Info: &e{name}"
  info-type: " &7Type: &f{type}"
  info-added-by: " &7Added by: &f{added_by}"
  info-added-at: " &7Added at: &f{added_at}"
  info-remaining: " &7Remaining: &f{remaining}"
  info-via-group: " &7Whitelisted via group: &a{group}"

  # Errors
  invalid-duration: "&cInvalid duration format! Examples: 1d12h, 30m, 2w, 1h30m"
  invalid-date: "&cInvalid or past date! Examples: 2.23.2027 11:59 pm, tomorrow, monday, next friday 18:00"
  luckperms-not-found: "&cLuckPerms is not available. Group features are disabled."
  player-not-exists: "&c{player} has never joined this server!"
  group-not-exists: "&cGroup '{group}' does not exist in LuckPerms!"

  # Usage messages
  usage-add: "&cUsage: /swl add <player|group> <name> [-t <duration> | -d <date>]"
  usage-remove: "&cUsage: /swl remove <player|group> <name>"
  usage-temp: "&cUsage: /swl temp <player|group> <name> <duration>"
  usage-info: "&cUsage: /swl info <name>"

  # Expiration
  expired-kicked: "&e{player}'s whitelist access has expired and they were kicked."
  join-message: "&aYou are whitelisted on this server. Welcome!"

  # Help menu
  help-header: "&6&lSWhitelist Commands"
  help-date: " &7- &eDate access: &f-d <date/time> &6(today, tomorrow, monday, next friday)"
  help-lines:
    - " &7- &e/swl add &6<player|group> &d<name> &6[-t <duration> | -d <date>] &7- &fAdd to whitelist"
    - " &7- &e/swl remove &6<player|group> &d<name> &7- &fRemove from whitelist"
    - " &7- &e/swl temp &6<player|group> &d<name> <duration> &7- &fAdd temporarily"
    - " &7- &e/swl list &6[players|p|groups|g] [page] &7- &fList whitelist entries"
    - " &7- &e/swl info &d<name> &7- &fShow entry details"
    - " &7- &e/swl on &7- &fEnable whitelist"
    - " &7- &e/swl off &7- &fDisable whitelist"
    - " &7- &e/swl status &7- &fShow whitelist status"
    - " &7- &e/swl reload &7- &fReload all configs"

FAQ

#1 Will there be support for older versions (1.8.8-1.15.2)?
Some older versions may allow the plugin to start, but they are not fully tested or officially supported. You may try them at your own risk, but support cannot be provided for problems specific to unsupported versions.

#2 Which Minecraft versions are officially supported?
Minecraft 1.16.5 through 26.2 on Spigot and Paper. If you encounter a problem, please use the discussion section and include the complete server version and error log.

#3 Does the plugin support both Spigot and Paper?
Yes. SWhitelist is designed and tested for both platforms within the supported version range.

#4 Can I add a player who is offline or has never joined before?
Yes. Add the player's name normally with /swl add player <name>. The player does not need to be online or have joined previously.

#5 Are there any dependencies?
There are no required dependencies. LuckPerms is optional and is only required for group-based whitelist entries.

#6 Which time zone is used by date-based access?
The server's local time zone is used. A date without a time expires at 23:59:59 on the selected day.

#7 Does this plugin support reloads?
The plugin's own /swhitelist reload command is supported. The server-wide /reload command is not recommended because it can cause conflicts between plugins; use a full server restart instead.

DO NOT USE REVIEWS FOR BUG REPORTS!

Usage Terms

This plugin is provided for personal and authorized server use only. Redistribution, resale, sublicensing, sharing, copying, modification for redistribution, or reuploading of this plugin, in whole or in part, is strictly prohibited without prior written permission from the author.

You may not sell, distribute, reproduce, or claim ownership of this plugin or any of its contents. Any unauthorized use, reproduction, or distribution may result in legal action.