computertech/duckhunt
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Prepare for GitHub release

Browse Source
This commit is contained in:
3nd3r
2025-12-28 13:16:55 -06:00
parent f8c46980de
commit 4d17ae8f04
8 changed files with 672 additions and 394 deletions
Download Patch File Download Diff File Expand all files Collapse all files

231
README.md
View File

@@ -1,201 +1,90 @@
# 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.
DuckHunt is an asyncio-based IRC bot that runs a classic “duck hunting” mini-game in IRC channels.
## ✨ Features
## Credits
- **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
- Originally written by **Computertech**
- New features, fixes, and maintenance added by **End3r**
## 🚀 Quick Start
## Features
### Prerequisites
- Per-channel stats (same nick has separate stats per channel)
- Multiple duck types (normal / golden / fast)
- Shop + inventory items
- Admin commands (rearm/disarm/ignore, spawn ducks, join/leave channels)
- `!globalducks` totals across channels
- JSON persistence to disk (`duckhunt.json`)
- Python 3.8+
- Virtual environment (recommended)
## Quick start
### Installation
### Requirements
1. **Clone the repository:**
```bash
git clone https://github.com/your-username/duckhunt-bot.git
cd duckhunt-bot
```
- Python 3.8+
2. **Set up virtual environment:**
```bash
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# or
.venv\Scripts\activate # Windows
```
### Run
3. **Install dependencies:**
```bash
pip install -r requirements.txt
```
From the repo root:
4. **Configure the bot:**
- Copy `config.json.example` to `config.json` (if available)
- Edit `config.json` with your IRC server settings
- See [CONFIG.md](CONFIG.md) for detailed configuration guide
5. **Run the bot:**
```bash
python duckhunt.py
```
## ⚙️ Configuration
The bot uses a nested JSON configuration system. Key settings include:
### Connection Settings
```json
{
"connection": {
"server": "irc.your-server.net",
"port": 6697,
"nick": "DuckHunt",
"channels": ["#your-channel"],
"ssl": true
}
}
```bash
python3 duckhunt.py
```
### Duck Types & Rewards
```json
{
"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 }
}
}
```
## Configuration
**📖 See [CONFIG.md](CONFIG.md) for complete configuration documentation.**
Edit `config.json`:
## 🎮 Game Commands
- `connection.server`, `connection.port`, `connection.nick`
- `connection.channels` (list of channels to join on connect)
- `connection.ssl` and optional password/SASL settings
### 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
Security note: don’t commit real IRC passwords/tokens in `config.json`.
### 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
## Persistence
## Duck Types
Player stats are saved to `duckhunt.json`.
| Type | Spawn Rate | HP | Timeout | XP Reward |
|------|------------|----|---------|-----------|
| Normal | 60% | 1 | 60s | 10 |
| Golden | 15% | 3-5 | 60s | 15 |
| Fast | 25% | 1 | 20s | 12 |
- Stats are stored per channel.
- If you run `!join` / `!leave`, the bot updates `config.json` so channel changes persist across restarts.
## 🛒 Shop Items
## Commands
- **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
### Player commands
## 📁 Project Structure
- `!bang`
- `!reload`
- `!shop`
- `!buy <item_id>`
- `!use <item_id> [target]`
- `!duckstats [player]`
- `!topduck`
- `!give <item_id> <player>`
- `!globalducks [player]` (totals across all configured channels)
- `!duckhelp` (sends a PM with examples)
### Admin commands
- `!rearm <player|all>`
- `!disarm <player>`
- `!ignore <player>` / `!unignore <player>`
- `!ducklaunch [duck_type]` (in-channel)
- `!ducklaunch <#channel> [duck_type]` (in PM)
- `!join <#channel>` / `!leave <#channel>` (persists to `config.json`)
## Repo layout
```
duckhunt/
├── duckhunt.py # Main bot entry point
├── duckhunt.py # 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
├── duckhunt.json # Player database (generated/updated at runtime)
└── src/
├── duckhuntbot.py # IRC bot + command routing
├── game.py # Duck game logic
├── db.py # Persistence layer
├── shop.py # Shop/inventory
├── levels.py # Level system
└── ...
```
## 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:
```bash
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](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](CONFIG.md) for configuration help
- 🐛 **Issues**: Report bugs via GitHub Issues
- 💬 **Discussion**: Join our IRC channel for help and discussion
---
**Happy Duck Hunting!**