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:

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:

>>> 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:

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:

>>> 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:

# 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):

create_progress_bar(50, 100, filled_char="█", empty_char="░")
# Output: "█████░░░░░"

Style 2 - Squares:

create_progress_bar(50, 100, filled_char="■", empty_char="□")
# Output: "■■■■■□□□□□"

Style 3 - Circles:

create_progress_bar(50, 100, filled_char="●", empty_char="○")
# Output: "●●●●●○○○○○"

Style 4 - Bars:

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

# 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:

# 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