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

Add comprehensive documentation and fix authentication config paths

Browse Source 
- Add detailed README.md with installation, usage, and development guide
- Add CONFIG.md with complete configuration documentation
- Update connection and SASL authentication to use nested config paths
- Fix server password and SASL username/password config access
- Add config validation test script (test_config.py)
- Clean up config.json (removed invalid JSON comments)
- Improve error handling for config arrays and null values
This commit is contained in:
Colby Lipsett
2025-09-24 20:33:23 +01:00
parent 74f3afdf4b
commit eb041477dc
8 changed files with 409 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
CONFIG.md Normal file
View File

@@ -0,0 +1,127 @@
# DuckHunt Bot Configuration Guide
This document explains all configuration options in `config.json`.
## 📡 IRC Connection Settings (`connection`)
| Setting | Description | Example |
|---------|-------------|---------|
| `server` | IRC server hostname | `"irc.rizon.net"` |
| `port` | IRC server port | `6697` (SSL) or `6667` (non-SSL) |
| `nick` | Bot's nickname on IRC | `"DuckHunt"` |
| `channels` | List of channels to auto-join | `["#channel1", "#channel2"]` |
| `ssl` | Use SSL/TLS encryption | `true` (recommended) |
| `password` | Server password (I-Line auth) | Change if server requires auth |
| `max_retries` | Connection retry attempts | `3` |
| `retry_delay` | Seconds between retries | `5` |
| `timeout` | Connection timeout in seconds | `30` |
## 🔐 SASL Authentication (`sasl`)
SASL is used for NickServ authentication on connect.
| Setting | Description | Example |
|---------|-------------|---------|
| `enabled` | Enable SASL authentication | `false` |
| `username` | Registered nickname | `"your_registered_nick"` |
| `password` | NickServ password | `"your_nickserv_password"` |
**Note:** Change `password` from the default if enabling SASL!
## 👑 Bot Administration (`admins`)
Array of IRC nicknames with admin privileges.
```json
"admins": ["peorth", "computertech", "colby"]
```
## 🦆 Duck Spawning (`duck_spawning`)
| Setting | Description | Default |
|---------|-------------|---------|
| `spawn_min` | Minimum seconds between spawns | `10` |
| `spawn_max` | Maximum seconds between spawns | `30` |
| `timeout` | Global fallback timeout | `60` |
| `rearm_on_duck_shot` | Auto-rearm guns when duck shot | `true` |
## 🎯 Duck Types (`duck_types`)
### Normal Ducks (`normal`)
- `xp`: XP reward (default: `10`)
- `timeout`: Seconds before flying away (default: `60`)
### Golden Ducks (`golden`)
- `chance`: Spawn probability (default: `0.15` = 15%)
- `min_hp`: Minimum hit points (default: `3`)
- `max_hp`: Maximum hit points (default: `5`)
- `xp`: XP reward (default: `15`)
- `timeout`: Seconds before flying away (default: `60`)
### Fast Ducks (`fast`)
- `chance`: Spawn probability (default: `0.25` = 25%)
- `timeout`: Seconds before flying away (default: `20`)
- `xp`: XP reward (default: `12`)
**Note:** Chances are decimal percentages (0.15 = 15%, 0.25 = 25%)
## 👤 New Player Defaults (`player_defaults`)
Starting values for new players:
| Setting | Description | Default |
|---------|-------------|---------|
| `accuracy` | Starting accuracy percentage (0-100) | `75` |
| `magazines` | Starting number of magazines | `3` |
| `bullets_per_magazine` | Bullets per magazine | `6` |
| `jam_chance` | Gun jam percentage (0-100) | `15` |
| `xp` | Starting XP (also currency) | `0` |
## 🎮 Game Mechanics (`gameplay`)
| Setting | Description | Default |
|---------|-------------|---------|
| `befriend_success_rate` | Base befriend chance (%) | `75` |
| `befriend_xp` | XP from befriending | `5` |
| `accuracy_gain_on_hit` | Accuracy boost per hit | `1` |
| `accuracy_loss_on_miss` | Accuracy loss per miss | `2` |
| `min_accuracy` | Minimum accuracy limit | `10` |
| `max_accuracy` | Maximum accuracy limit | `100` |
| `min_befriend_success_rate` | Min befriend rate | `5` |
| `max_befriend_success_rate` | Max befriend rate | `95` |
## 🔧 Feature Toggles (`features`)
| Setting | Description | Default |
|---------|-------------|---------|
| `shop_enabled` | Enable shop system | `true` |
| `inventory_enabled` | Enable inventory system | `true` |
| `auto_rearm_enabled` | Enable auto gun rearming | `true` |
## ⚖️ System Limits (`limits`)
| Setting | Description | Default |
|---------|-------------|---------|
| `max_inventory_items` | Max items per player | `20` |
| `max_temp_effects` | Max temporary effects | `20` |
---
## 🔧 Configuration Access
The bot uses dot notation to access nested settings:
```python
# Examples:
server = bot.get_config('connection.server')
normal_xp = bot.get_config('duck_types.normal.xp')
player_accuracy = bot.get_config('player_defaults.accuracy')
```
## 📝 Tips
1. **Percentages:** Most percentage values use 0-100 scale, but spawn chances use 0.0-1.0 decimals
2. **Authentication:** Set real passwords when using server auth or SASL
3. **Balance:** Adjust XP rewards and duck spawn rates to balance gameplay
4. **Testing:** Change one setting at a time to test effects
5. **Backup:** Keep a backup of working config before major changes

