https://github.com/otabekoff/hangman-bot
Hangman game, now in Telegram bot.
https://github.com/otabekoff/hangman-bot
bot game hangman telegram
Last synced: 2 months ago
JSON representation
Hangman game, now in Telegram bot.
- Host: GitHub
- URL: https://github.com/otabekoff/hangman-bot
- Owner: otabekoff
- License: mit
- Created: 2025-10-05T06:19:17.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-11-23T19:43:23.000Z (7 months ago)
- Last Synced: 2025-11-23T21:13:58.279Z (7 months ago)
- Topics: bot, game, hangman, telegram
- Language: Python
- Homepage: https://t.me/HangmanUzBot
- Size: 612 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Hangman Telegram Bot
A fun Telegram bot implementation of the classic Hangman game using aiogram.
## Features
- ๐ **Multilingual Support**: Full interface in 3 languages (English, Russian, Uzbek)
- ๐ฎ **Classic Hangman Gameplay**: Guess the word letter by letter
- ๐ผ๏ธ **Visual Progression**: 8 hangman images showing your progress
- โจ๏ธ **Language-Specific Keyboards**:
- English: A-Z alphabet (26 letters)
- Russian: Cyrillic alphabet (33 letters)
- Uzbek: Latin-based alphabet with `'` sign (26+1)
- ๐ **CSV Word Database**: Organized words with categories for each language
- ๐ฏ **Category Display**: See the category of the word you're guessing
- ๐ค **Interactive Word Display**: Word letters shown as inline buttons
- ๐ญ **Session Management**: Clean message history for better UX
- ๐ **Progressive Difficulty**: 7 wrong guesses before game over
## Setup
1. **Install dependencies:**
```bash
pip install -r requirements.txt
```
2. **Configure your bot token:**
- Create a bot using [@BotFather](https://t.me/botfather) on Telegram
- Copy the bot token
- Create a `.env` file in the project root and add your token:
```
BOT_TOKEN=your_bot_token_here
```
Example is given in `.env.example` file.
3. **Prepare word files** (optional):
- The bot comes with pre-configured word files:
- `words-en.csv`,
- `words-ru.csv`,
- `words-uz.csv`
- You can add your own words in the format: `word,category`
- Each file should contain words in the respective language
4. **Run the bot:**
```bash
python hangman-bot.py
```
## How to Play
1. **Start the bot**: Send `/start` to your bot on Telegram
2. **Select language**: Choose your preferred language (English, Russian, or Uzbek)
- This sets both the interface language and the language of words to guess
3. **Start a game**: Click the "โถ๏ธ Play" button or send `/play`
4. **Guess letters**: Tap letters from the on-screen keyboard
- The word is displayed as inline buttons (revealed letters or *)
- Wrong guesses are tracked and shown
- The hangman image updates with each wrong guess
5. **Win or lose**: Guess all letters before 7 wrong attempts to win!
6. **End game early**: Tap the ๐ซ button to stop the current game
7. **Change language**: Use the "๐ Change Language" button to switch languages
## Commands
- `/start` - Welcome message and language selection (first time) or main menu
- `/play` - Start a new game with words in your selected language
- `/help` - Show detailed help and game instructions
- `/stop` - Stop the current game and reveal the word
## Keyboard Layouts
### English (26 letters + apostrophe + END)
- Row 1: A B C D E F G
- Row 2: H I J K L M N
- Row 3: O P Q R S T U
- Row 4: V W X Y Z ' ๐ซ
### Russian (33 Cyrillic letters + apostrophe + END)
- Row 1 (9): ะ ะ ะ ะ ะ ะ ะ ะ ะ
- Row 2 (9): ะ ะ ะ ะ ะ ะ ะ ะ ะ
- Row 3 (9): ะก ะข ะฃ ะค ะฅ ะฆ ะง ะจ ะฉ
- Row 4 (7+1): ะช ะซ ะฌ ะญ ะฎ ะฏ ' ๐ซ
### Uzbek (Latin-based with special characters)
- Row 1: A B C D E F G
- Row 2: H I J K L M N
- Row 3: O P Q R S T U
- Row 4: V W X Y Z ' ๐ซ
## Game Rules
- You have **7 wrong guesses** before the game ends
- Each wrong guess progresses the hangman image
- Guessed letters are tracked and displayed
- Win by guessing all letters correctly before running out of attempts
- Words are selected randomly from the language-specific CSV file
- Each word has an associated category shown during gameplay
## Image Progression
The bot uses 8 images to show the hangman progression:
1. `blank.png` - Starting state
2. `head.png` - After 1 wrong guess
3. `head-torso.png` - After 2 wrong guesses
4. `h-t-lh.png` - After 3 wrong guesses
5. `h-t-hands-lf.png` - After 4 wrong guesses
6. `h-t-hands.png` - After 5 wrong guesses
7. `fresh-man.png` - After 6 wrong guesses
8. `died-man.png` - Game Over (7 wrong guesses)
## Project Structure
```
hangman-bot/
โโโ hangman-bot.py # Main bot code
โโโ .env # Bot token configuration (create this)
โโโ requirements.txt # Python dependencies
โโโ README.md # This file
โโโ words-en.csv # English words database
โโโ words-ru.csv # Russian words database
โโโ words-uz.csv # Uzbek words database
โโโ images/ # Hangman progression images
โโโ blank.png
โโโ head.png
โโโ head-torso.png
โโโ h-t-lh.png
โโโ h-t-hands-lf.png
โโโ h-t-hands.png
โโโ fresh-man.png
โโโ died-man.png
```
## CSV Word File Format
Each language has its own CSV file with the following format:
```csv
word,category
PYTHON,Programming
TELEGRAM,Technology
COMPUTER,Technology
```
- **Header row**: `word,category`
- **Data rows**: One word per line with its category
- **Words**: Should be in UPPERCASE
- **Encoding**: UTF-8 (important for Cyrillic and special characters)
## Technologies Used
- **Python 3.x**
- **aiogram 3.13.1** - Modern async Telegram Bot API framework
- **python-dotenv 1.0.1** - Environment variable management
- **CSV module** - Word database management
- **FSM (Finite State Machine)** - Game state management
- **Inline & Reply Keyboards** - Interactive UI elements
## License
Free to use and modify for personal and educational purposes.