Jocaru/echoes-of-the-ash
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add visual progress bars and refactor handler modules

Browse Source 
- Implement visual HP/Stamina/XP bars using Unicode characters (██░)
- Refactor handlers.py (1308 → 377 lines) into specialized modules:
  * action_handlers.py - World interaction and status display
  * inventory_handlers.py - Inventory management
  * combat_handlers.py - Combat actions
  * profile_handlers.py - Character stats with visual bars
  * corpse_handlers.py - Looting system
  * pickup_handlers.py - Item collection
- Add utility functions: create_progress_bar(), format_stat_bar()
- Organize all documentation into docs/ structure
- Create comprehensive documentation index with navigation
- Add UI examples showing before/after visual improvements
This commit is contained in:
Joan
2025-10-19 00:23:44 +02:00
parent ab13bdb9f1
commit 861f3b8a36
15 changed files with 3150 additions and 1062 deletions
Download Patch File Download Diff File Expand all files Collapse all files

298
docs/development/BOT_MODULE.md Normal file
View File

@@ -0,0 +1,298 @@
# Bot Module Documentation
## Overview
The bot module contains all the Telegram bot logic for "Echoes of the Ashes" RPG game.
## Module Structure
### Core Modules
- **`handlers.py`** (14KB) - Main message router and utility functions
- **`database.py`** - Database operations and queries
- **`keyboards.py`** - Telegram keyboard layouts
- **`logic.py`** - Game logic and calculations
- **`combat.py`** (17KB) - Combat system implementation
- **`spawn_manager.py`** - Enemy spawning system
- **`utils.py`** - Utility functions and decorators
### Handler Modules (Refactored)
Organized by functionality for better maintainability:
#### **`action_handlers.py`** (14KB, 367 lines)
World interaction and inspection
- `get_player_status_text()` - Player status display
- `handle_inspect_area()` - Inspect locations
- `handle_attack_wandering()` - Attack wandering enemies
- `handle_inspect_interactable()` - Inspect objects
- `handle_action()` - Perform actions
- `handle_main_menu()` - Main menu navigation
- `handle_move_menu()` - Movement menu
- `handle_move()` - Travel between locations
#### **`inventory_handlers.py`** (13KB, 355 lines)
Inventory management system
- `handle_inventory_menu()` - Show inventory
- `handle_inventory_item()` - Item details
- `handle_inventory_use()` - Use consumables
- `handle_inventory_drop()` - Drop items
- `handle_inventory_equip()` - Equip gear
- `handle_inventory_unequip()` - Unequip gear
#### **`pickup_handlers.py`** (5.1KB, 135 lines)
Item collection from world
- `handle_pickup_menu()` - Pickup options
- `handle_pickup()` - Pick up items
#### **`combat_handlers.py`** (6.3KB, 171 lines)
Combat action handlers
- `handle_combat_attack()` - Attack enemy
- `handle_combat_flee()` - Flee combat
- `handle_combat_use_item_menu()` - Combat items menu
- `handle_combat_use_item()` - Use item in combat
- `handle_combat_back()` - Return to combat menu
#### **`profile_handlers.py`** (6.0KB, 147 lines)
Character progression
- `handle_profile()` - View profile
- `handle_spend_points_menu()` - Stat points menu
- `handle_spend_point()` - Allocate stat points
#### **`corpse_handlers.py`** (8.2KB, 234 lines)
Looting system
- `handle_loot_player_corpse()` - Loot player corpses
- `handle_take_corpse_item()` - Take items from player corpse
- `handle_scavenge_npc_corpse()` - Scavenge NPC corpses
- `handle_scavenge_corpse_item()` - Take items from NPC corpse
## Architecture
### Message Flow
```
Telegram Update
↓
main.py (Application setup)
↓
handlers.py::button_handler (Router)
↓
Specialized Handler (action_handlers, combat_handlers, etc.)
↓
database.py (Data operations)
↓
keyboards.py (UI response)
↓
Response to User
```
### Handler Pattern
All handlers follow a consistent pattern:
```python
async def handle_action(query, user_id: int, player: dict, data: list = None):
"""
Handle specific action.
Args:
query: Telegram callback query object
user_id: Telegram user ID
player: Player data dict
data: Optional list of parameters from callback_data
"""
# 1. Validate input
# 2. Perform action
# 3. Update database
# 4. Send response with send_or_edit_with_image()
```
### Shared Utilities
#### `send_or_edit_with_image()`
Central function for sending/editing messages with images:
```python
await send_or_edit_with_image(
query,
text="Message text",
reply_markup=keyboard,
image_path="/path/to/image.png" # Optional
)
```
Features:
- Smooth image transitions
- Image caching for performance
- Automatic fallback to text-only
- Edit vs. send detection
## Design Principles
### 1. Separation of Concerns
Each module handles a specific domain:
- Handlers → User interaction
- Database → Data persistence
- Logic → Game rules
- Combat → Battle mechanics
### 2. Single Responsibility
Each function has one clear purpose:
- ✅ `handle_inventory_use()` - Use items
- ✅ `handle_combat_attack()` - Attack in combat
- ❌ ~~One giant function that does everything~~
### 3. Consistency
All handlers:
- Accept same parameter pattern
- Use async/await
- Handle errors gracefully
- Log important actions
### 4. Error Handling
Centralized in `button_handler`:
```python
try:
await handle_specific_action(...)
except Exception as e:
logger.error(f"Error: {e}", exc_info=True)
await query.answer("An error occurred.", show_alert=True)
```
## Adding New Handlers
### Step 1: Create Handler Function
```python
# In appropriate *_handlers.py module
async def handle_new_action(query, user_id: int, player: dict, data: list):
"""Handle new action."""
await query.answer()
# Your logic here
from .handlers import send_or_edit_with_image
await send_or_edit_with_image(
query,
text="Action result",
reply_markup=some_keyboard()
)
```
### Step 2: Import in handlers.py
```python
from .your_handlers import handle_new_action
```
### Step 3: Add Route
```python
# In button_handler()
elif action_type == "new_action":
await handle_new_action(query, user_id, player, data)
```
### Step 4: Create Keyboard Button
```python
# In keyboards.py
InlineKeyboardButton(
"New Action",
callback_data="new_action:param1:param2"
)
```
## Testing
### Manual Testing
1. Start the bot: `python main.py`
2. Send `/start` to the bot
3. Test each button action
4. Check logs for errors
### Unit Testing (Future)
```python
# tests/test_handlers.py
async def test_handle_inventory_use():
result = await handle_inventory_use(
mock_query,
user_id=123,
player=mock_player,
data=['inventory_use', '1']
)
assert result is not None
```
## Performance Considerations
### Image Caching
Images are cached after first upload:
```python
cached_file_id = await database.get_cached_image(image_path)
if not cached_file_id:
# Upload and cache
await database.cache_image(image_path, file_id)
```
### Database Queries
- Use indexed lookups (user_id, location_id)
- Batch operations where possible
- Async all the way
### Memory
- Don't store large objects in memory
- Use database for persistence
- Clean up old data periodically
## Debugging
### Enable Debug Logging
```python
# In main.py
logging.basicConfig(
level=logging.DEBUG, # Change from INFO
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
```
### Common Issues
**Issue:** Handler not being called
- Check callback_data format: `"action_type:param1:param2"`
- Verify route exists in `button_handler()`
- Check import statement
**Issue:** Image not showing
- Verify image path exists
- Check image cache
- Look for upload errors in logs
**Issue:** Database errors
- Check player exists
- Verify foreign key relationships
- Look at database schema
## Migration Guide
### From Old handlers.py
Old code in backup files:
- `backups/handlers_original.py`
- `backups/handlers.py.old`
All functionality preserved, just reorganized into modules.
## Future Enhancements
1. **Type Hints** - Add proper type annotations
2. **Unit Tests** - Test coverage for all handlers
3. **Decorators** - Common validations (requires_combat, requires_stamina)
4. **Base Classes** - Handler base class with common functionality
5. **Event System** - Decouple actions from responses
## Contributing
When adding new features:
1. Choose the appropriate handler module (or create new one)
2. Follow the existing pattern
3. Add docstrings
4. Log important actions
5. Handle errors gracefully
6. Update this documentation
## Questions?
See also:
- `REFACTORING_NOTES.md` - Refactoring details
- `HANDLER_REFACTORING_SUMMARY.md` - Before/after comparison
- `README.md` - Project overview

