Skip to content
BranchesTags

Repository files navigation

🎮 PokeGrind

Automated Pokemon Hunting & Fishing Bot for Discord

Python Discord.py-self License Status

An intelligent, multi-account automation bot for PokeMeow Discord bot with advanced CAPTCHA solving, smart ball selection, and comprehensive activity tracking.

Features • Installation • Configuration • Usage

📋 Table of Contents

🌟 Overview

PokeGrind is a sophisticated automation bot designed to interact with the PokeMeow Discord bot. It automates Pokemon hunting, fishing, item management, and ball inventory while implementing intelligent strategies to maximize efficiency and minimize detection.

Why PokeGrind?

  • 🤖 Fully Automated: Runs 24/7 with minimal intervention
  • 🧠 Intelligent Ball Selection: Automatically chooses the optimal Pokeball based on rarity
  • 🔍 Advanced CAPTCHA Solver: YOLOv8-powered digit detection with high accuracy
  • 📊 Comprehensive Tracking: Real-time statistics and webhook notifications
  • 🎣 Multi-Activity Support: Handles both hunting and fishing simultaneously
  • 👥 Multi-Account Management: Run multiple accounts concurrently
  • ⚡ Resource Management: Auto-restocks balls, uses items, and manages inventory
  • 🎯 Smart Exception Handling: Custom ball configurations for specific Pokemon

✨ Features

🎯 Core Features

  • Automated Pokemon Hunting

    • Continuous /pokemon command execution
    • Intelligent ball selection based on Pokemon rarity
    • Custom ball assignments for specific Pokemon
    • Held item detection and special ball handling
    • Daily hunt limit detection with automatic midnight reset scheduling

  • 🎣 Automated Fishing

    • Parallel fishing and hunting operations
    • Fish-specific rarity detection
    • Separate ball configuration for fishing
    • Integrated with fish database for rarity lookup

  • 🧩 Advanced CAPTCHA Solving

    • YOLOv8 Nano model for digit detection
    • Image preprocessing and enhancement
    • Automatic CAPTCHA response submission
    • High success rate with confidence-based validation

  • 📦 Item Management

    • Automatic ball restocking when thresholds are met
    • Grazz Berry usage for held items
    • Repel activation when available
    • Egg hatching automation
    • Lootbox opening
    • Startup command randomization

  • 📊 Statistics & Tracking

    • Real-time catch tracking by rarity
    • Session statistics (catches, coins, tokens)
    • Webhook notifications for rare catches
    • Market view triggers for valuable Pokemon
    • Console logging with color-coded severity levels

🛡️ Safety Features

  • Rate Limiting: Respects Discord API limits
  • Random Delays: Humanized timing between actions
  • Error Recovery: Automatic reconnection on failures
  • Daily Limit Handling: Smart scheduling for hunt limit resets
  • Activity Coordination: Prevents conflicting simultaneous actions

🎨 Customization

  • Configurable Ball Selection: Define ball usage per rarity tier
  • Pokemon Exceptions: Override ball selection for specific Pokemon
  • Fish Exceptions: Custom handling for rare fish
  • Per-Account Settings: Individual configurations for multiple accounts
  • Webhook Integration: Custom Discord webhook for notifications

📋 Prerequisites

Before installing PokeGrind, ensure you have:

  • Python 3.8+ installed on your system
  • Discord User Token (for selfbot operation)
  • PokeMeow Bot in your Discord server
  • Channel/Server IDs where PokeMeow is active
  • YOLOv8 Model File (best.pt) for CAPTCHA solving

Required Python Packages

All dependencies are listed in requirements.txt:

  • discord.py-self>=2.1.0b0 - Discord selfbot library
  • aiohttp>=3.8.0 - Async HTTP client
  • Pillow>=9.0.0 - Image processing for CAPTCHA
  • pytz>=2022.1 - Timezone handling
  • pygame>=2.1.0 - Audio notifications
  • ultralytics>=8.0.0 - YOLOv8 for CAPTCHA solving

🚀 Installation

