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
• Item Collection: Discover and collect useful items during exploration

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
• Item System: 16+ unique items with rarity tiers and special effects

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 ssh://git@192.168.1.249:2230/megaproxy/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

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.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!