180
docs/development/HANDLER_REFACTORING_SUMMARY.md Normal file
View File

@@ -0,0 +1,180 @@
# Handler Refactoring Summary
## Code Metrics
### Before Refactoring
- **Single file:** `bot/handlers.py` (~1,308 lines)
- **Giant function:** `button_handler()` with 1000+ lines of if/elif chains
- **Maintainability:** Very difficult to navigate and modify
### After Refactoring
- **7 organized modules:** Total ~1,786 lines (well-structured)
- **Main router:** `handlers.py` (377 lines) - clean routing logic
- **6 specialized modules:**
- `action_handlers.py` (367 lines) - World interaction
- `inventory_handlers.py` (355 lines) - Inventory management
- `corpse_handlers.py` (234 lines) - Corpse looting
- `combat_handlers.py` (171 lines) - Combat actions
- `profile_handlers.py` (147 lines) - Profile & stats
- `pickup_handlers.py` (135 lines) - Item pickup
## Architecture
```
bot/
├── handlers.py # Main router & utilities
│ ├── send_or_edit_with_image()
│ ├── start()
│ ├── export_map()
│ ├── spawn_stats()
│ └── button_handler() # Routes to specialized handlers
│
├── action_handlers.py # World & Inspection
│ ├── get_player_status_text()
│ ├── handle_inspect_area()
│ ├── handle_attack_wandering()
│ ├── handle_inspect_interactable()
│ ├── handle_action()
│ ├── handle_main_menu()
│ ├── handle_move_menu()
│ └── handle_move()
│
├── inventory_handlers.py # Inventory Management
│ ├── handle_inventory_menu()
│ ├── handle_inventory_item()
│ ├── handle_inventory_use()
│ ├── handle_inventory_drop()
│ ├── handle_inventory_equip()
│ └── handle_inventory_unequip()
│
├── pickup_handlers.py # Item Collection
│ ├── handle_pickup_menu()
│ └── handle_pickup()
│
├── combat_handlers.py # Combat System
│ ├── handle_combat_attack()
│ ├── handle_combat_flee()
│ ├── handle_combat_use_item_menu()
│ ├── handle_combat_use_item()
│ └── handle_combat_back()
│
├── profile_handlers.py # Character Stats
│ ├── handle_profile()
│ ├── handle_spend_points_menu()
│ └── handle_spend_point()
│
└── corpse_handlers.py # Looting System
├── handle_loot_player_corpse()
├── handle_take_corpse_item()
├── handle_scavenge_npc_corpse()
└── handle_scavenge_corpse_item()
```
## Key Improvements
### 1. Separation of Concerns
Each module handles a specific domain of functionality:
- **Action Handlers** → World exploration & interaction
- **Inventory Handlers** → Item management
- **Combat Handlers** → Battle mechanics
- **Profile Handlers** → Character progression
- **Corpse Handlers** → Looting system
- **Pickup Handlers** → Item collection
### 2. Single Responsibility Principle
Each function has one clear purpose:
- ✅ `handle_inventory_use()` - Use items
- ✅ `handle_combat_attack()` - Attack in combat
- ✅ `handle_pickup()` - Pick up items
- ❌ ~~`button_handler()` - Do everything~~
### 3. Improved Error Handling
```python
# Centralized error handling in router
try:
if action_type == "inspect_area":
await handle_inspect_area(query, user_id, player)
# ... more routes
except Exception as e:
logger.error(f"Error handling {action_type}: {e}", exc_info=True)
await query.answer("An error occurred.", show_alert=True)
```
### 4. Better Code Navigation
- Jump to specific functionality in seconds
- IDE autocomplete works better
- Easier to review code changes
- Reduced cognitive load
### 5. Testability
Each handler can now be tested independently:
```python
# Easy to test
await handle_inventory_use(mock_query, user_id, player, data)
# vs. testing 1000 lines of if/elif
```
## Migration Path
All functionality has been preserved. The refactoring only changed the organization, not the behavior.
### Verified Compatible
- ✅ All action types still handled
- ✅ Same function signatures
- ✅ Same error handling behavior
- ✅ No breaking changes to external code
### Backup Files
Original files saved in `backups/`:
- `handlers_original.py`
- `handlers.py.old`
## Future Enhancements
1. **Add Type Hints**
```python
async def handle_inventory_use(
query: CallbackQuery,
user_id: int,
player: dict,
data: list[str]
) -> None:
```
2. **Create Base Handler Class**
```python
class BaseHandler:
def __init__(self, query, user_id, player):
self.query = query
self.user_id = user_id
self.player = player
```
3. **Add Unit Tests**
```python
def test_handle_inventory_use():
# Test consumable usage
# Test inventory updates
# Test error cases
```
4. **Add Handler Decorators**
```python
@requires_combat
async def handle_combat_attack(...):
@requires_stamina(10)
async def handle_action(...):
```
## Conclusion
This refactoring transforms a monolithic 1,308-line file with a 1000+ line function into a well-organized, modular architecture with:
- ✅ Clear separation of concerns
- ✅ Easy navigation and maintenance
- ✅ Better error handling
- ✅ Improved testability
- ✅ No breaking changes
**Result:** The codebase is now much easier to understand, modify, and extend.

