EvenBetterWhitelist - Plugin

A modern whitelist system for Minecraft Paper 1.21.x with Discord integration. When a player attempts to join and is not whitelisted, a structured request is posted to your Discord channel. Admins can accept, deny, or ban directly from Discord using buttons.

Installation Steps

1. Place WhitelistPluginButBetter-1.0.0.jar in your server's plugins/ folder
2. Start/restart your server
3. Edit plugins/WhitelistPluginButBetter/config.yml
4. Download GeoLite2-City.mmdb and place it in the plugin folder
5. Reload with /wlp reload or restart the server

🤖 Discord Bot Setup

1. Create a Discord Application

1. Go to Discord Developer Portal
2. Click "New Application" and give it a name
3. Go to "Bot" section and click "Add Bot"
4. Copy the Bot Token (keep this secret!)
5. Enable these Privileged Gateway Intents:
   • Message Content Intent

2. Invite the Bot

1. Go to "OAuth2" → "URL Generator"
2. Select scopes: bot, applications.commands
3. Select permissions: Send Messages, Embed Links, Read Message History
4. Copy the generated URL and open it to invite the bot

3. Get Your IDs

Enable Developer Mode in Discord (Settings → Advanced → Developer Mode)

• Server ID: Right-click your server → Copy Server ID
• Channel ID: Right-click the channel → Copy Channel ID
• Admin User ID: Right-click yourself → Copy User ID

4. (Optional) Create a Webhook

1. Right-click your channel → Edit Channel
2. Go to Integrations → Webhooks
3. Create a webhook and copy the URL

⚙️ Configuration

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"
  admin-user-ids: "USER_ID_1,USER_ID_2"
  ping-admins: true

cooldowns:
  deny-cooldown: 60        # Minutes before denied player can try again
  pending-cooldown: 5      # Minutes between join attempts while pending
  ip-cooldown: 10          # Minutes before same IP can make new request

geoip:
  enabled: true
  database-path: "plugins/WhitelistPluginButBetter/GeoLite2-City.mmdb"

See the full config.yml for all options!

📝 Commands

Command	Description
/wlp accept <player>	Accept a pending whitelist request
/wlp deny <player>	Deny a pending whitelist request
/wlp pending	View all pending requests
/wlp list [page]	View whitelisted players
/wlp add <player>	Manually add a player to whitelist
/wlp remove <player>	Remove a player from whitelist
/wlp info <player>	View detailed player info
/wlp status	View plugin status
/wlp reload	Reload configuration

🔐 Permissions

Permission	Description	Default
whitelistplugin.admin	Access to all commands	OP
whitelistplugin.bypass	Bypass whitelist check	OP

Discord Embed Preview

When a player tries to join, admins receive an embed like this:

┌─────────────────────────────────────────┐
│ New Whitelist Request                   │
├─────────────────────────────────────────┤
│ Player: Steve                           │
│ UUID: 069a79f4-...                      │
│ IP: ||192.168.1.1||                     │
│ Location: New York, United States       │
│ Client: fabric                          │
│ Language: en_US                         │
│ Requested: 2024-01-15 14:30 UTC         │
│                                         │
│ Same IP as: Alex (1 other request)      │
│                                         │
│ [Accept]  [Deny]  [Ban]                 │
└─────────────────────────────────────────┘

🗂️ File Structure

plugins/WhitelistPluginButBetter/
├── config.yml              # Main configuration
├── whitelist.json          # Whitelisted players
├── pending-requests.json   # Pending requests
├── denied-players.json     # Denied players (for cooldowns)
├── requests.log            # Action log
└── GeoLite2-City.mmdb      # GeoIP database (you provide this)

Troubleshooting

Bot not responding to buttons?

• Make sure the bot token is correct
• Ensure the bot has permissions in the channel
• Check console for connection errors

GeoIP not working?

• Download GeoLite2-City.mmdb from MaxMind
• Place it in the plugin folder
• Check the path in config.yml

Players not being kicked?

• Make sure the plugin is loaded (/plugins)
• Check if player has whitelistplugin.bypass permission
• Look for errors in console

Seeing Private IP (10.x.x.x, 192.168.x.x)?

This happens when using a reverse proxy (BungeeCord, Velocity, TCPShield, etc.)

For BungeeCord:

1. Set bungeecord: true in spigot.yml
2. Restart the server

For Velocity:

1. Edit config/paper-global.yml
2. Set proxies.velocity.enabled: true
3. Set the secret to match Velocity's forwarding secret
4. Restart the server

For TCPShield/Other:
Follow your proxy's documentation for IP forwarding.

Client/Language shows "N/A (Pre-login)"?

This is expected! The plugin intercepts players before they fully connect, so client brand and locale data isn't available yet. This is a Minecraft limitation, not a bug.

The data we DO capture (IP, UUID, GeoIP location) is still very useful for identifying players and alts!

📜 License

All Rights Reserved.Any modifications without informing is illegal.

Made for the Minecraft community!