# CosBot **A premium, production-ready Discord bot with advanced features** built with Node.js v20 and discord.js v14. ## en Features ### 🎵 Music System - Play songs from YouTube with search - Queue management with full control - Pause, resume, skip, and stop controls - Auto-disconnect when voice channel is empty - Display current queue with song info ### 🎉 Giveaway System - Create giveaways with customizable duration and prizes - Automatic winner selection when time expires - Reroll functionality for new winners - Button-based entry system - Persistent storage with MongoDB ### 🛡️ Moderation Commands - Ban, kick, timeout, and unban commands - Bulk message deletion (up to 100 messages) - Professional moderation logging ### 🤖 AutoMod System - **Anti-Spam** - Detect and punish spammers automatically - **Anti-Link** - Block unauthorized links - **Anti-Invite** - Prevent Discord invite links - **Anti-Caps** - Remove messages with excessive capitalization - **Anti-Mass Mention** - Stop mention spam - **Bad Word Filter** - Custom word filtering - Configurable actions (delete, timeout, kick, ban) - Bypass roles for staff - Detailed logging ### 🚨 Anti-Nuke Protection - Protect against mass channel/role deletion - Configurable action limits and timeframes - Automatic punishment (ban, kick, or strip roles) - Whitelist trusted users - Real-time tracking and logging ### 🎫 Premium Ticket System - Multiple ticket categories (General, Report, Premium, Account, Other) - Beautiful ticket panels with select menus - Ticket claiming system for staff - Add/remove users from tickets dynamically - Automatic transcripts saved and sent to users - Ticket logging in dedicated channel - Support role permissions - One ticket per user limit - Professional embeds with user info ### 👥 Staff Management System - Staff application system with approval workflow - Activity tracking for staff members - Inactivity detection and warnings - Leave request system with approval - Staff reporting system - Activity leaderboards - Comprehensive logging ### ✅ Verification System - Button-based verification - Auto-role assignment - Welcome messages - Persistent verification status ### 🎮 Minecraft Status Checker - Check any Minecraft server status - Display player count and MOTD - Show server icon and version - List online players ### ⚙️ Utility Commands - Customizable prefix per server - Help command (auto-lists all commands) - Ping and uptime commands - Server and user information - Professional embeds ## Requirements - Node.js v20 or higher - MongoDB (local or cloud) - Discord Bot Token - FFmpeg (for music functionality) ## Installation ### Prerequisites - **Node.js v20+** - [Download here](https://nodejs.org/) - **MongoDB** - [Local installation](https://www.mongodb.com/try/download/community) or [MongoDB Atlas (free cloud)](https://www.mongodb.com/cloud/atlas) - **FFmpeg** - Required for music (Windows: [Download](https://ffmpeg.org/download.html), Linux: `sudo apt install ffmpeg`) - **Discord Bot Token** - [Create bot here](https://discord.com/developers/applications) ### Step 1: Clone Repository ```bash git clone cd astralbot ``` ### Step 2: Install Dependencies ```bash npm install ``` ### Step 3: Configure Environment Create a `.env` file in the root directory: ```env DISCORD_TOKEN=your_discord_bot_token_here MONGODB_URI=mongodb://localhost:27017/astralbot CLIENT_ID=your_bot_client_id ``` **MongoDB Atlas URI Format:** ``` mongodb+srv://username:password@cluster.mongodb.net/astralbot?retryWrites=true&w=majority ``` ### Step 4: Setup Discord Bot 1. Go to [Discord Developer Portal](https://discord.com/developers/applications) 2. Create a new application 3. Go to **Bot** section and create a bot 4. Copy the token and add to `.env` 5. Enable these **Privileged Gateway Intents**: - en Presence Intent - en Server Members Intent - en Message Content Intent 6. Go to **OAuth2 > URL Generator** 7. Select scopes: `bot` and `applications.commands` 8. Select permissions: `Administrator` (or specific permissions) 9. Use generated URL to invite bot to your server ### Step 5: Start the Bot ```bash npm start ``` For development with auto-reload: ```bash npm run dev ``` ### Step 6: Setup Commands (First Time) After starting the bot, slash commands will automatically register. Wait 1-2 minutes for them to appear in Discord. ## Quick Setup Guide After inviting the bot, run these commands to get started: 1. **Ticket System:** ``` /ticket-setup category: support-role: log-channel: /ticket-panel ``` 2. **AutoMod:** ``` /automod-setup anti-spam enabled:true /automod-setup anti-invite enabled:true /automod-setup log-channel channel: ``` 3. **Anti-Nuke:** ``` /antinuke-setup enable /antinuke-setup log-channel channel: /antinuke-setup whitelist user: ``` 4. **Staff System:** ``` /staff-setup roles role: /staff-setup logs channel: /staff-setup applications channel: ``` 5. **Verification:** ``` /verification-setup role: channel: ``` ## Premium Features Included en This bot includes features found in premium bots like: - en **Advanced Ticket System** with categories, claiming, transcripts - en **Anti-Nuke Protection** with real-time tracking - en **Comprehensive AutoMod** with multiple modules - en **Staff Management** with activity tracking - en **Professional Embeds** and UI design - en **Database Persistence** for all features - en **Logging Systems** for all major actions - en **Configurable Settings** per server ## Required Bot Permissions Minimum permissions integer: `8` (Administrator) or individual permissions: **Text Permissions:** - View Channels - Send Messages - Send Messages in Threads - Manage Messages - Embed Links - Attach Files - Read Message History - Mention Everyone - Add Reactions - Use External Emojis **Voice Permissions:** - Connect - Speak - Use Voice Activity ** Management Permissions:** - Manage Channels - Manage Roles - Manage Webhooks - Ban Members - Kick Members - Timeout Members - View Audit Log ## Project Structure ``` src/ ├── commands/ │ ├── antinuke/ # Anti-nuke protection commands │ ├── automod/ # Auto-moderation commands │ ├── giveaway/ # Giveaway commands │ ├── minecraft/ # Minecraft server status │ ├── moderation/ # Moderation commands │ ├── music/ # Music commands │ ├── staff/ # Staff management commands │ ├── ticket/ # Ticket system commands │ ├── utility/ # Utility commands │ └── verification/ # Verification commands ├── events/ # Discord event handlers │ ├── channelCreate.js # Anti-nuke channel tracking │ ├── channelDelete.js # Anti-nuke channel tracking │ ├── guildBanAdd.js # Anti-nuke ban tracking │ ├── guildMemberAdd.js # Welcome & verification │ ├── guildMemberRemove.js # Anti-nuke kick tracking │ ├── interactionCreate.js # Command & button handling │ ├── messageCreate.js # AutoMod & staff tracking │ ├── ready.js # Bot initialization │ ├── roleCreate.js # Anti-nuke role tracking │ ├── roleDelete.js # Anti-nuke role tracking │ ├── voiceStateUpdate.js # Music auto-disconnect │ └── webhookUpdate.js # Anti-nuke webhook tracking ├── handlers/ │ ├── commandHandler.js # Load and register commands │ └── eventHandler.js # Load event listeners ├── models/ # MongoDB schemas │ ├── AntiNuke.js # Anti-nuke settings │ ├── AutoMod.js # AutoMod settings │ ├── Giveaway.js # Giveaway data │ ├── MinecraftServer.js # MC server tracking │ ├── Settings.js # Guild settings │ ├── StaffApplication.js # Staff applications │ ├── StaffMember.js # Staff activity data │ ├── StaffReport.js # Staff reports │ ├── StaffSettings.js # Staff system settings │ ├── Ticket.js # Ticket data │ └── Verification.js # Verification settings ├── utils/ # Utility functions │ ├── antiNukeManager.js # Anti-nuke logic │ ├── autoModManager.js # AutoMod logic │ ├── giveawayManager.js # Giveaway automation │ ├── logger.js # Console logging │ ├── musicPlayer.js # Music queue & playback │ ├── staffTracker.js # Staff activity tracking │ └── ticketManager.js # Ticket management ├── config.js # Bot configuration └── index.js # Main entry point ``` ## Commands ### en Music Commands - `/play ` - Play a song from YouTube - `/pause` - Pause the current song - `/resume` - Resume playback - `/skip` - Skip the current song - `/stop` - Stop playback and clear queue - `/queue` - View the music queue ### en Moderation Commands - `/ban [reason]` - Ban a member - `/kick [reason]` - Kick a member - `/timeout [reason]` - Timeout a member - `/unban ` - Unban a user - `/clear ` - Delete messages (1-100) ### en AutoMod Commands - `/automod-setup anti-spam` - Configure anti-spam - `/automod-setup anti-link` - Configure anti-link - `/automod-setup anti-invite` - Configure anti-invite - `/automod-setup anti-caps` - Configure anti-capitalization - `/automod-setup anti-mention` - Configure anti-mass mention - `/automod-setup bad-words` - Configure bad word filter - `/automod-setup log-channel` - Set automod log channel - `/automod-setup bypass-role` - Add bypass role - `/automod-setup view` - View current settings ### en Anti-Nuke Commands - `/antinuke-setup enable` - Enable anti-nuke - `/antinuke-setup disable` - Disable anti-nuke - `/antinuke-setup whitelist ` - Whitelist a user - `/antinuke-setup unwhitelist ` - Remove from whitelist - `/antinuke-setup log-channel` - Set log channel - `/antinuke-setup punishment` - Set punishment action - `/antinuke-setup limits` - Configure action limits - `/antinuke-setup view` - View current settings ### en Giveaway Commands - `/giveaway-create [channel]` - Create a giveaway - `/giveaway-end ` - End a giveaway early - `/giveaway-reroll ` - Reroll a winner ### en Ticket Commands - `/ticket-setup [support-role] [log-channel]` - Setup ticket system - `/ticket-panel [channel]` - Create ticket panel with categories - `/ticket-claim` - Claim or unclaim a ticket - `/ticket-add ` - Add user to ticket - `/ticket-remove ` - Remove user from ticket - `/ticket-close` - Close current ticket with transcript ### en Staff Commands - `/staff-setup roles ` - Add staff role - `/staff-setup bypass ` - Set bypass role - `/staff-setup logs ` - Set log channel - `/staff-setup applications ` - Set application channel - `/staff-setup inactivity ` - Configure inactivity - `/staff-setup view` - View settings - `/staff-apply` - Apply for staff position - `/staff-activity view [staff]` - View staff activity - `/staff-activity leaderboard` - View activity leaderboard - `/staff-activity inactive` - View inactive staff - `/staff-leave ` - Request leave - `/staff-leave-approve ` - Approve/deny leave - `/staff-report ` - Report a staff member ### en Verification Commands - `/verification-setup [message]` - Setup verification ### en Minecraft Commands - `/mcstatus [port]` - Check Minecraft server status ### en Utility Commands - `/setprefix ` - Change bot prefix (Admin only) - `/help` - Display all commands - `/ping` - Check bot latency - `/uptime` - Check bot uptime - `/serverinfo` - Display server information - `/userinfo [user]` - Display user information ## Hosting ### VPS Hosting (Recommended) **Using PM2 (Process Manager):** ```bash # Install PM2 globally npm install -g pm2 # Start bot with PM2 pm2 start src/index.js --name astralbot # Save PM2 configuration pm2 save # Setup auto-start on reboot pm2 startup # View logs pm2 logs astralbot # Restart bot pm2 restart astralbot # Stop bot pm2 stop astralbot ``` **System Requirements:** - 1GB+ RAM - 1 CPU Core - 10GB+ Storage - Ubuntu 20.04+ / Debian 10+ recommended ### Cloud Platforms **Heroku:** 1. Create `Procfile`: ``` worker: node src/index.js ``` 2. Add MongoDB Atlas connection string 3. Deploy via Git **Railway.app:** 1. Connect GitHub repository 2. Add environment variables 3. Auto-deploys on push **DigitalOcean / AWS / Azure:** - Create a droplet/instance - Install Node.js v20+ - Install MongoDB or use Atlas - Install FFmpeg - Clone repository and run ### Keep Bot Online 24/7 **Option 1: PM2 (VPS)** ```bash pm2 start src/index.js --name astralbot pm2 startup pm2 save ``` **Option 2: systemd (Linux)** Create `/etc/systemd/system/astralbot.service`: ```ini [Unit] Description=AstralBot Discord Bot After=network.target [Service] Type=simple User=youruser WorkingDirectory=/path/to/astralbot ExecStart=/usr/bin/node src/index.js Restart=always RestartSec=10 [Install] WantedBy=multi-user.target ``` Then: ```bash sudo systemctl enable astralbot sudo systemctl start astralbot sudo systemctl status astralbot ``` ## Troubleshooting ### Common Issues **Commands not appearing:** 1. Verify `CLIENT_ID` in `.env` matches your bot's Application ID 2. Ensure bot has `applications.commands` scope 3. Wait 1-5 minutes for commands to sync 4. Try restarting the bot 5. In Discord, right-click server icon > Server Settings > Integrations > Check bot permissions **Bot not responding:** 1. Check if bot is online (green status) 2. Verify bot has proper permissions in channels 3. Check console for error messages 4. Ensure Message Content Intent is enabled 5. Verify MongoDB connection **Music not playing:** 1. Install FFmpeg: `sudo apt install ffmpeg` (Linux) or download for Windows 2. Ensure bot has Connect and Speak permissions 3. Check if voice channel is full 4. Verify `play-dl` is installed: `npm install play-dl` 5. Some videos may be age-restricted or unavailable **MongoDB connection issues:** 1. Verify MongoDB is running: `sudo systemctl status mongod` 2. Check `MONGODB_URI` format in `.env` 3. For Atlas: Whitelist your IP address in Atlas dashboard 4. Test connection: `mongosh "your_mongodb_uri"` **Permission errors:** 1. Ensure bot role is above roles it needs to manage 2. Give bot Administrator permission (or specific required permissions) 3. Check channel-specific permission overrides **AutoMod not working:** 1. Run `/automod-setup view` to check configuration 2. Ensure modules are enabled 3. Check if user has bypass role 4. Verify log channel is set **Ticket system not working:** 1. Run `/ticket-setup` first 2. Ensure category exists and bot can access it 3. Check bot has Manage Channels permission 4. Verify support role is configured ### Error Messages **"Missing Access"** - Bot doesn't have permission to view/access that channel - Solution: Give bot View Channel permission **"Missing Permissions"** - Bot lacks specific permission for action - Solution: Grant required permission or Administrator **"Unknown Interaction"** - Interaction took too long to respond (3 seconds) - Solution: Use `interaction.deferReply()` for slow operations **"Invalid Form Body"** - Command options are invalid - Solution: Check command parameters ### Getting Help If you need help: 1. Check console logs for error details 2. Enable debug logging in config 3. Verify all prerequisites are installed 4. Check Discord.js version: `npm list discord.js` 5. Ensure Node.js version is 20+: `node --version` ### Performance Tips 1. **Use MongoDB Atlas** for cloud hosting (free tier available) 2. **Enable PM2 clustering** for high-traffic bots 3. **Set up proper logging** to catch errors early 4. **Monitor RAM usage** - restart if memory leak occurs 5. **Keep dependencies updated**: `npm update` ### Debugging Enable debug mode in `src/index.js`: ```javascript client.on('debug', console.log); ``` View real-time logs with PM2: ```bash pm2 logs astralbot --lines 100 ``` ## Frequently Asked Questions (FAQ) **Q: Is this bot ready for production use?** A: Yes! All features are fully tested and production-ready. **Q: Can I customize the bot?** A: Absolutely! The code is open-source and well-documented. Feel free to modify anything. **Q: Do I need coding knowledge to use this?** A: Basic knowledge helps, but following the installation guide should be enough to get started. **Q: Can I use this bot for commercial purposes?** A: Yes, this bot is under MIT License. You can use it commercially. **Q: How many servers can this bot handle?** A: With proper hosting, it can handle hundreds of servers. For 1000+ servers, consider clustering. **Q: Is MongoDB required?** A: Yes, MongoDB stores all settings, tickets, giveaways, and user data. **Q: Can I self-host this bot?** A: Yes! That's the primary way to use it. Follow the installation guide. **Q: Does this bot collect user data?** A: It only stores data needed for functionality (tickets, staff activity, etc.). No personal data is sold or shared. **Q: How do I update the bot?** A: Pull latest changes with `git pull`, run `npm install`, then restart the bot. **Q: Can I request features?** A: Feel free to fork and add features yourself, or submit feature requests as issues. ## Contributing Contributions are welcome! To contribute: 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/AmazingFeature`) 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) 4. Push to the branch (`git push origin feature/AmazingFeature`) 5. Open a Pull Request ### Code Style - Use ES6+ features - Follow existing code structure - Comment complex logic - Test thoroughly before submitting ## Support If you encounter issues: 1. Check the Troubleshooting section 2. Search existing issues on GitHub 3. Create a new issue with: - Error messages - Steps to reproduce - Environment details (Node version, OS, etc.) ## Credits Built with: - [discord.js](https://discord.js.org/) - Discord API library - [MongoDB](https://www.mongodb.com/) - Database - [play-dl](https://github.com/play-dl/play-dl) - Music playback - [FFmpeg](https://ffmpeg.org/) - Audio processing ## Changelog ### v1.0.0 (Latest) - en Initial release - en Full ticket system with categories - en comprehensive AutoMod - en Anti-nuke protection - en Staff management system - en Music system - en Giveaway system - en Verification system - en Moderation commands - en Minecraft status checker ## License MIT License - see [LICENSE](LICENSE) file for details. **What this means:** - en You can use this bot commercially - en You can modify the code - en You can distribute modified versions - en You must include the original license - en No warranty is provided --- **Note:** This bot is not affiliated with Discord Inc. Discord is a trademark of Discord Inc.