echoes-of-the-ash/docs/development/VISUAL_IMPROVEMENTS.md

# 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