Petbot/README.md

# PetBot - IRC Pokemon-Style Pet Game Bot

A comprehensive 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 manage their collections through an integrated web interface.

## 🎮 Features

### Core Gameplay
- **Pet Collection**: Catch and collect different species of pets with varying rarities
- **Exploration**: Travel between various themed locations with unique spawns
- **Battle System**: Engage in turn-based battles with wild pets and gym leaders
- **Team Management**: Build teams with drag-and-drop web interface and PIN verification
- **Achievement System**: Unlock new areas by completing challenges and milestones
- **Item Collection**: Discover 17+ useful items including healing potions, battle boosters, and treasure

### Advanced Systems
- **Dynamic Weather**: Real-time weather system affecting spawn rates and pet encounters
- **Web Interface**: Modern responsive web dashboard with unified navigation
- **Enhanced Leaderboards**: 8 different ranking categories (levels, experience, wealth, achievements, etc.)
- **Interactive Team Builder**: Drag-and-drop team management with numbered slots (1-6)
- **Location-Based Spawns**: Different pets spawn in different locations with weather modifiers
- **Level Progression**: Pets gain experience, level up, and can be nicknamed
- **Type Effectiveness**: Strategic battle system with type advantages
- **Gym Battle System**: Challenge gym leaders and earn badges
- **Global Item Spawn Control**: Admin-configurable spawn rates with global multipliers

### Modern Web Features
- **Unified Navigation**: Consistent navigation bar across all web pages
- **Player Profiles**: Comprehensive player statistics and pet collections
- **Team Builder**: Secure PIN-verified team changes with IRC delivery
- **Inventory Management**: Visual item display with usage commands
- **Multi-Category Leaderboards**: Interactive leaderboard switching
- **Responsive Design**: Mobile-friendly interface design

### Technical Features
- **Robust IRC Connection**: Auto-reconnecting IRC client with health monitoring
- **Rate Limiting System**: Token bucket rate limiting to prevent spam and abuse
- **Automated Backups**: Comprehensive database backup system with retention policies
- **Security Monitoring**: Security audit completed with 23 vulnerabilities identified
- **Modular Architecture**: Clean, extensible codebase with proper separation of concerns
- **Async Database**: SQLite with async operations and proper transaction handling
- **Background Tasks**: Automated weather updates and system monitoring
- **Error Handling**: Comprehensive error handling and user feedback

## 🚀 Quick Start

### Prerequisites
- Python 3.8+
- SQLite3
- Network access for IRC and web server

### Installation
1. Clone the repository:
   ```bash
   git clone ssh://git@192.168.1.249:2230/megaproxy/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

### Inventory Commands
- `!inventory` / `!inv` / `!items` - View your collected items
- `!use <item>` - Use a consumable item on your active pet

## 🌍 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:
- **Pet Collector**: Catch 5 pets total → 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

### Achievement Progression
- **Pet Collector** (5 pets) → Unlock Whispering Woods
- **Nature Explorer** (3 different Grass pets) → No location unlock
- **Advanced Trainer** (10 pets) → No location unlock

## 🌤️ 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

## 🎒 Item System

### Item Categories
- **🩹 Healing Items**: Restore pet HP (Small/Large/Super Potions, Energy Berries)
- **⚔️ Battle Items**: Temporary combat boosts (Attack Boosters, Defense Crystals, Speed Elixirs)
- **💎 Rare Items**: Special materials (Fire/Water Stones, Lucky Charms, Ancient Fossils)
- **🏛️ Location Items**: Area-specific treasures (Shells, Mushrooms, Volcanic Glass, Ice Crystals)

### Rarity Tiers
- **○ Common**: Frequently found items (15% spawn rate)
- **◇ Uncommon**: Moderately rare items (8-12% spawn rate)
- **◆ Rare**: Valuable items (3-6% spawn rate)
- **★ Epic**: Very rare items (2-3% spawn rate)
- **✦ Legendary**: Ultra-rare items (1% spawn rate)

### Item Discovery
- 30% chance to find items during `!explore`
- Location-specific items only spawn in certain areas
- Items stack in inventory with quantity tracking
- Use consumable items with `!use <item name>`

## 🌐 Web Interface

Access the web dashboard at `http://petz.rdx4.com/`:
- **Player Profiles**: Complete stats, pet collections, and inventories
- **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

### v0.3.0 - Team Swap System & Architecture Cleanup
- ✅ **Active Team Architecture**: Complete redesign allowing any team (1-3) to be set as active
- ✅ **Web-IRC Synchronization**: IRC battles now use teams selected via web interface
- ✅ **Team Management Hub**: Enhanced web interface with "Make Active" buttons and team status
- ✅ **Database Migration**: New `active_teams` table for flexible team management
- ✅ **PIN Security**: Secure team changes with IRC-delivered PINs and verification
- ✅ **Command Architecture Cleanup**: Eliminated 12 duplicate commands and standardized admin system
- ✅ **Legacy Code Removal**: Cleaned up 180+ lines of redundant code across modules
- ✅ **Modular System Enhancement**: Improved separation of concerns and maintainability

### v0.2.0 - Item Collection System
- ✅ Complete item system with 16 unique items across 5 categories
- ✅ Item discovery during exploration (30% chance)
- ✅ Rarity tiers with symbols and colors (Common → Legendary)
- ✅ Location-specific unique items and treasures
- ✅ Inventory management with `!inventory` and `!use` commands
- ✅ Web interface integration showing player inventories
- ✅ Consumable items (healing potions, battle boosters, lucky charms)

### v0.1.0 - Core Game & Weather System
- ✅ Added background task for automatic weather updates
- ✅ Changed weather durations from 2-6 hours to 30min-3hours
- ✅ Implemented continuous weather coverage
- ✅ 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!*