Even Better Whitelist

A professional whitelist workflow with Discord actions, dual VPN/Proxy detection, GeoIP, optional captcha, Discord account linking, and statistics. Built for production servers.

Quick challenge

How far can you run before the mobs catch you?

Even Better Whitelist

EvenBetterWhitelist - Plugin

Modrinth

Minecraft

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 Privileged Gateway Intents 2. Click "New Application" and give it a name 3. Go to "Bot" section and click "Add Bot" 4. Copy the Privileged Gateway Intents (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)

- Admin User ID: Right-click your server → Copy Server ID - Admin User 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

```yaml 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!