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:**
```json
{
  "success": true,
  "message": "Equipped Rusty Knife"
}
```

**After (when slot occupied):**
```json
{
  "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:

```python
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

- [x] Equipment grid displays in character section
- [x] Empty slots show placeholder icons
- [x] Equipped items show name and durability
- [x] Click equipped item to unequip
- [x] Equipping to occupied slot auto-unequips old item
- [x] Message shows what was unequipped
- [x] Item info tooltip shows durability and tier
- [x] Styling matches game theme (red borders for equipment)
- [x] 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