PetBot - IRC Pokemon-Style Pet Game Bot

A feature-rich IRC bot that brings Pokemon-style pet collecting and battling to your IRC channel! Players can catch pets, explore locations, battle wild creatures, earn achievements, and more.

🎮 Features

Core Gameplay

• Pet Collection: Catch and collect different species of pets
• Exploration: Travel between various themed locations
• Battle System: Engage in turn-based battles with wild pets
• Team Management: Activate/deactivate pets, swap team members
• Achievement System: Unlock new areas by completing challenges

Advanced Systems

• Dynamic Weather: Real-time weather system affecting spawn rates
• Web Interface: Modern web dashboard for player stats and pet collections
• Location-Based Spawns: Different pets spawn in different locations
• Level Progression: Pets gain experience and level up
• Type Effectiveness: Strategic battle system with type advantages

Technical Features

• Modular Architecture: Clean, extensible codebase
• Async Database: SQLite with async operations
• Background Tasks: Automated weather updates
• PM Flood Prevention: Web-based responses for large data sets
• Persistent Data: Player progress survives bot restarts

🚀 Quick Start

Prerequisites

• Python 3.8+
• SQLite3
• Network access for IRC and web server

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/petbot.git
   cd petbot
   

2. Install dependencies:

   pip install aiosqlite
   

3. Configure the bot:

   cp config/settings.example.json config/settings.json
   # Edit config/settings.json with your IRC details
   

4. Run the bot:

   python3 run_bot_debug.py
   

📋 Commands

Player Commands

• !start - Begin your pet collecting journey
• !explore - Search for wild pets in your current location
• !catch <pet> - Attempt to catch a wild pet
• !team - View your active team
• !pets - View your complete collection (web link)
• !travel <location> - Move to a different location
• !weather - Check current weather effects
• !achievements - View your progress and unlocked achievements

Battle Commands

• !battle - Start a battle with a wild pet
• !attack <move> - Use a move in battle
• !flee - Attempt to escape from battle
• !moves - View your active pet's moves

Pet Management

• !activate <pet> - Activate a pet for battle
• !deactivate <pet> - Move a pet to storage
• !swap <pet1> <pet2> - Swap two pets' active status

🌍 Locations

Available Areas

• Starter Town: Peaceful starting area (Fire/Water/Grass pets)
• Whispering Woods: Ancient forest (Grass/Nature pets)
• Electric Canyon: Charged valley (Electric/Rock pets)
• Crystal Caves: Underground caverns (Rock/Crystal pets)
• Frozen Tundra: Icy wasteland (Ice/Water pets)
• Dragon's Peak: Ultimate challenge (Fire/Rock/Ice pets)

Unlocking Locations

Locations are unlocked by completing achievements:

• Nature Explorer: Catch 3 different Grass-type pets → Whispering Woods
• Spark Collector: Catch 2 different Electric-type pets → Electric Canyon
• Rock Hound: Catch 3 different Rock-type pets → Crystal Caves
• Ice Breaker: Catch 5 different Water/Ice-type pets → Frozen Tundra
• Dragon Tamer: Catch 15 pets total + 3 Fire-types → Dragon's Peak

🌤️ Weather System

Weather Types & Effects

• Sunny: 1.5x Fire/Grass spawns (1-2 hours)
• Rainy: 2.0x Water spawns (45-90 minutes)
• Thunderstorm: 2.0x Electric spawns (30-60 minutes)
• Blizzard: 1.7x Ice/Water spawns (1-2 hours)
• Earthquake: 1.8x Rock spawns (30-90 minutes)
• Calm: Normal spawns (1.5-3 hours)

Background System

• Weather updates automatically every 5 minutes
• Dynamic durations from 30 minutes to 3 hours
• Location-specific weather patterns
• Real-time spawn rate modifications

🌐 Web Interface

Access the web dashboard at http://localhost:8080/:

• Player Profiles: Complete stats and pet collections
• Leaderboard: Top players by level and achievements
• Locations Guide: All areas with spawn information
• Help System: Complete command reference

🔧 Architecture

Core Components

• Database Layer: Async SQLite with comprehensive schema
• Game Engine: Core logic for pets, battles, weather
• Module System: Pluggable command handlers
• Web Server: Built-in HTTP server for dashboard
• Battle Engine: Turn-based combat system

Key Files

• src/database.py - Database operations and schema
• src/game_engine.py - Core game logic and weather system
• src/battle_engine.py - Combat mechanics
• modules/ - Command handler modules
• webserver.py - Web interface server
• config/ - Configuration files

🐛 Recent Updates

Weather System Enhancement

• ✅ Added background task for automatic weather updates
• ✅ Changed weather durations from 2-6 hours to 30min-3hours
• ✅ Implemented continuous weather coverage
• ✅ Added graceful shutdown handling

Bug Fixes

• ✅ Fixed database persistence on bot restart
• ✅ Resolved individual player pages showing 'not found'
• ✅ Corrected achievement count displays
• ✅ Added specific travel requirement messages
• ✅ Fixed locations page display
• ✅ Implemented colored battle moves by type

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Add tests if applicable
5. Commit with descriptive messages
6. Push and create a pull request

📝 License

This project is open source. Feel free to use, modify, and distribute.

🎯 Roadmap

• PvP battles between players
• Pet evolution system
• Trading between players
• Seasonal events
• More pet types and locations
• Mobile-responsive web interface

🐾 Support

For questions, bug reports, or feature requests, please open an issue on GitHub.

---

Built with ❤️ for IRC communities who love Pokemon-style games!