Petbot/README.md

# 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:
   ```bash
   git clone https://github.com/yourusername/petbot.git
   cd petbot
   ```

2. Install dependencies:
   ```bash
   pip install aiosqlite
   ```

3. Configure the bot:
   ```bash
   cp config/settings.example.json config/settings.json
   # Edit config/settings.json with your IRC details
   ```

4. Run the bot:
   ```bash
   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!*