duckhunt/README.md

DuckHunt IRC Bot

DuckHunt is an asyncio-based IRC bot that runs a classic "duck hunting" mini-game in IRC channels.

Credits

• Originally written by Computertech
• New features, fixes, and maintenance added by End3r

Features

• Multi-channel support - Bot can be in multiple channels
• Global player stats - Same player stats across all channels
• Three duck types - Normal, Golden (multi-HP), and Fast ducks
• Shop system - Buy items to improve your hunting
• Leveling system - Gain XP and increase your level
• Admin commands - Join/leave channels, spawn ducks, manage players
• JSON persistence - All stats saved to disk
• Auto-save - Progress saved automatically after each action

Quick Start

Requirements

• Python 3.8+

Run

From the repo root:

python3 duckhunt.py

Configuration

Copy the example config and edit it:

cp config.json.example config.json

Then edit config.json:

• connection.server, connection.port, connection.nick
• connection.channels (list of channels to join on connect)
• connection.ssl and optional password/SASL settings
• admins (list of admin nicks or nick+hostmask patterns)

Security note: config.json is ignored by git - don't commit real IRC passwords/tokens.

Duck Types

Three duck types with different behaviors:

• Normal - Standard duck, 1 HP, base XP
• Golden - Multi-HP duck (3-5 HP), high XP, awards XP per hit
• Fast - Quick duck, 1 HP, flies away faster

Duck spawn rates configured in config.json:

• golden_duck_chance - Probability of golden duck (default: 0.15)
• fast_duck_chance - Probability of fast duck (default: 0.25)

Persistence

Player stats are saved to duckhunt.json:

• Global stats - Players have one set of stats across all channels
• Auto-save - Database saved after each action (shoot, reload, shop, etc.)
• Atomic writes - Safe file handling prevents database corruption
• Retry logic - Automatic retry on save failures

Commands

Player Commands

• !bang - Shoot at a duck
• !bef or !befriend - Try to befriend a duck
• !reload - Reload your gun
• !shop - View available items
• !shop buy <item_id> - Purchase an item from the shop
• !duckstats [player] - View hunting statistics
• !topduck - View leaderboard (top hunters)
• !duckhelp - Get detailed command list via PM

Admin Commands

• !rearm <player|all> - Give player a gun
• !disarm <player> - Confiscate player's gun
• !ignore <player> / !unignore <player> - Ignore/unignore commands
• !ducklaunch [duck_type] - Force spawn a duck (normal, golden, fast)
• !join <#channel> - Make bot join a channel
• !part <#channel> - Make bot leave a channel

Admin commands work in PM or in-channel.

Shop Items

Basic shop items available (use !shop to see current inventory):

• Bullets - Ammunition refills
• Magazines - Extra ammo capacity
• Gun Improvements - Better accuracy, less jamming
• Gun License - Buy back your confiscated gun
• Insurance - Protection from penalties

Use !shop buy <id> to purchase.

Gameplay

How to Play

1. Wait for a duck to spawn (appears randomly in channel)
2. Type !bang to shoot it
3. Earn XP for successful hits
4. Level up to improve your stats
5. Buy items from !shop to enhance your hunting

Duck Behavior

• Normal ducks - Standard targets, 1 shot to kill
• Golden ducks - Tougher! Multiple HP, gives XP per hit
• Fast ducks - Quick! They fly away faster than normal

Stats Tracked

• XP (experience points)
• Ducks shot
• Ducks befriended
• Shots fired
• Accuracy percentage
• Current level

Repo Layout

duckhunt/
├── duckhunt.py          # Entry point
├── config.json          # Bot configuration (ignored by git)
├── config.json.example  # Safe template to copy
├── duckhunt.json        # Player database (auto-generated)
├── levels.json          # Level definitions
├── shop.json            # Shop item catalog
├── messages.json        # Bot messages
└── src/
    ├── duckhuntbot.py   # IRC bot + command routing
    ├── game.py          # Duck game logic
    ├── db.py            # Database persistence
    ├── shop.py          # Shop/inventory system
    ├── levels.py        # Leveling system
    ├── sasl.py          # SASL authentication
    ├── error_handling.py # Error recovery
    └── utils.py         # Utility functions

Recent Updates

• ✅ Fixed golden duck XP bug (now awards XP on each hit)
• ✅ Added !join and !part admin commands
• ✅ Improved !duckhelp with detailed PM
• ✅ Simplified to 3 core duck types for stability
• ✅ Enhanced database save reliability

Happy Duck Hunting! 🦆