127
docs/development/REFACTORING_NOTES.md Normal file
View File

@@ -0,0 +1,127 @@
# Code Refactoring - Handler Organization
## Overview
The `bot/handlers.py` file has been refactored to improve code organization, readability, and maintainability. The massive `button_handler` function (previously 1000+ lines) has been broken down into logical, focused modules.
## New Structure
### Main Module: `bot/handlers.py`
**Purpose:** Core routing and utility functions
- `send_or_edit_with_image()` - Image handling utility
- `start()` - /start command handler
- `export_map()` - Admin command for map export
- `spawn_stats()` - Admin command for spawn statistics
- `button_handler()` - Main router that delegates to specific handlers
### Action Handlers: `bot/action_handlers.py`
**Purpose:** World interaction and inspection
- `get_player_status_text()` - Generate player status display
- `handle_inspect_area()` - Inspect current location
- `handle_attack_wandering()` - Attack wandering enemies
- `handle_inspect_interactable()` - Inspect objects
- `handle_action()` - Perform actions on interactables
- `handle_main_menu()` - Return to main menu
- `handle_move_menu()` - Show movement options
- `handle_move()` - Handle player movement
### Inventory Handlers: `bot/inventory_handlers.py`
**Purpose:** Inventory management
- `handle_inventory_menu()` - Show inventory
- `handle_inventory_item()` - Show item details
- `handle_inventory_use()` - Use consumable items
- `handle_inventory_drop()` - Drop items to world
- `handle_inventory_equip()` - Equip items
- `handle_inventory_unequip()` - Unequip items
### Pickup Handlers: `bot/pickup_handlers.py`
**Purpose:** Item collection from world
- `handle_pickup_menu()` - Show pickup options
- `handle_pickup()` - Pick up dropped items
### Combat Handlers: `bot/combat_handlers.py`
**Purpose:** Combat actions
- `handle_combat_attack()` - Attack enemy
- `handle_combat_flee()` - Attempt to flee
- `handle_combat_use_item_menu()` - Show usable items in combat
- `handle_combat_use_item()` - Use item during combat
- `handle_combat_back()` - Return to combat menu
### Profile Handlers: `bot/profile_handlers.py`
**Purpose:** Character profile and stat management
- `handle_profile()` - Show player profile
- `handle_spend_points_menu()` - Show stat point menu
- `handle_spend_point()` - Spend stat points
### Corpse Handlers: `bot/corpse_handlers.py`
**Purpose:** Looting corpses
- `handle_loot_player_corpse()` - Show player corpse loot
- `handle_take_corpse_item()` - Take item from player corpse
- `handle_scavenge_npc_corpse()` - Show NPC corpse loot
- `handle_scavenge_corpse_item()` - Scavenge from NPC corpse
## Benefits
### 1. **Improved Readability**
- Each module focuses on a specific domain
- Function names clearly describe their purpose
- Easier to find and understand specific functionality
### 2. **Better Maintainability**
- Changes to one feature don't affect others
- Easier to test individual components
- Reduced risk of merge conflicts
### 3. **Logical Organization**
- Related functions grouped together
- Clear separation of concerns
- Follows Single Responsibility Principle
### 4. **Easier Navigation**
- Jump to specific functionality quickly
- No need to scroll through 1000+ lines
- Clear module imports show dependencies
### 5. **Error Handling**
- Centralized error handling in router
- Consistent error messages
- Better logging
## Migration Notes
### Old Structure
```python
async def button_handler():
# 1000+ lines of if/elif statements
if action_type == "inspect_area":
# 50 lines of code
elif action_type == "inventory_menu":
# 30 lines of code
# ... hundreds more lines
```
### New Structure
```python
async def button_handler():
# Clean router - delegates to specialized handlers
if action_type == "inspect_area":
await handle_inspect_area(query, user_id, player)
elif action_type == "inventory_menu":
await handle_inventory_menu(query, user_id, player)
```
## Future Improvements
1. **Add unit tests** for each handler module
2. **Create handler base class** for common functionality
3. **Add type hints** for better IDE support
4. **Document return types** and error conditions
5. **Add handler decorators** for common validations
## Backup Files
Old versions have been preserved in `backups/`:
- `handlers_original.py` - Last version before refactoring
- `handlers.py.old` - Additional backup
## Date
Refactored: October 19, 2025

