🃏 Durak Bot — Telegram Card Game

📌 Description

A Telegram bot that lets you play Durak (Дурак) — the classic Russian card game — straight from a chat. Built with Python and aiogram, it deals a real 36-card deck, tracks a trump suit, and plays a full hand against you: attack, defend, refill from the deck, repeat until someone runs out of cards.

🚀 Features

• 🃏 Real 36-card deck with proper trump handling
• 🤖 Bot opponent that defends with the cheapest valid card, saving trumps for later
• 🔄 Automatic hand refill from the deck after every round (up to 6 cards each)
• ⌨️ Reply-keyboard UI — pick cards by tapping, no typing needed
• 🏳️ Surrender option at any time
• 🎯 Win detection once the deck runs dry and a hand empties out
• 🧩 Clean, modular codebase — game rules separated from Telegram wiring

🛠 Technologies Used

• Python 3
• aiogram 2.x — async Telegram Bot framework
• python-dotenv — environment variable loading

▶ How to Run

1. Install Python 3
2. Clone the repo:

   git clone https://github.com/Milesden/durak_bot.git
   cd durak_bot

3. Install dependencies:

   pip install -r requirements.txt

4. Set up your bot token:

   cp .env.example .env

   Then open .env and replace your_token_here with a real token from @BotFather.
5. Run the bot:

   python main.py

6. Open your bot in Telegram and send /start.

📚 Concepts Used

• Async/await (asyncio, aiogram handlers)
• State management per user
• Functions & modules
• Conditional statements
• Environment variables / secrets handling

📁 Project structure

durak_bot/
├── main.py               # Entry point — creates the bot and starts polling
├── bot/
│   ├── __init__.py
│   ├── config.py          # Loads BOT_TOKEN from .env
│   ├── deck.py            # Deck creation and card-beats-card rules
│   ├── game.py             # Game state: dealing, refilling, win checks
│   ├── keyboards.py        # Reply keyboard builders
│   └── handlers.py         # Telegram message handlers
├── assets/
│   └── preview.svg         # README chat preview
├── requirements.txt
├── Procfile                # For Heroku-style worker deployment
├── .env.example             # Template — copy to .env and fill in your token
└── .gitignore

⚠️ Known limitations

This is a simplified single-attacker-card version of Durak — no "podkidnoy" (throwing in extra cards of matching rank during a round) yet. Contributions or forks that add it are welcome.

🔐 Security note

Never commit your real .env file — it's already gitignored. Only .env.example (with a placeholder value) belongs in version control.