201
README.md Normal file
View File

@@ -0,0 +1,201 @@
# 🦆 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:**
```bash
git clone https://github.com/your-username/duckhunt-bot.git
cd duckhunt-bot
```
2. **Set up virtual environment:**
```bash
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# or
.venv\Scripts\activate # Windows
```
3. **Install dependencies:**
```bash
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](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
}
}
```
### 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 }
}
}
```
**📖 See [CONFIG.md](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:
```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!** 🦆🔫

8
config.json
View File

@@ -36,12 +36,12 @@
"min_hp": 3,
"max_hp": 5,
"xp": 15,
"timeout": 50
"timeout": 60
},
"fast": {
"chance": 0.25,
"timeout": 20,
"xp": 20
"xp": 12
}
},
@@ -49,7 +49,7 @@
"accuracy": 75,
"magazines": 3,
"bullets_per_magazine": 6,
"jam_chance": 5,
"jam_chance": 15,
"xp": 0
},
@@ -72,6 +72,6 @@
"limits": {
"max_inventory_items": 20,
"max_temp_effects": 5
"max_temp_effects": 20
}
}

BIN
src/__pycache__/duckhuntbot.cpython-312.pyc
View File

Binary file not shown.

BIN
src/__pycache__/sasl.cpython-312.pyc
View File

Binary file not shown.

28
src/duckhuntbot.py
View File

