🛡️ 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+.

---