🛡️ WhitelistBot

Automatically whitelist players from a Discord channel — no commands, no hassle.

WhitelistBot bridges your Discord server and Minecraft server. Set up a dedicated channel, and when a player sends their Minecraft username, the bot instantly whitelists them and replies with a colour-coded embed. One username per Discord account, always.

✨ Features

• 📨 Discord → Minecraft whitelisting — players send their username in a channel, bot does the rest
• 🔒 One username per Discord user — enforced via SQLite database, no duplicates
• ✅ Smart validation — checks for invalid characters, already-whitelisted players, and taken usernames
• 🌐 Web dashboard — add and remove entries from a browser with a searchable table
• 🔑 Auto-generated password — random login saved to webpage.yml on first launch
• 🔄 In-game reload — /wlbot reload reloads config and restarts the bot without restarting the server
• 🎨 Colour-coded embeds — green for success, red for errors, brown for invalid input, orange for already registered

📋 Embed Responses

| Situation | Colour | Message |
|---|---|---|
| Valid new username | 🟢 Green | ✅ Successfully Whitelisted |
| Invalid username format | 🟫 Brown | ⚠️ Invalid Characters |
| Discord user already registered | 🟠 Orange | ⚠️ Already Registered |
| Username taken by another user | 🔴 Red | ❌ Username Taken |
| Already on whitelist | 🔴 Red | ❌ Already Whitelisted |

⚙️ Setup

1. Create a Discord Bot

1. Go to discord.com/developers/applications → New Application
2. Navigate to Bot → copy your token
3. Enable Message Content Intent under Privileged Gateway Intents
4. Under OAuth2 → URL Generator, select bot scope with Read Messages + Send Messages permissions and invite it to your server

2. Get Your IDs

Enable Developer Mode in Discord Settings → Advanced, then:

• Right-click your server → Copy Server ID
• Right-click your whitelist channel → Copy Channel ID

3. Configure the Plugin

Edit plugins/WhitelistBot/config.yml:

discord:
  bot-token: "YOUR_BOT_TOKEN_HERE"
  guild-id: "YOUR_GUILD_ID_HERE"
  channel-id: "YOUR_CHANNEL_ID_HERE"

4. Web Dashboard

On first launch, plugins/WhitelistBot/webpage.yml is created with a randomly generated password:

web:
  password: "a3f9c2d1e8b04f7a"
  port: 8080

Open http://your-server-ip:8080 in your browser to access the dashboard.

🌐 Web Dashboard

The built-in dashboard lets you manage whitelist entries without touching the server console.

• Add entries — enter a Discord ID + Minecraft username to add and whitelist instantly
• Remove entries — remove by Discord ID, automatically runs /whitelist remove
• Search — filter the table by Discord ID or Minecraft username
• Secure login — session-based auth with your webpage.yml password

To change the password or port, edit webpage.yml and run /wlbot reload.

🔧 Commands & Permissions

| Command | Description | Permission |
|---|---|---|
| /wlbot reload | Reloads config and restarts the bot | whitelistbot.reload (default: op) |

🗄️ Database

All entries are stored in plugins/WhitelistBot/whitelist.db (SQLite). You can open it with DB Browser for SQLite to view or manage entries manually.

The database stores:

• Discord ID
• Minecraft username
• Timestamp of when they were whitelisted

🖥️ Compatibility

| Minecraft Version | Supported |
|---|---|
| 1.18.x | ✅ |
| 1.19.x | ✅ |
| 1.20.x | ✅ |
| 1.21.x | ✅ |

Requires Paper or Spigot. Java 17+ required for 1.18–1.19, Java 21+ for 1.20+.