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

140
docs/README.md Normal file
View File

@@ -0,0 +1,140 @@
# Echoes of the Ashes - Documentation Index
## 📚 Documentation Overview
This directory contains all project documentation organized by category.
## 📁 Directory Structure
### `/docs/development/`
Technical documentation for developers
- **[BOT_MODULE.md](development/BOT_MODULE.md)** - Bot module architecture and handler system
- **[HANDLER_REFACTORING_SUMMARY.md](development/HANDLER_REFACTORING_SUMMARY.md)** - Code refactoring summary
- **[REFACTORING_NOTES.md](development/REFACTORING_NOTES.md)** - Detailed refactoring notes
- **[VISUAL_IMPROVEMENTS.md](development/VISUAL_IMPROVEMENTS.md)** - UI improvements and progress bars
- **[UI_EXAMPLES.md](development/UI_EXAMPLES.md)** - Before/after UI comparisons and visual mockups
### `/docs/game/`
Game design and mechanics documentation
- **[MECHANICS.md](game/MECHANICS.md)** - Complete game mechanics overview
### `/docs/api/`
API documentation and integration guides
- **Telegram Bot API** - Bot command reference
- **Database Schema** - Data models and relationships
- **Web Map Editor** - Map editor API and usage
## 🚀 Quick Links
### For Developers
- [Bot Module Documentation](development/BOT_MODULE.md) - Start here to understand the codebase
- [Handler System](development/HANDLER_REFACTORING_SUMMARY.md) - Handler architecture
- [Contributing Guide](../README.md#contributing) - How to contribute
### For Game Designers
- [Game Mechanics](game/) - Game systems and balance
- [World Editor](../web-map/README.md) - Map editing guide
### For Players
- [README](../README.md) - Project overview and setup
- [Game Guide](game/) - How to play
## 📝 Documentation Standards
### Markdown Guidelines
- Use clear, descriptive headings
- Include code examples where relevant
- Keep lines under 100 characters for readability
- Use emoji sparingly for visual organization
### File Naming
- Use `SCREAMING_SNAKE_CASE.md` for major documentation
- Use `PascalCase.md` for component-specific docs
- Use `kebab-case.md` for guides and tutorials
### Document Structure
```markdown
# Title
## Overview
Brief description
## Table of Contents
- [Section 1](#section-1)
- [Section 2](#section-2)
## Content
Detailed information
## See Also
Related documentation
```
## 🔄 Recent Updates
### October 19, 2025
- ✅ Reorganized documentation into structured folders
- ✅ Created documentation index (this file)
- ✅ Moved development docs from root to docs/development/
- ✅ **Added visual HP/Stamina bars** - Progress bars for better UI feedback
- ✅ Refactored handler system into modular architecture
- ✅ Created comprehensive bot module documentation
- ✅ Added utility functions for visual progress displays
### October 18, 2025
- ✅ Refactored handler system into modular architecture
- ✅ Created comprehensive bot module documentation
- ✅ Added refactoring notes and summaries
## 📖 Contributing to Documentation
When adding new documentation:
1. **Choose the right folder:**
- `development/` - Technical/code documentation
- `game/` - Game design and mechanics
- `api/` - API references and integration
2. **Update this index** with links to new documents
3. **Follow naming conventions** as outlined above
4. **Include:**
- Clear title and overview
- Table of contents for longer docs
- Code examples where applicable
- Links to related documentation
5. **Keep it updated** - Documentation should match the code
## 🔍 Finding Documentation
### By Topic
- **Setup & Installation** → [README.md](../README.md)
- **Bot Development** → [development/BOT_MODULE.md](development/BOT_MODULE.md)
- **Code Architecture** → [development/](development/)
- **Game Mechanics** → [game/](game/)
- **Map Editor** → [../web-map/README.md](../web-map/README.md)
- **Database** → [api/](api/)
### By File Type
- **README files** - Quick overviews and getting started guides
- **Technical specs** - Detailed architecture and implementation
- **Guides** - Step-by-step tutorials
- **Reference** - API documentation and data schemas
## 📧 Questions?
If you can't find what you're looking for:
1. Check the [main README](../README.md)
2. Search through existing documentation
3. Look at code comments and docstrings
4. Create an issue for missing documentation
---
**Last Updated:** October 19, 2025
**Maintained by:** Development Team

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

221
docs/game/MECHANICS.md Normal file
View File

@@ -0,0 +1,221 @@
# Game Mechanics Overview
## Core Systems
### 1. Health & Stamina System
#### Health Points (HP)
- **Purpose:** Measure of character's life force
- **Starting Value:** 100 HP
- **Range:** 0 to max_hp
- **Death:** Occurs when HP reaches 0
- **Regeneration:** Does not auto-regenerate (requires items or rest)
- **Display:** Visual bar with percentage
```
❤️ HP: ███████░░░ 70% (70/100)
```
#### Stamina
- **Purpose:** Resource for actions and movement
- **Starting Value:** 100 Stamina
- **Range:** 0 to max_stamina
- **Usage:**
- Movement between locations (varies by distance and inventory weight)
- Actions on interactables (searching, opening, etc.)
- **Regeneration:** Passive over time (1 + endurance/10 per cycle)
- **Display:** Visual bar with percentage
```
⚡ Stamina: █████░░░░░ 50% (50/100)
```
### 2. Character Progression
#### Experience (XP)
- **Gained From:**
- Defeating enemies
- Completing actions
- Exploring new locations
- **Display:** Progress bar showing advancement to next level
```
⭐ XP: ████░░░░░░ 40% (240/600)
```
#### Leveling
- **Formula:** XP required = 100 * (level ^ 1.5)
- **Benefits:**
- Stat point to allocate
- Increased base damage
- Access to new areas
#### Stats
- **Strength (💪)**
- Increases melee damage
- Formula: Base Damage = 5 + (strength / 2) + level
- **Agility (🏃)**
- Increases flee chance in combat
- Formula: Flee Chance = 50% + (agility / 100)
- **Endurance (💚)**
- Increases max HP when leveled
- Increases stamina regeneration
- Formula: Stamina Regen = 1 + (endurance / 10)
- **Intellect (🧠)**
- Reserved for future mechanics
- May affect crafting, dialogue, etc.
#### Stat Points
- **Earned:** 1 point per level
- **Allocation Options:**
- +10 Max HP
- +5 Max Stamina
- +1 Strength
- +1 Agility
- +1 Endurance
- +1 Intellect
### 3. Inventory System
#### Capacity
- **Weight Limit:** 50 kg (base) + equipped backpack bonus
- **Volume Limit:** 100 vol (base) + equipped backpack bonus
- **Overencumbered:** Cannot pick up items when at capacity
- **Movement Penalty:** Higher inventory weight increases stamina cost for travel
#### Item Types
- **Weapons:** Equippable, adds damage
- **Armor:** Equippable, adds protection
- **Consumables:** Single-use, restores HP/Stamina
- **Tools:** Required for certain actions
- **Materials:** Crafting components (future)
- **Quest Items:** Special items for progression
#### Equipment Slots
- **Weapon:** Primary attack tool
- **Backpack:** Increases carrying capacity
- **Armor:** Protection (future implementation)
### 4. Combat System
#### Turn-Based Combat
- Player turn → NPC turn → Repeat until victory or defeat
#### Actions
- **Attack:** Deal damage to enemy
- **Flee:** Attempt to escape (chance-based)
- **Use Item:** Consume healing/buff items
#### Damage Calculation
```python
Base Damage = 5 + (strength / 2) + level
Weapon Damage = random(weapon_min, weapon_max)
Total Damage = Base Damage + Weapon Damage
```
#### Enemy Spawning
- **Static Spawns:** Fixed enemies at locations
- **Random Encounters:** Chance-based when moving
- **Wandering Enemies:** NPCs that patrol locations
#### Death & Respawn
- **Player Death:** Lose all inventory, respawn at start location
- **Corpses:** Player corpses can be looted by others (multiplayer aspect)
- **Enemy Death:** Drop loot, award XP
### 5. World Interaction
#### Locations
- **Types:** Safe zones, dangerous areas, dungeons
- **Connections:** Graph-based navigation
- **Images:** Visual representation of each location
- **Interactables:** Objects to search/interact with
#### Actions
- **Inspect Area:** View location details and items
- **Move:** Travel to connected locations
- **Search Objects:** Loot interactables for items
- **Attack Enemies:** Engage wandering NPCs
#### Cooldowns
- **Purpose:** Prevent infinite resource farming
- **Duration:** Varies by action (typically 5-30 minutes)
- **Per-Object:** Each interactable has independent cooldown
### 6. Item Collection
#### Dropped Items
- **Sources:**
- Enemy loot
- Interactable rewards
- Player-dropped items
- **Pickup:** Choose quantity to take
- **Capacity Check:** Must have room in inventory
#### Looting
- **NPC Corpses:**
- Requires tools for certain materials
- Random quantities
- Disappears when fully looted
- **Player Corpses:**
- Contains all inventory from death
- Can be looted by any player
- Encourages retrieval runs
## Game Loop
### Basic Cycle
1. **Explore** → Move to new location
2. **Inspect** → Find interactables and enemies
3. **Action** → Search, fight, or collect
4. **Manage** → Organize inventory, use items
5. **Progress** → Gain XP, level up, allocate stats
6. **Repeat**
### Resource Management
- Monitor HP and Stamina
- Use consumables strategically
- Rest when needed
- Manage inventory weight
### Risk vs. Reward
- Dangerous areas have better loot
- Higher-level enemies give more XP
- Overextending can lead to death
- Strategic retreats preserve progress
## Progression Path
### Early Game (Levels 1-5)
- Learn basic mechanics
- Gather starting equipment
- Explore safe zones
- Build initial stats
### Mid Game (Levels 6-15)
- Venture into dangerous areas
- Face tougher enemies
- Collect better equipment
- Specialize character build
### Late Game (Levels 16+)
- Challenge end-game content
- Optimize builds
- Collect rare items
- Explore all areas
## Future Mechanics
### Planned Features
- **Crafting System:** Combine materials into items
- **Quests:** Story-driven objectives
- **Factions:** Reputation and alliances
- **Trading:** Player-to-player economy
- **Skills:** Special abilities beyond stats
- **Housing:** Personal storage and rest areas
---
**Last Updated:** October 19, 2025
**Status:** Living document - Updated as mechanics evolve