240
docs/development/UI_EXAMPLES.md Normal file
View File

@@ -0,0 +1,240 @@
# Visual UI Examples
## Before & After Comparison
### Main Menu / Player Status
#### Before
```
Location: Downtown Plaza
Status: Healthy
❤️ HP: 70/100 | ⚡️ Stamina: 50/100
🎒 Load: 15/50 kg | 30/100 vol
⚔️ Equipped: 🔧 Wrench, 🎒 Backpack
━━━━━━━━━━━━━━━━━━━━
A desolate plaza, once bustling with life...
```
#### After
```
📍 Location: Downtown Plaza
❤️ HP: ███████░░░ 70% (70/100)
⚡ Stamina: █████░░░░░ 50% (50/100)
🎒 Load: 15/50 kg | 30/100 vol
⚔️ Equipped: 🔧 Wrench, 🎒 Backpack
━━━━━━━━━━━━━━━━━━━━
A desolate plaza, once bustling with life...
```
### Player Profile
#### Before
```
👤 PlayerName
━━━━━━━━━━━━━━━━━━━━
Level: 5
XP: 240/600 (40%)
⭐ Unspent Points: 2
Health: 70/100 ❤️
Stamina: 50/100 ⚡
Stats:
💪 Strength: 12
🏃 Agility: 8
💚 Endurance: 10
🧠 Intellect: 5
Combat:
⚔️ Base Damage: 13
🛡️ Flee Chance: 58%
💚 Stamina Regen: 2/cycle
```
#### After
```
👤 PlayerName
━━━━━━━━━━━━━━━━━━━━
Level: 5
⭐ XP: ████░░░░░░ 40% (240/600)
💎 Unspent Points: 2
❤️ HP: ███████░░░ 70% (70/100)
⚡ Stamina: █████░░░░░ 50% (50/100)
Stats:
💪 Strength: 12
🏃 Agility: 8
💚 Endurance: 10
🧠 Intellect: 5
Combat:
⚔️ Base Damage: 13
🛡️ Flee Chance: 58%
💚 Stamina Regen: 2/cycle
```
## Visual States
### Critical Health
```
❤️ HP: ██░░░░░░░░ 20% (20/100)
```
### Low Stamina
```
⚡ Stamina: ██░░░░░░░░ 20% (20/100)
```
### Half Values
```
❤️ HP: █████░░░░░ 50% (50/100)
⚡ Stamina: █████░░░░░ 50% (50/100)
```
### Full Values
```
❤️ HP: ██████████ 100% (100/100)
⚡ Stamina: ██████████ 100% (100/100)
```
### Empty/Dead
```
❤️ HP: ░░░░░░░░░░ 0% (0/100)
⚡ Stamina: ░░░░░░░░░░ 0% (0/100)
```
## XP Progress Examples
### Just Leveled Up
```
⭐ XP: ░░░░░░░░░░ 0% (0/600)
```
### Quarter Progress
```
⭐ XP: ██░░░░░░░░ 25% (150/600)
```
### Half Progress
```
⭐ XP: █████░░░░░ 50% (300/600)
```
### Almost Level Up
```
⭐ XP: █████████░ 95% (570/600)
```
## Character Build Examples
### Tank Build (High HP/Endurance)
```
👤 TankWarrior
━━━━━━━━━━━━━━━━━━━━
Level: 10
⭐ XP: ███████░░░ 65% (780/1200)
❤️ HP: ████████░░ 80% (160/200)
⚡ Stamina: ██████░░░░ 60% (90/150)
Stats:
💪 Strength: 15
🏃 Agility: 5
💚 Endurance: 20
🧠 Intellect: 5
```
### Glass Cannon (High Damage, Low HP)
```
👤 GlassCannon
━━━━━━━━━━━━━━━━━━━━
Level: 10
⭐ XP: ███████░░░ 65% (780/1200)
❤️ HP: ██████░░░░ 60% (60/100)
⚡ Stamina: ████████░░ 80% (120/150)
Stats:
💪 Strength: 25
🏃 Agility: 10
💚 Endurance: 5
🧠 Intellect: 5
```
### Balanced Build
```
👤 AllRounder
━━━━━━━━━━━━━━━━━━━━
Level: 10
⭐ XP: ███████░░░ 65% (780/1200)
❤️ HP: ███████░░░ 70% (105/150)
⚡ Stamina: ███████░░░ 70% (88/125)
Stats:
💪 Strength: 15
🏃 Agility: 12
💚 Endurance: 12
🧠 Intellect: 6
```
## Combat Display Examples
### Player vs Enemy (Active Combat)
```
⚔️ Combat with 🐕 Feral Dog!
A mangy, aggressive dog with matted fur...
🐕 Enemy HP: ██████░░░░ 60% (30/50)
❤️ Your HP: ███████░░░ 70% (70/100)
🎯 Your turn! What will you do?
[⚔️ Attack] [🏃 Flee] [💊 Use Item]
```
### Low Health Warning
```
⚠️ A 🧟 Infected Human appears!
A shambling, infected survivor...
🧟 Enemy HP: ████████░░ 80% (80/100)
❤️ Your HP: ██░░░░░░░░ 20% (20/100) ⚠️ CRITICAL!
🎯 Your turn! What will you do?
```
## Inventory Display
### Inventory Load Bars (Future Enhancement)
```
🎒 Your Inventory:
📊 Weight: █████░░░░░ 50% (25/50 kg)
📦 Volume: ███░░░░░░░ 30% (30/100 vol)
Items:
🔧 Wrench x1
🥫 Canned Food x3
💊 Bandage x5
```
## Mobile Display
All bars are designed to work perfectly on mobile:
- Unicode characters supported on all platforms
- Monospaced alignment for consistent display
- Clear even on small screens
- Works in all Telegram clients
---
**Implementation Date:** October 19, 2025
**Status:** ✅ Live in Production

