EvenBetterWhitelist

Quick Start

1. Download the plugin from Modrinth and place the jar in plugins/.
2. Start the server once to generate config.yml.
3. Fill Discord settings (bot token, channel id; optional webhook).
4. (Optional) Download GeoLite2-City.mmdb if GeoIP is enabled.
5. Restart the server or run /wlp reload.

Configuration

Key groups from config.yml.

discord:
  bot-token: "YOUR_BOT_TOKEN_HERE"
  webhook-url: "YOUR_WEBHOOK_URL_HERE"
  server-id: "YOUR_SERVER_ID_HERE"
  channel-id: "YOUR_CHANNEL_ID_HERE"
  link-channel-id: ""              # Optional: restrict where users run the link command
  command-prefix: "\\"            # Message-based command prefix (e.g. \link)
  admin-user-ids: "123,456"       # Optional pings
  ping-admins: true
  admin-panel-enabled: true
  admin-panel-channel-id: ""      # Channel for the whitelist panel embed

cooldowns:
  deny-cooldown: 60
  pending-cooldown: 5
  ip-cooldown: 10
  deny-expire-days: 7

captcha:
  enabled: false
  type: "math"            # math | text | color
  math-difficulty: "easy" # easy | medium | hard
  timeout-seconds: 60
  max-attempts: 3
  fail-ban-minutes: 30
  show-timer: true
  sounds:
    enabled: true
    success: "ENTITY_PLAYER_LEVELUP"
    fail: "ENTITY_VILLAGER_NO"
    timeout: "ENTITY_WITHER_DEATH"

vpn-detection:
  enabled: true
  primary-provider: "ip-api"
  fallback-provider: "proxycheck"
  proxycheck-api-key: ""
  action: "flag"        # flag | deny | none
  detect:
    vpn: true
    proxy: true
    tor: true
    hosting: true
  cache-minutes: 60
  log-checks: true

auto-accept:
  enabled: false
  high-reputation: false
  trusted-ips: false
  ip-whitelist: []
  previously-accepted: true

embed-colors:
  pending: "5865F2"
  accepted: "57F287"
  denied: "ED4245"

# Panel options:
# discord.admin-panel-enabled: true
# discord.admin-panel-channel-id: "YOUR_CHANNEL_ID"

discord-linking:
  enabled: false
  require-before-whitelist: true
  one-to-one: true
  min-account-age-days: 7
  require-verified-email: false
  code-expiry-minutes: 10
  links-file: "plugins/WhitelistPluginButBetter/discord-links.json"

Discord Account Linking

1. In your Discord server, type \link (or your configured prefix) in a channel where the bot can reply. If discord.link-channel-id is set, use that channel.
2. The bot will DM you a six-character code.
3. Join the Minecraft server. If linking is required, you will be frozen and prompted to type that code in chat.
4. After a successful link, the plugin proceeds to captcha (if enabled) or sends a whitelist request and disconnects you with a confirmation.

Captcha Flow

• Non-whitelisted players are allowed to join in a frozen, invisible state.
• A captcha question appears in chat. The player must answer within the configured time and attempts.
• On success, a whitelist request is sent to Discord and the player is disconnected with a confirmation message.
• On failure/timeout, the player is disconnected. Repeated failures can temporarily ban the IP.

Discord Workflow

• The plugin posts a structured request to your configured Discord channel when a player attempts to join and is not whitelisted.
• Admins can accept, deny, or ban directly from the message when the bot is connected. Webhook-only delivery provides embeds without buttons.
• The optional admin panel embed lists current whitelisted players with a dropdown to remove entries; it updates automatically on changes.

Commands & Permissions

Troubleshooting