Step 1: Clone the Repository

git clone https://github.com/dragonblz/PokeGrind.git
cd PokeGrind

Step 2: Install Dependencies

pip install -r requirements.txt

Step 3: Add CAPTCHA Model

Place your trained YOLOv8 model file (best.pt) in the root directory of the project.

Step 4: Configure the Bot

Edit config.json with your account details and preferences (see Configuration section below).

⚙️ Configuration

The bot is configured through config.json. Here's a breakdown of the configuration structure:

Ball Configuration

Define which Pokeball to use for each rarity tier:

{
  "Balls": {
    "Common": "pb",           // Pokeball
    "Uncommon": "pb",         // Pokeball
    "Rare": "gb",             // Greatball
    "Super Rare": "ub",       // Ultraball
    "Legendary": "mb",        // Masterball
    "Shiny": "mb",            // Masterball
    "Shiny Event": "mb",      // Masterball
    "Shiny Full-odds": "prb"  // Premier Ball
  }
}

Available Ball Types:

  • pb - Pokeball
  • gb - Greatball
  • ub - Ultraball
  • mb - Masterball
  • db - Diveball (fishing)
  • prb - Premier Ball

Fish Ball Configuration

Separate ball configuration for fishing:

{
  "FishBalls": {
    "Common": "pb",
    "Uncommon": "gb",
    "Rare": "ub",
    "Super Rare": "ub",
    "Legendary": "db",
    "Shiny": "mb",
    "Golden": "mb"
  }
}

Pokemon Exceptions

Override ball selection for specific Pokemon:

{
  "PokemonExceptions": {
    "Yamper": "ub",
    "Riolu": "ub",
    "Groudon": "prb",
    "Celebi": "prb"
  }
}

Account Configuration

Configure one or more accounts:

{
  "Accounts": [
    {
      "name": "MyAccount",
      "enabled": true,
      "token": "YOUR_DISCORD_TOKEN_HERE",
      "channelid": "CHANNEL_ID_HERE",
      "serverid": "SERVER_ID_HERE",
      "FishingEnabled": false,
      "BallRestock": {
        "masterball": {"threshold": 0, "amount": 1},
        "pokeball": {"threshold": 10, "amount": 20},
        "greatball": {"threshold": 1, "amount": 5},
        "ultraball": {"threshold": 1, "amount": 1},
        "premierball": {"threshold": 0, "amount": 1}
      }
    }
  ]
}

Account Parameters:

  • name: Display name for logging
  • enabled: Set to false to disable this account
  • token: Your Discord user token
  • channelid: Channel ID where PokeMeow is active
  • serverid: Server (guild) ID
  • FishingEnabled: Enable/disable fishing for this account
  • BallRestock: Auto-restock settings (threshold = when to buy, amount = how many)

Webhook Configuration

Add a Discord webhook URL for notifications:

{
  "WebhookURL": "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL"
}

🎮 Usage

Starting the Bot

python main.py

The bot will:

  1. Load configuration from config.json
  2. Initialize all enabled accounts
  3. Connect to Discord
  4. Load cogs (hunting, fishing, items)
  5. Run startup checks
  6. Begin automated activities

Multi-Account Operation

PokeGrind supports running multiple accounts simultaneously. Each account:

  • Runs in its own async task
  • Has independent activity coordination
  • Maintains separate statistics
  • Can have different configurations

Stopping the Bot

Press Ctrl+C to gracefully shut down all accounts.

📁 Project Structure

PokeGrind/
├── main.py                 # Entry point and multi-account manager
├── config.json             # Configuration file (user-created)
├── requirements.txt        # Python dependencies
├── best.pt                 # YOLOv8 CAPTCHA model
├── fishes.json             # Fish rarity database
├── state.json              # Runtime state persistence
├── bell.mp3                # Audio notification
│
├── core/                   # Core functionality
│   ├── __init__.py
│   ├── config.py           # Configuration loader
│   └── logger.py           # Colored console logging
│
└── cogs/                   # Activity modules
    ├── __init__.py
    ├── base.py             # Base activity cog
    ├── hunting.py          # Pokemon hunting logic
    ├── fishing.py          # Pokemon fishing logic
    ├── items.py            # Item management
    ├── utils.py            # Utilities (ball matcher, coordinator)
    ├── tracker.py          # Statistics tracking
    └── captcha_solver.py   # YOLOv8 CAPTCHA solver

