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

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

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

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