{"id":31628372,"url":"https://github.com/codergautam/worldguessr-discord-bot","last_synced_at":"2026-07-16T16:33:51.846Z","repository":{"id":316251236,"uuid":"1062200061","full_name":"codergautam/worldguessr-discord-bot","owner":"codergautam","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-23T13:59:37.000Z","size":70,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-23T15:37:59.977Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codergautam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-23T00:19:19.000Z","updated_at":"2025-09-23T13:59:40.000Z","dependencies_parsed_at":"2025-09-23T15:38:04.725Z","dependency_job_id":null,"html_url":"https://github.com/codergautam/worldguessr-discord-bot","commit_stats":null,"previous_names":["codergautam/worldguessr-discord-bot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/codergautam/worldguessr-discord-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codergautam%2Fworldguessr-discord-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codergautam%2Fworldguessr-discord-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codergautam%2Fworldguessr-discord-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codergautam%2Fworldguessr-discord-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codergautam","download_url":"https://codeload.github.com/codergautam/worldguessr-discord-bot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codergautam%2Fworldguessr-discord-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278672782,"owners_count":26025975,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-06T20:24:05.945Z","updated_at":"2025-10-06T20:24:08.412Z","avatar_url":"https://github.com/codergautam.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WorldGuessr Discord Bot\n\nA comprehensive Discord bot featuring interactive quiz systems, player statistics, and WorldGuessr game integration. Built with Discord.js v14 and SQLite.\n\n## 🎯 Features\n\n### 🌍 Interactive Quiz System\n- **Country TLD Quiz** - Learn country top-level domains (.com, .uk, .de, etc.)\n- **Country Flag Quiz** - Identify countries by their flag emojis 🇺🇸🇬🇧🇯🇵\n- **Progressive Difficulty** - Starts hard, shows multiple choice after 5 wrong attempts\n- **Cross-platform** - Works with both slash commands (`/`) and message commands (`!`)\n- **Persistent Questions** - Questions remain until someone gets the correct answer\n\n### 📊 Statistics \u0026 Leaderboards\n- **Individual Stats** - Track your accuracy and progress per quiz category\n- **Overall Leaderboards** - See top players across all quiz types\n- **Category Leaderboards** - Compete in specific quiz categories\n- **Detailed Analytics** - View correct/incorrect answers, accuracy percentages, attempt counts\n\n### 🎮 WorldGuessr Integration\n- **Player Stats Lookup** - Check any WorldGuessr player's game statistics\n- **Beautiful Embeds** - Rich, formatted displays with proper styling\n\n### 🛠️ Modular Architecture\n- **Auto-detecting Commands** - Commands are automatically discovered and loaded\n- **Seamless Dual Interface** - Every command works with both `/command` and `!command`\n- **Generic Utilities** - Reusable components for easy development\n- **Clean Code Structure** - Well-organized, maintainable codebase\n\n## 📋 Commands\n\n### Quiz Commands\nAll quiz interactions happen by simply chatting in designated quiz channels - no commands needed!\n\n### Information Commands\n| Slash Command | Message Command | Description |\n|---------------|-----------------|-------------|\n| `/stats [user] [category]` | `!stats` | View quiz statistics for yourself or another user |\n| `/leaderboard [category] [limit]` | `!leaderboard` | View quiz leaderboards (overall, TLD, or flags) |\n| `/check \u003cusername\u003e` | `!check \u003cusername\u003e` | Look up WorldGuessr player statistics |\n| `/hello` | `!hello` | Test command to verify bot functionality |\n\n### Command Parameters\n- **category**: `tld` (Country TLD Quiz) or `flags` (Country Flag Quiz)\n- **limit**: Number of users to show on leaderboard (5-25, default: 10)\n- **user**: Mention another Discord user to check their stats\n\n## 🚀 Setup\n\n### Prerequisites\n- Node.js (v16 or higher)\n- Discord Bot Token\n- Discord Application ID\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd worldguessr-discord-bot\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Environment Configuration**\n   Create a `.env` file in the root directory:\n   ```env\n   DISCORD_TOKEN=your_discord_bot_token_here\n   CLIENT_ID=your_client_id_here\n   ```\n\n4. **Start the bot**\n   ```bash\n   npm start\n   ```\n\n## 🤖 Discord Bot Setup\n\n1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)\n2. Create a new application\n3. Navigate to the \"Bot\" section and create a bot\n4. Copy the bot token → add to `.env` as `DISCORD_TOKEN`\n5. Copy the Application ID → add to `.env` as `CLIENT_ID`\n6. In \"OAuth2\" section, generate invite link with scopes:\n   - `bot`\n   - `applications.commands`\n7. Add bot permissions:\n   - Send Messages\n   - Use Slash Commands\n   - Embed Links\n   - Read Message History\n   - Add Reactions\n8. Invite the bot to your Discord server\n\n## 🎯 Quiz Setup\n\n### Channel Configuration\nThe bot uses specific channel IDs for different quiz types:\n- **TLD Quiz Channel**: `1419838438349344829`\n- **Flags Quiz Channel**: `1420033591458398258`\n\nTo set up quiz channels in your server:\n1. Create dedicated channels for each quiz type\n2. Update the channel IDs in `quiz/quizManager.js` (lines 15-16)\n3. Update the database categories in `database/database.js` (lines 62-63)\n\n### How Quiz System Works\n1. **Automatic Questions** - Bot posts random questions when started\n2. **Community Answering** - Anyone can answer by typing in the quiz channel\n3. **Progressive Difficulty**:\n   - Initial: Hard mode (no options)\n   - After 5 wrong attempts: Multiple choice (A, B, C, D, E)\n4. **Answer Methods**:\n   - Type full country name: `\"United States\"`\n   - Type letter choice: `\"A\"` or `\"a\"`\n   - Alternative names accepted: `\"USA\"`, `\"America\"`, `\"US\"`\n5. **Immediate Feedback** - Bot reacts with ✅ or ❌ and shows correct answer\n\n## 🗃️ Database\n\nThe bot uses SQLite for data persistence:\n- **User Statistics** - Individual performance tracking per category\n- **Quiz Categories** - Configuration for different quiz types\n- **Database File** - `database/quiz_data.db` (auto-created, git-ignored)\n\n### Database Schema\n```sql\n-- User quiz performance\nuser_stats (user_id, category, correct, incorrect, total_attempts, last_attempt)\n\n-- Quiz category configuration\nquiz_categories (category, channel_id, enabled, auto_post, description)\n```\n\n## 🏗️ Architecture\n\n### File Structure\n```\nworldguessr-discord-bot/\n├── commands/                 # Command implementations\n│   ├── check.js             # WorldGuessr player lookup\n│   ├── hello.js             # Test command\n│   ├── leaderboard.js       # Quiz leaderboards\n│   └── stats.js             # User statistics\n├── database/                # Database layer\n│   └── database.js          # SQLite operations\n├── handlers/                # Core bot handlers\n│   └── commandHandler.js    # Command loading and routing\n├── quiz/                    # Quiz system\n│   └── quizManager.js       # Quiz logic and management\n├── utils/                   # Utility functions\n│   ├── commandHandler.js    # Unified command processing\n│   └── genericUtils.js      # Reusable helper functions\n├── country_flags.json       # Flag emoji mappings\n├── country_tlds.json        # TLD to country mappings\n└── index.js                 # Main bot entry point\n```\n\n### Adding New Commands\n\nThanks to the seamless command handler system, adding new commands is incredibly easy:\n\n```javascript\n// commands/newcommand.js\nconst { SlashCommandBuilder } = require('discord.js');\nconst CommandHandler = require('../utils/commandHandler');\n\n// Core logic - works for both slash and message commands\nasync function newCommandLogic({ param1, param2, isSlash }) {\n    // Your command logic here\n    const embed = new EmbedBuilder()\n        .setTitle('New Command')\n        .setDescription('Command response');\n\n    return { embed };\n}\n\n// Parameter configuration\nconst paramConfig = {\n    param1: { type: 'string', default: 'defaultValue' },\n    param2: { type: 'user', default: null }\n};\n\nmodule.exports = {\n    data: new SlashCommandBuilder()\n        .setName('newcommand')\n        .setDescription('Description of new command')\n        .addStringOption(option =\u003e\n            option.setName('param1').setDescription('Parameter description')),\n\n    async execute(interaction) {\n        const params = CommandHandler.extractSlashParams(interaction, paramConfig);\n        await CommandHandler.handleCommand(newCommandLogic, params);\n    },\n\n    async executeMessage(message, args) {\n        const params = CommandHandler.extractMessageParams(message, args, paramConfig);\n        await CommandHandler.handleCommand(newCommandLogic, params);\n    }\n};\n```\n\nThat's it! Your command automatically supports:\n- ✅ Slash commands (`/newcommand`)\n- ✅ Message commands (`!newcommand`)\n- ✅ Unified error handling\n- ✅ Consistent response formatting\n- ✅ Parameter extraction\n\n## 🧪 Development\n\n### Available Scripts\n```bash\nnpm start          # Start the bot\nnpm run dev        # Start the bot (development alias)\n```\n\n### Hot Reload\nIn development mode, send `SIGUSR2` to reload commands without restarting:\n```bash\nkill -SIGUSR2 \u003cprocess_id\u003e\n```\n\n### Git Workflow\nThe bot includes commit automation. When making changes:\n```bash\n# Changes are automatically committed with detailed messages\n# Including co-authorship attribution to Claude\n```\n\n## 📊 Usage Examples\n\n### Quiz Interaction\n```\nBot: 🌍 Country TLD Quiz\n     Which country uses the TLD: `.jp`?\n     Type the country name to answer!\n\nUser: Japan\nBot: ✅ Correct!\n     Japan uses `.jp`\n     🎉 Well done, Username!\n     Next question coming up...\n```\n\n### Stats Command\n```\n/stats user:@friend category:flags\n\n📊 Country Flags Quiz Stats\nStatistics for Friend\n\n✅ Correct Answers: 45\n❌ Incorrect Answers: 12\n📈 Accuracy: 78.9%\n🎯 Total Attempts: 57\n⏰ Last Attempt: 12/23/2024\n```\n\n### Leaderboard Command\n```\n/leaderboard category:overall limit:5\n\n🏆 Overall Quiz Leaderboard\nTop 5 players by correct answers\n\n🥇 TopPlayer\n   ✅ 156 correct • ❌ 23 wrong • 📈 87.2% accuracy\n\n🥈 SecondPlace\n   ✅ 134 correct • ❌ 31 wrong • 📈 81.2% accuracy\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes using the established architecture patterns\n4. Test with both slash and message commands\n5. Commit your changes: `git commit -m 'Add amazing feature'`\n6. Push to the branch: `git push origin feature/amazing-feature`\n7. Open a Pull Request\n\n## 📝 License\n\nISC License - see LICENSE file for details.\n\n## 🔗 Links\n\n- [Discord.js Documentation](https://discord.js.org/#/docs)\n- [Discord Developer Portal](https://discord.com/developers/applications)\n- [WorldGuessr Website](https://worldguessr.com)\n\n---\n\n**Built with ❤️ using Discord.js v14, SQLite, and modern JavaScript**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodergautam%2Fworldguessr-discord-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodergautam%2Fworldguessr-discord-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodergautam%2Fworldguessr-discord-bot/lists"}