297
docs/development/VISUAL_IMPROVEMENTS.md Normal file
View File

@@ -0,0 +1,297 @@
# Visual UI Improvements
## Overview
This document describes the visual improvements made to the game's user interface, particularly the addition of progress bars for stats.
## Progress Bars
### Implementation
Visual progress bars have been added to display HP, Stamina, and XP using Unicode block characters.
### Format
```
❤️ HP: ███████░░░ 70% (70/100)
⚡ Stamina: █████░░░░░ 50% (50/100)
⭐ XP: ████░░░░░░ 40% (240/600)
```
### Components
- **Emoji** - Visual indicator of stat type
- **Label** - Stat name (HP, Stamina, etc.)
- **Progress Bar** - Visual representation using █ (filled) and ░ (empty)
- **Percentage** - Numeric percentage value
- **Values** - Current/Maximum in parentheses
### Characters Used
- `█` (U+2588) - Full Block - Represents filled portion
- `░` (U+2591) - Light Shade - Represents empty portion
## Utility Functions
### `create_progress_bar()`
Creates a visual progress bar from current and maximum values.
**Signature:**
```python
def create_progress_bar(
current: int,
maximum: int,
length: int = 10,
filled_char: str = "█",
empty_char: str = "░"
) -> str
```
**Parameters:**
- `current` - Current value of the stat
- `maximum` - Maximum possible value
- `length` - Number of characters in the bar (default: 10)
- `filled_char` - Character for filled portion (default: █)
- `empty_char` - Character for empty portion (default: ░)
**Returns:**
String containing the progress bar
**Examples:**
```python
>>> create_progress_bar(75, 100)
"███████░░░"
>>> create_progress_bar(0, 100)
"░░░░░░░░░░"
>>> create_progress_bar(100, 100)
"██████████"
>>> create_progress_bar(33, 100, length=6)
"██░░░░"
```
### `format_stat_bar()`
Formats a complete stat line with label, bar, and values.
**Signature:**
```python
def format_stat_bar(
label: str,
emoji: str,
current: int,
maximum: int,
bar_length: int = 10
) -> str
```
**Parameters:**
- `label` - Name of the stat (e.g., "HP", "Stamina")
- `emoji` - Emoji to display (e.g., "❤️", "⚡")
- `current` - Current value
- `maximum` - Maximum value
- `bar_length` - Length of the progress bar (default: 10)
**Returns:**
Formatted string with emoji, label, bar, percentage, and values
**Examples:**
```python
>>> format_stat_bar("HP", "❤️", 75, 100)
"❤️ HP: ███████░░░ 75% (75/100)"
>>> format_stat_bar("Stamina", "⚡", 50, 100)
"⚡ Stamina: █████░░░░░ 50% (50/100)"
>>> format_stat_bar("XP", "⭐", 240, 600)
"⭐ XP: ████░░░░░░ 40% (240/600)"
```
## Updated Displays
### Player Status (Main Menu)
**Before:**
```
Location: Downtown Plaza
Status: Healthy
❤️ HP: 70/100 | ⚡️ Stamina: 50/100
🎒 Load: 5/50 kg | 10/100 vol
```
**After:**
```
📍 Location: Downtown Plaza
❤️ HP: ███████░░░ 70% (70/100)
⚡ Stamina: █████░░░░░ 50% (50/100)
🎒 Load: 5/50 kg | 10/100 vol
```
### Player Profile
**Before:**
```
👤 PlayerName
━━━━━━━━━━━━━━━━━━━━
Level: 5
XP: 240/600 (40%)
Health: 70/100 ❤️
Stamina: 50/100 ⚡
```
**After:**
```
👤 PlayerName
━━━━━━━━━━━━━━━━━━━━
Level: 5
⭐ XP: ████░░░░░░ 40% (240/600)
❤️ HP: ███████░░░ 70% (70/100)
⚡ Stamina: █████░░░░░ 50% (50/100)
```
## Benefits
### 1. **Visual Clarity**
- Instant understanding of stat levels at a glance
- No mental math required to assess health/stamina
- Color-coded through emojis (❤️ = health, ⚡ = stamina)
### 2. **Better Gameplay**
- Players can quickly assess danger
- Easy to see when healing/rest is needed
- Visual feedback is more engaging
### 3. **Mobile Friendly**
- Unicode characters work on all platforms
- No images required
- Works in all Telegram clients
### 4. **Accessibility**
- Percentage and numeric values still provided
- Multiple representations of same data
- Screen readers can parse text values
## Customization
### Changing Bar Length
Modify the `bar_length` parameter:
```python
# Shorter bars (5 characters)
format_stat_bar("HP", "❤️", 75, 100, bar_length=5)
# Output: "❤️ HP: ███░░ 75% (75/100)"
# Longer bars (20 characters)
format_stat_bar("HP", "❤️", 75, 100, bar_length=20)
# Output: "❤️ HP: ███████████████░░░░░ 75% (75/100)"
```
### Alternative Characters
Different visual styles can be achieved with different characters:
**Style 1 - Blocks (Default):**
```python
create_progress_bar(50, 100, filled_char="█", empty_char="░")
# Output: "█████░░░░░"
```
**Style 2 - Squares:**
```python
create_progress_bar(50, 100, filled_char="■", empty_char="□")
# Output: "■■■■■□□□□□"
```
**Style 3 - Circles:**
```python
create_progress_bar(50, 100, filled_char="●", empty_char="○")
# Output: "●●●●●○○○○○"
```
**Style 4 - Bars:**
```python
create_progress_bar(50, 100, filled_char="▰", empty_char="▱")
# Output: "▰▰▰▰▰▱▱▱▱▱"
```
## Color Variations
While Telegram doesn't support custom colors in text, we use emoji for color coding:
- ❤️ Red heart = Health (HP)
- ⚡ Lightning = Energy (Stamina)
- ⭐ Star = Experience (XP)
- 🎒 Backpack = Inventory capacity
- 💎 Gem = Unspent points
## Performance
### Optimization
- Progress bars are generated on-demand
- No database storage required
- Minimal computation (simple division and multiplication)
- No external dependencies
### Caching
Progress bars are not cached as they change frequently and are cheap to generate.
## Future Enhancements
### Potential Improvements
1. **Color thresholds** - Different bars at low health
```
❤️ HP: ██░░░░░░░░ 20% (20/100) ⚠️ LOW
```
2. **Animated transitions** - Show changes over time
(Limited by Telegram's edit rate limits)
3. **More stats** - Apply to other numeric values
- Hunger bar
- Thirst bar
- Status effect duration
4. **Inventory load bars**
```
🎒 Weight: █████░░░░░ 50% (25/50 kg)
📦 Volume: ███░░░░░░░ 30% (30/100 vol)
```
## Testing
### Test Cases
```python
# Test edge cases
assert create_progress_bar(0, 100) == "░░░░░░░░░░"
assert create_progress_bar(100, 100) == "██████████"
assert create_progress_bar(50, 100) == "█████░░░░░"
# Test invalid values
assert create_progress_bar(-10, 100) == "░░░░░░░░░░" # Negative clamped to 0
assert create_progress_bar(150, 100) == "██████████" # Over max clamped to 100%
# Test zero maximum
assert create_progress_bar(10, 0) == "░░░░░░░░░░" # Avoid division by zero
```
## Files Modified
- **`bot/utils.py`** - Added utility functions
- **`bot/action_handlers.py`** - Updated `get_player_status_text()`
- **`bot/profile_handlers.py`** - Updated `handle_profile()`
## Migration
No database migration required - this is purely a display change.
## Rollback
To revert to the old format, simply remove the `format_stat_bar()` calls and use plain text:
```python
# Old format
status += f"❤️ HP: {player['hp']}/{player['max_hp']}\n"
# New format (can be reverted)
status += f"{format_stat_bar('HP', '❤️', player['hp'], player['max_hp'])}\n"
```
---
**Implementation Date:** October 19, 2025
**Status:** ✅ Complete and Deployed