@@ -32,7 +32,8 @@ class DuckHuntBot:
self.sasl_handler = SASLHandler(self, config)
self.admins = [admin.lower() for admin in self.config.get('admins', ['colby'])]
admins_list = self.get_config('admins', ['colby']) or ['colby']
self.admins = [admin.lower() for admin in admins_list]
# Initialize shop manager
shop_file = os.path.join(os.path.dirname(os.path.dirname(__file__)), 'shop.json')
@@ -103,24 +104,26 @@ class DuckHuntBot:
for attempt in range(max_retries):
try:
ssl_context = None
if self.config.get('ssl', False):
if self.get_config('connection.ssl', False):
ssl_context = ssl.create_default_context()
# Add SSL context configuration for better compatibility
ssl_context.check_hostname = False
ssl_context.verify_mode = ssl.CERT_NONE
self.logger.info(f"Attempting to connect to {self.config['server']}:{self.config['port']} (attempt {attempt + 1}/{max_retries})")
server = self.get_config('connection.server', 'irc.libera.chat')
port = self.get_config('connection.port', 6667)
self.logger.info(f"Attempting to connect to {server}:{port} (attempt {attempt + 1}/{max_retries})")
self.reader, self.writer = await asyncio.wait_for(
asyncio.open_connection(
self.config['server'],
self.config['port'],
server,
port,
ssl=ssl_context
),
timeout=self.get_config('connection.timeout', 30) or 30.0 # Connection timeout from config
)
self.logger.info(f"✅ Successfully connected to {self.config['server']}:{self.config['port']}")
self.logger.info(f"✅ Successfully connected to {server}:{port}")
return
except asyncio.TimeoutError:
@@ -183,11 +186,13 @@ class DuckHuntBot:
async def register_user(self):
"""Register user with IRC server"""
if self.config.get('password'):
self.send_raw(f"PASS {self.config['password']}")
password = self.get_config('connection.password')
if password and password != "your_iline_password_here":
self.send_raw(f"PASS {password}")
self.send_raw(f"NICK {self.config['nick']}")
self.send_raw(f"USER {self.config['nick']} 0 * :{self.config['nick']}")
nick = self.get_config('connection.nick', 'DuckHunt')
self.send_raw(f"NICK {nick}")
self.send_raw(f"USER {nick} 0 * :{nick}")
async def handle_message(self, prefix, command, params, trailing):
"""Handle incoming IRC messages with comprehensive error handling"""
@@ -227,7 +232,8 @@ class DuckHuntBot:
self.logger.info("Successfully registered with IRC server")
# Join channels
for channel in self.config.get('channels', []):
channels = self.get_config('connection.channels', []) or []
for channel in channels:
try:
self.send_raw(f"JOIN {channel}")
self.channels_joined.add(channel)

8
src/sasl.py
View File

@@ -14,10 +14,10 @@ class SASLHandler:
def __init__(self, bot, config):
self.bot = bot
self.logger = setup_logger("SASL")
sasl_config = config.get("sasl", {})
self.enabled = sasl_config.get("enabled", False)
self.username = sasl_config.get("username", config.get("nick", ""))
self.password = sasl_config.get("password", "")
# Use bot's get_config method for nested config access
self.enabled = bot.get_config("sasl.enabled", False)
self.username = bot.get_config("sasl.username", bot.get_config("connection.nick", ""))
self.password = bot.get_config("sasl.password", "")
self.authenticated = False
self.cap_negotiating = False

56
test_config.py Normal file
View File

@@ -0,0 +1,56 @@
#!/usr/bin/env python3
import json
import os
def test_config():
"""Test the config structure and values"""
config_path = 'config.json'
if not os.path.exists(config_path):
print("❌ Config file not found")
return
with open(config_path, 'r') as f:
config = json.load(f)
print("🧪 Testing configuration structure...")
# Test connection settings
connection = config.get('connection', {})
print(f"🌐 Server: {connection.get('server')}")
print(f"🔌 Port: {connection.get('port')}")
print(f"🤖 Nick: {connection.get('nick')}")
print(f"🔒 SSL: {connection.get('ssl')}")
# Check if password is set (not default)
password = connection.get('password')
password_set = password and password != "your_iline_password_here"
print(f"🔑 Password configured: {'Yes' if password_set else 'No (default placeholder)'}")
# Test SASL settings
sasl = config.get('sasl', {})
print(f"🔐 SASL enabled: {sasl.get('enabled')}")
print(f"👤 SASL username: {sasl.get('username')}")
# Check if SASL password is set (not default)
sasl_password = sasl.get('password')
sasl_password_set = sasl_password and sasl_password != "duckhunt//789//"
print(f"🗝️ SASL password configured: {'Yes' if sasl_password_set else 'No (default placeholder)'}")
# Test channels
channels = connection.get('channels', [])
print(f"📺 Channels to join: {channels}")
print("\n✅ Configuration structure looks good!")
if not password_set:
print("⚠️ Warning: Server password is still set to placeholder value")
print(" Update 'connection.password' if your server requires authentication")
if sasl.get('enabled') and not sasl_password_set:
print("⚠️ Warning: SASL is enabled but password is still placeholder")
print(" Update 'sasl.password' with your actual NickServ password")
if __name__ == "__main__":
test_config()