duckhunt/README.md

DuckHunt IRC Bot

A feature-rich IRC bot that brings the classic duck hunting game to your IRC channels. Players can shoot, befriend, and collect various types of ducks while managing their equipment and competing for high scores.

✨ Features

• Multiple Duck Types: Normal, Golden (high HP), and Fast (quick timeout) ducks
• 🎯 Accuracy System: Dynamic accuracy that improves with hits and degrades with misses
• Weapon Management: Magazines, bullets, and gun jamming mechanics
• 🛒 Shop System: Buy equipment and items with XP (currency)
• 🎒 Inventory System: Collect and use various items (bread, grease, sights, etc.)
• 👥 Player Statistics: Track shots, hits, misses, and best times
• Fully Configurable: Every game parameter can be customized via config
• 🔐 Authentication: Support for both server passwords and SASL/NickServ auth
• 📊 Admin Commands: Comprehensive bot management and player administration

🚀 Quick Start

Prerequisites

• Python 3.8+
• Virtual environment (recommended)

Installation

1. Clone the repository:

   git clone https://github.com/your-username/duckhunt-bot.git
   cd duckhunt-bot
   

2. Set up virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # Linux/Mac
   # or
   .venv\Scripts\activate     # Windows
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure the bot:

   • Copy config.json.example to config.json (if available)
   • Edit config.json with your IRC server settings
   • See CONFIG.md for detailed configuration guide

5. Run the bot:

   python duckhunt.py
   

⚙️ Configuration

The bot uses a nested JSON configuration system. Key settings include:

Connection Settings

{
  "connection": {
    "server": "irc.your-server.net",
    "port": 6697,
    "nick": "DuckHunt",
    "channels": ["#your-channel"],
    "ssl": true
  }
}

Duck Types & Rewards

{
  "duck_types": {
    "normal": { "xp": 10, "timeout": 60 },
    "golden": { "chance": 0.15, "min_hp": 3, "max_hp": 5, "xp": 15 },
    "fast": { "chance": 0.25, "timeout": 20, "xp": 12 }
  }
}

📖 See CONFIG.md for complete configuration documentation.

🎮 Game Commands

Player Commands

• !shoot - Shoot at a duck
• !reload - Reload your weapon
• !befriend - Try to befriend a duck
• !stats [player] - View player statistics
• !shop - View the shop
• !buy <item> - Purchase an item
• !inventory - Check your inventory
• !use <item> - Use an item from inventory

Admin Commands

• !spawn - Manually spawn a duck
• !give <player> <item> <quantity> - Give items to players
• !setstat <player> <stat> <value> - Modify player stats
• !reload_config - Reload configuration without restart

Duck Types

Type	Spawn Rate	HP	Timeout	XP Reward
Normal	60%	1	60s	10
Golden	15%	3-5	60s	15
Fast	25%	1	20s	12

🛒 Shop Items

• Bread - Attracts more ducks
• Gun Grease - Reduces jam chance
• Sight - Improves accuracy
• Silencer - Enables stealth shooting
• Explosive Ammo - Extra damage
• Lucky Charm - Increases rewards
• Duck Detector - Reveals duck locations

📁 Project Structure

duckhunt/
├── duckhunt.py          # Main bot entry point
├── config.json          # Bot configuration
├── CONFIG.md           # Configuration documentation
├── src/
│   ├── duckhuntbot.py  # Core bot IRC functionality
│   ├── game.py         # Duck game mechanics
│   ├── db.py           # Player database management
│   ├── shop.py         # Shop system
│   ├── levels.py       # Player leveling system
│   ├── sasl.py         # SASL authentication
│   └── utils.py        # Utility functions
├── shop.json           # Shop item definitions
├── levels.json         # Level progression data
├── messages.json       # Bot response messages
└── duckhunt.json       # Player database

Development

Adding New Features

The bot is designed with modularity in mind:

1. Game mechanics are in src/game.py
2. IRC functionality is in src/duckhuntbot.py
3. Database operations are in src/db.py
4. Configuration uses dot notation: bot.get_config('duck_types.normal.xp')

Testing Configuration

Use the built-in config tester:

python test_config.py

🛠️ Troubleshooting

Common Issues

1. Connection fails: Check server, port, and SSL settings in config
2. SASL authentication fails: Verify username/password and ensure nick is registered
3. Bot doesn't respond: Check channel permissions and admin list
4. Config errors: Validate JSON syntax and see CONFIG.md for proper values

Debug Mode

Enable detailed logging by setting log level in the code or add verbose output.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• Inspired by classic IRC duck hunting bots
• Built with Python's asyncio for modern async IRC handling
• Thanks to all contributors and testers

📞 Support

• 📖 Documentation: See CONFIG.md for configuration help
• 🐛 Issues: Report bugs via GitHub Issues
• 💬 Discussion: Join our IRC channel for help and discussion

---

Happy Duck Hunting!