🔧 How It Works

Activity Coordination

The bot uses an ActivityCoordinator to manage multiple activities:

  1. Hunting - Executes /pokemon command
  2. Fishing - Executes /fish command (if enabled)
  3. Items - Manages repels, berries, eggs, and balls

Activities are coordinated to prevent conflicts and ensure smooth operation.

Ball Selection Algorithm

  1. Parse Pokemon message for name and rarity
  2. Check if Pokemon is in exceptions list → use exception ball
  3. Check if Pokemon has held item → use held item ball configuration
  4. Use standard ball configuration based on rarity
  5. Verify ball is in inventory
  6. Click appropriate ball button

CAPTCHA Solving Process

  1. Detect CAPTCHA message from PokeMeow
  2. Download CAPTCHA image
  3. Preprocess image (grayscale conversion, enhancement)
  4. Run YOLOv8 inference to detect digits
  5. Sort detected digits left-to-right
  6. Combine digits into answer
  7. Submit answer to CAPTCHA prompt

Daily Limit Handling

When the daily hunt limit is reached:

  1. Bot detects "daily limit" message
  2. Calculates time until midnight in America/New_York timezone + random offset (0-30 min)
  3. Schedules disconnection
  4. Waits for reset time
  5. Automatically reconnects and resumes hunting

🐛 Troubleshooting

Common Issues

Bot doesn't start:

  • Check that config.json exists and is valid JSON
  • Verify your Discord token is correct
  • Ensure best.pt model file is present

Commands not found:

  • Make sure PokeMeow bot has registered slash commands in your server
  • Try using PokeMeow commands manually first
  • Check channel and server IDs are correct

CAPTCHA solving fails:

  • Ensure best.pt model is properly trained
  • Check model confidence threshold in captcha_solver.py
  • Verify Pillow and ultralytics are installed correctly

Multiple accounts not working:

  • Each account needs a unique token
  • Verify all accounts have "enabled": true
  • Check logs for account-specific errors

Ball restock not working:

  • Ensure you have sufficient coins
  • Check ball restock thresholds and amounts
  • Verify /shop buy command is available

Debug Logging

The bot uses color-coded console logging:

  • 🟢 Green: Startup and success messages
  • 🔵 Blue: Info and general operations
  • 🟡 Yellow: Warnings
  • 🔴 Red: Errors
  • 🟣 Magenta: Hunt/fish actions
  • 🟠 Cyan: Item operations

🤝 Contributing

Contributions are welcome! Here's how you can help:

  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

Development Guidelines

  • Follow existing code style and conventions
  • Add comments for complex logic
  • Test thoroughly with multiple accounts
  • Update documentation for new features

⚠️ Disclaimer

IMPORTANT: READ CAREFULLY

This bot is for educational purposes only. Using selfbots violates Discord's Terms of Service and may result in account termination. The authors of this project:

  • Do NOT encourage violating Discord's ToS
  • Are NOT responsible for any account bans or penalties
  • Are NOT liable for any damages or consequences
  • Provide this software AS-IS without warranty

Use at your own risk. By using this bot, you acknowledge and accept all risks associated with automated Discord activity.

Ethical Considerations

  • Be respectful of Discord's platform and community
  • Don't spam or harass other users
  • Don't use this bot to gain unfair advantages in competitive scenarios
  • Consider the impact on server performance and other players

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • discord.py-self - For the selfbot library
  • Ultralytics - For the YOLOv8 framework
  • PokeMeow - For the Pokemon Discord bot
  • Contributors - For improvements and bug fixes

⭐ Star this repository if you find it useful!

Made with ❤️ for Pokemon enthusiasts

Report Bug • Request Feature

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages