echoes-of-the-ash/docs/EQUIPMENT_VISUAL_ENHANCEMENTS.md

Equipment Visual Enhancements

Summary

Enhanced the equipment system with visual improvements and better user feedback.

Changes Made

1. Visual Equipment Grid in Character Sheet ✅

Location: pwa/src/components/Game.tsx (lines 1211-1336)

Added a dedicated equipment display section that shows all 7 equipment slots in a visual grid layout:

      [Head]
[Shield] [Torso] [Backpack]
      [Weapon]
      [Legs]
      [Feet]

Features:

• Empty slots show placeholder icons and labels (e.g., 🪖 Head, ⚔️ Weapon)
• Filled slots show item emoji, name, and durability (e.g., 50/80)
• Click equipped items to unequip them
• Color-coded borders (red for equipment vs blue for inventory)
• Responsive layout with three-column middle row

Styling: pwa/src/components/Game.css (lines 1321-1412)

• .equipment-sidebar - Container styling
• .equipment-grid - Flex column layout
• .equipment-row - Individual slot rows
• .equipment-slot - Individual slot styling
• .equipment-slot.empty - Empty slot appearance (grayed out)
• .equipment-slot.filled - Filled slot appearance (red border, hover effects)

2. Improved Equip Messaging ✅

Location: api/main.py (lines 1108-1150)

Enhanced the equip endpoint to provide better feedback when replacing equipped items:

Before:

{
  "success": true,
  "message": "Equipped Rusty Knife"
}

After (when slot occupied):

{
  "success": true,
  "message": "Unequipped Old Knife, equipped Rusty Knife",
  "unequipped_item": "Old Knife"
}

Behavior:

• Automatically unequips the old item when equipping to an occupied slot
• No need for manual unequip first
• Clear messaging about what was replaced
• Old item returns to inventory

3. Durability Display in Item Info ✅

Location: pwa/src/components/Game.tsx (lines 1528-1542)

Added durability and tier information to the item info tooltip:

📦 Item Name
Weight: 2kg
Volume: 1L
⚔️ Damage: 3-7
🔧 Durability: 65/80  [NEW]
⭐ Tier: 2            [NEW]

Shows for all equipment items with durability tracking.

Known Limitations

Durability-Based Item Stacking ⚠️

Current Behavior: Items with different durability values currently stack together and show as a single inventory line. For example:

• Knife (80/80 durability)
• Knife (50/80 durability)

These appear as "Knife ×2" in inventory.

Why This Happens: The add_item_to_inventory() function in api/database.py (line 336) groups items by item_id only:

result = await session.execute(
    select(inventory).where(
        and_(
            inventory.c.player_id == player_id,
            inventory.c.item_id == item_id  # Only checks item type, not durability
        )
    )
)

Required Fix: To make items with different durability separate inventory lines, we would need to:

1. Change add_item_to_inventory() to check durability as well
2. Modify pickup, drop, and loot systems to handle durability-unique items
3. Update combat loot generation to create unique inventory rows per item
4. Adjust inventory queries to NOT group by durability for equipment

Complexity: This is a significant change that affects:

• Pickup system
• Drop system
• Combat loot
• Inventory management
• Database queries across multiple endpoints

Recommendation: Create this as a separate task since it requires careful testing to avoid:

• Breaking existing inventory stacks
• Creating duplicate item issues
• Affecting non-equipment items (consumables should still stack)

Testing Checklist

• Equipment grid displays in character section
• Empty slots show placeholder icons
• Equipped items show name and durability
• Click equipped item to unequip
• Equipping to occupied slot auto-unequips old item
• Message shows what was unequipped
• Item info tooltip shows durability and tier
• Styling matches game theme (red borders for equipment)
• Build succeeds without errors
• Durability stacking (NOT FIXED - see limitations above)

Files Modified

1. pwa/src/components/Game.tsx

   • Added equipment grid display (lines 1211-1336)
   • Added durability to item info tooltip (lines 1528-1542)

2. pwa/src/components/Game.css

   • Added equipment sidebar styling (lines 1321-1412)

3. api/main.py

   • Enhanced equip endpoint messaging (lines 1108-1150)

Next Steps (Optional Future Work)

1. Durability-Based Stacking:

   • Refactor add_item_to_inventory() to check durability
   • Update all item acquisition paths (pickup, loot, crafting)
   • Add migration to separate existing stacked items by durability
   • Test thoroughly with edge cases

2. Additional Equipment Items:

   • Create armor items for head, torso, legs, feet slots
   • Add shields for offhand slot
   • Balance encumbrance and stats

3. Weapon Upgrade System:

   • Repair mechanics (restore durability)
   • Upgrade mechanics (increase tier)
   • Crafting system integration

4. Visual Polish:

   • Add item rarity colors (common, uncommon, rare, epic)
   • Animated durability bars
   • Slot hover effects with preview
   • Drag-and-drop equip from inventory to equipment grid