{"id":29647533,"url":"https://github.com/jakedev796/counting-bot","last_synced_at":"2026-05-20T05:01:25.207Z","repository":{"id":305180413,"uuid":"1022175160","full_name":"jakedev796/counting-bot","owner":"jakedev796","description":"a simple discord counting bot written in python","archived":false,"fork":false,"pushed_at":"2025-07-18T16:16:02.000Z","size":1480,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-18T19:51:34.458Z","etag":null,"topics":["bot","counter","counting","counting-bot","discord","discord-bot","discord-py","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jakedev796.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-07-18T15:25:08.000Z","updated_at":"2025-07-18T16:16:06.000Z","dependencies_parsed_at":"2025-07-18T19:51:40.838Z","dependency_job_id":"9c9c0916-82c5-4c2d-9b51-81230d4a25fc","html_url":"https://github.com/jakedev796/counting-bot","commit_stats":null,"previous_names":["jakedev796/counting-bot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jakedev796/counting-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakedev796%2Fcounting-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakedev796%2Fcounting-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakedev796%2Fcounting-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakedev796%2Fcounting-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jakedev796","download_url":"https://codeload.github.com/jakedev796/counting-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakedev796%2Fcounting-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278748811,"owners_count":26038996,"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-07T02:00:06.786Z","response_time":59,"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":["bot","counter","counting","counting-bot","discord","discord-bot","discord-py","python"],"created_at":"2025-07-22T03:37:42.804Z","updated_at":"2025-10-07T09:24:13.519Z","avatar_url":"https://github.com/jakedev796.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"countingBotIcon.png\" alt=\"Counting Bot Icon\" width=\"200\" height=\"200\"\u003e\n  \n  # Discord Counting Bot\n  \n  A Discord bot built with `discord.py` that enables a counting game in a specified channel. Users count upwards from 1, one number per message. The bot validates the sequence, reacts to correct/incorrect entries, and maintains per-server and global leaderboards.\n  \n  [![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)\n  [![Discord.py](https://img.shields.io/badge/discord.py-2.3+-blue.svg)](https://discordpy.readthedocs.io/)\n  [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n  [![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)\n\u003c/div\u003e\n\n---\n\n## 📋 Table of Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Bot Setup](#bot-setup)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [Development](#development)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [Support](#support)\n\n## ✨ Features\n\n- 🎯 **Counting Game**: Users count upwards from 1 in a designated channel\n- ✅ **Smart Validation**: Bot validates correct sequence and prevents consecutive counting by same user\n- 🎨 **Custom Reactions**: Support for custom emotes or default ✅/❌ reactions with automatic fallback\n- ⚙️ **Admin Commands**: Set counting channel and reset count with permission checks\n- 📊 **Leaderboards**: Per-server stats with global rankings\n- 🌐 **Multi-Server Support**: Maintains separate counts for each server\n- 💾 **Local Storage**: All data stored in SQLite database with async support\n- 🔄 **Flexible Input**: Accepts numbers anywhere in messages (e.g., \"5 this is a test\")\n- 📈 **Live Presence**: Custom status showing total count across all servers\n- 🐳 **Docker Ready**: Easy deployment with Docker and Docker Compose\n- ⏰ **Grace Period System**: 5-second countdown when mistakes are made, allowing others to save the count\n- 🚫 **Same User Protection**: Automatically ignores consecutive messages from the same user\n- 💥 **Auto Reset**: Count resets to 0 if no one saves it during grace period\n\n## 📋 Requirements\n\n- **Python** 3.10+\n- **Discord Bot Token** (from Discord Developer Portal)\n- **Required Bot Permissions**:\n  - Send Messages\n  - Add Reactions\n  - Use Slash Commands\n  - Read Message History\n\n## 🤖 Public Bot\n\n**Ready to use immediately!** Invite the public bot to your server:\n\n[![Invite Bot](https://img.shields.io/badge/Invite%20Bot-Discord-blue.svg)](https://discord.com/oauth2/authorize?client_id=1395776535629266985\u0026permissions=2147551296\u0026integration_type=0\u0026scope=bot)\n\n**Direct Link:** https://discord.com/oauth2/authorize?client_id=1395776535629266985\u0026permissions=8\u0026integration_type=0\u0026scope=bot+applications.commands\n\n## 🚀 Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/jakedev796/counting-bot.git\ncd counting-bot\n\n# Set up environment\ncp .env.example .env\n# Edit .env with your Discord bot token\n\n# Run with Docker (recommended)\ndocker-compose up -d\n\n# Or run locally\npip install -r requirements.txt\npython main.py\n```\n\n## 📦 Installation\n\n### Local Development\n\n2. **Install dependencies**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Set up environment variables**\n   ```bash\n   cp .env.example .env\n   ```\n   \n   Edit `.env` and add your Discord bot token:\n   ```\n   DISCORD_TOKEN=your_discord_bot_token_here\n   DATABASE_PATH=./counting_bot.db\n   ```\n\n4. **Run the bot**\n   ```bash\n   python main.py\n   ```\n\n### Docker Deployment\n\n1. **Set up environment variables**\n   ```bash\n   cp .env.example .env\n   ```\n   \n   Edit `.env` with your Discord bot token.\n\n2. **Create data directory**\n   ```bash\n   mkdir data\n   ```\n\n3. **Build and run with Docker Compose**\n   ```bash\n   docker-compose up -d\n   ```\n\n## Bot Setup\n\n1. **Create a Discord Application**\n   - Go to [Discord Developer Portal](https://discord.com/developers/applications)\n   - Create a new application\n   - Go to the \"Bot\" section and create a bot\n   - Copy the bot token to your `.env` file\n\n2. **Invite the Bot to Your Server**\n   - Go to OAuth2 \u003e URL Generator\n   - Select scopes: `bot` and `applications.commands`\n   - Select permissions: `Send Messages`, `Add Reactions`, `Use Slash Commands`\n   - Use the generated URL to invite the bot\n\n3. **Set Required Intents**\n   - In the Bot section, enable:\n     - Message Content Intent\n     - Server Members Intent\n\n## Usage\n\n### Admin Commands\n\n- `/setcountingchannel [channel]` - Set the counting channel for the server\n  - Requires \"Manage Server\" permission\n  - Only one channel per server can be set\n\n- `/resetcount [reason]` - Reset the count for the server\n  - Requires \"Manage Server\" permission\n  - Clears all user stats for the server\n  - Optional reason parameter\n\n### User Commands\n\n- `/leaderboard` - View server statistics with global rankings\n  - Shows Current Number, High Score, and Total Score\n  - Displays global rank for each stat\n  - Available to all users\n\n### Counting Game Rules\n\n1. **Valid Messages**: Only integer messages are processed\n2. **Sequence**: Must count in correct order (1, 2, 3, ...)\n3. **User Alternation**: No user can count twice in a row (automatically ignored)\n4. **Reactions**: \n   - ✅ for correct counts\n   - ❌ for incorrect counts or rule violations\n5. **Rapid Counting**: Allowed as long as users alternate\n6. **Grace Period**: When someone makes a mistake, others have 5 seconds to save the count\n7. **Auto Reset**: If no one saves the count in time, it resets to 0\n\n### 🎯 Grace Period System\n\nThe bot features an exciting **5-second grace period** when mistakes are made:\n\n- **🚨 Mistake Detection**: When someone types the wrong number, a countdown starts\n- **⏰ Live Countdown**: An embed updates every second showing remaining time\n- **💪 Team Save**: Other users can type the correct number to save the count\n- **🚫 Mistake Maker Lock**: The person who made the mistake cannot save it\n- **🎉 Success**: If saved, the count continues with a celebration message\n- **💥 Reset**: If time runs out, the count resets to 0 and everyone starts over\n\nThis creates a thrilling team-based experience where quick thinking and cooperation can save the day!\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `DISCORD_TOKEN` | Your Discord bot token | Required |\n| `DATABASE_PATH` | Path to SQLite database | `./counting_bot.db` |\n| `SUCCESS_EMOTE` | Custom emote for correct counts (with fallback) | `✅` |\n| `ERROR_EMOTE` | Custom emote for incorrect counts (with fallback) | `❌` |\n\n### Database\n\nThe bot uses SQLite for data storage with the following tables:\n\n- **guild_settings**: Server configuration and stats\n- **user_stats**: Individual user statistics per server\n\n## Development\n\n### Project Structure\n\n```\ncounting-bot/\n├── bot/\n│   ├── __init__.py\n│   ├── main.py              # Main bot class\n│   ├── commands/\n│   │   ├── __init__.py\n│   │   ├── admin.py         # Admin slash commands\n│   │   └── leaderboard.py   # Leaderboard command\n│   ├── cogs/\n│   │   ├── __init__.py\n│   │   └── counting.py      # Counting game logic\n│   ├── db/\n│   │   ├── __init__.py\n│   │   └── database.py      # Database operations\n│   └── utils/\n│       ├── __init__.py\n│       └── helpers.py       # Utility functions\n├── main.py                  # Entry point\n├── requirements.txt         # Python dependencies\n├── Dockerfile              # Docker configuration\n├── docker-compose.yml      # Docker Compose setup\n├── .env.example            # Environment template\n└── README.md               # This file\n```\n\n### Adding New Features\n\n1. **Commands**: Add new slash commands in `bot/commands/`\n2. **Cogs**: Add new functionality in `bot/cogs/`\n3. **Database**: Extend `bot/db/database.py` for new data needs\n4. **Utilities**: Add helper functions in `bot/utils/helpers.py`\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Bot not responding to commands**\n   - Check if bot has required permissions\n   - Verify slash commands are synced\n   - Check bot token is correct\n\n2. **Database errors**\n   - Ensure write permissions for database directory\n   - Check database path in environment variables\n\n3. **Counting not working**\n   - Verify counting channel is set with `/setcountingchannel`\n   - Check bot has permission to add reactions\n\n### Logs\n\nThe bot logs all activities to console. Check logs for:\n- Command usage\n- Counting events\n- Error messages\n- Database operations\n\n## 🤝 Contributing\n\nAlways welcoming contributions! Here's how you can help:\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\n5. **Open** a Pull Request\n\n### 🐛 Bug Reports\n\nFound a bug? Please [open an issue](https://github.com/jakedev796/counting-bot/issues) with:\n- Description of the bug\n- Steps to reproduce\n- Expected vs actual behavior\n- Bot logs (if applicable)\n\n### 💡 Feature Requests\n\nHave an idea? I'd love to hear it! [Open an issue](https://github.com/jakedev796/counting-bot/issues) with your suggestion.\n\n## 🆘 Support\n\nNeed help? Here are your options:\n\n### 📖 Self-Help\n1. Check the [troubleshooting section](#troubleshooting) above\n2. Review the bot logs for error messages\n3. Check the [Discord.py documentation](https://discordpy.readthedocs.io/)\n\n### 🐛 Get Help\n- **GitHub Issues**: [Open an issue](https://github.com/jakedev796/counting-bot/issues) for bugs or feature requests\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003eMade with ❤️ by the Jake\u003c/p\u003e\n  \u003cp\u003eIf this project helped you, consider giving it a ⭐!\u003c/p\u003e\n\u003c/div\u003e \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakedev796%2Fcounting-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjakedev796%2Fcounting-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakedev796%2Fcounting-bot/lists"}