Minecraft Discord Bot

A feature-rich Discord bot for managing Minecraft servers with unique features like story recaps, time capsules, build showcases, and more.

Features

• 🔐 Self-Service Whitelist - Simple whitelist management to block port scanners
• 💬 Chat Bridge - Bidirectional chat between Discord and Minecraft
• 🎮 Server Control - Start, stop, restart, and monitor your server
• 📊 Player Stats - Track playtime, deaths, achievements (no coordinates!)
• 🛡️ Moderation Tools - Kick, ban, mute, warn with full logging
• 📖 Story Recaps - Automated narrative summaries of server activity
• ⏰ Time Capsules - Send messages to your future self
• 🏗️ Build Showcase - Gallery system without coordinate leaks
• 🔔 Personal Alerts - Get notified when friends join
• 📬 Offline Messages - Send messages to offline players
• 🎉 Event Management - Create and manage server events
• ✨ Custom Join Messages - Personalized welcome messages

Setup

Prerequisites

• Python 3.8 or higher
• A Minecraft server (Spigot/Paper) with RCON enabled
• A Discord bot token

Installation

1. Clone the repository:

git clone https://github.com/JosFa1/MinecraftDiscordBot.git
cd MinecraftDiscordBot

2. Install dependencies:

pip install -r requirements.txt

3. Configure your bot:

cp .env.example .env
# Edit .env with your settings

4. Initialize the database:

python -c "from database.models import init_db; init_db()"

5. Run the bot:

python main.py

Configuration

Edit the .env file with your settings:

• DISCORD_TOKEN - Your Discord bot token
• DISCORD_GUILD_ID - Your Discord server ID
• MC_RCON_HOST - Your Minecraft server IP
• MC_RCON_PORT - RCON port (default: 25575)
• MC_RCON_PASSWORD - Your RCON password
• Channel and role IDs (get these after inviting the bot)

Enable RCON on your Minecraft Server

Edit server.properties:

enable-rcon=true
rcon.port=25575
rcon.password=your_secure_password_here

Usage

Basic Commands

• /mc whitelist <minecraft_name> - Add yourself to the whitelist
• /mc player <name> - View player stats
• /server status - Check server status
• /timecapsule create <message> <duration> - Create a time capsule
• /build link <name> - Link a screenshot to your build
• /alert friend <name> - Get notified when a friend joins

Admin Commands

• /server restart - Restart the server with countdown
• /server lock - Lock the server (prevent all joins)
• /mc kick/ban/mute <player> - Moderation commands

See FEATURE_PLAN.md for full feature documentation.

Project Structure

MinecraftDiscordBot/
├── main.py                 # Main bot entry point
├── config.py              # Configuration management
├── requirements.txt       # Python dependencies
├── database/
│   ├── models.py          # Database models
│   └── session.py         # Database session management
├── cogs/
│   ├── whitelist.py       # Whitelist commands
│   ├── server.py          # Server control
│   ├── moderation.py      # Moderation commands
│   ├── stats.py           # Player stats
│   ├── time_capsules.py   # Time capsule system
│   ├── builds.py          # Build showcase
│   ├── alerts.py          # Alert system
│   ├── events.py          # Event management
│   └── messages.py        # Offline messages
├── utils/
│   ├── rcon.py            # RCON connection
│   ├── message_queue.py   # Message batching
│   ├── filters.py         # Coordinate filtering
│   └── permissions.py     # Permission checks
└── tasks/
    ├── chat_bridge.py     # Chat bridge background task
    ├── story_recaps.py    # Story recap generation
    └── capsule_delivery.py # Time capsule delivery

Contributing

Contributions are welcome! Please open an issue or pull request.

License

MIT License - see LICENSE file for details