AppleHillsProduction/docs/card_system_migration_summary.md

# Card System Migration Summary

## Overview
Successfully migrated the card UI system from the old wrapper-based approach (AlbumCard, FlippableCard) to the new state-based Card system using PixelPlacement's StateMachine.

## Date
Migration completed: November 16, 2025

---

## Changes Made

### 1. CardDisplay.cs - Simplified Click Handling
**Changes:**
- Removed `_isPreviewMode` and `_previewSlot` tracking
- Removed `SetPreviewMode()` and preview visual methods (`SetPreviewVisuals`, `ClearPreviewVisuals`)
- Simplified `OnPointerClick()` to only emit `OnCardClicked` event
- No more parent-seeking or type-checking logic

**Impact:**
- CardDisplay is now a pure "dumb" visual renderer + click detector
- Any wrapper can subscribe to click events without tight coupling
- Preview functionality moved to card states

---

### 2. AlbumCardSlot.cs - Updated to New Card System
**Changes:**
- Changed from `AlbumCard` references to `StateMachine.Card`
- Removed `IPointerClickHandler` interface (no more manual preview clicks)
- Removed all preview-related fields and methods:
  - `previewCardDisplay`
  - `_isPreviewShowing`
  - `_previewOriginalScale`
  - `SetupPreviewCard()`
  - `ShowPreview()`
  - `HidePreview()`
  - `OnPointerClick()`
  - `DismissPreview()`
- Updated `SpawnCard()` to use `Card.SetupForAlbumSlot()` with `PlacedInSlotState`
- Removed registration with AlbumViewPage (no longer needed)
- Changed `albumCardPrefab` field to `cardPrefab`

**Impact:**
- Slots now spawn cards in the `PlacedInSlotState` directly
- Preview functionality will be handled by card states if needed in the future
- Cleaner, simpler slot logic focused only on validation and spawning

---

### 3. AlbumViewPage.cs - Removed Legacy Support
**Changes:**
- Removed legacy `AlbumCard` registration methods:
  - `RegisterAlbumCard()`
  - `UnregisterAlbumCard()`
  - `OnCardEnlargeRequested(AlbumCard)`
  - `OnCardShrinkRequested(AlbumCard)`
- Removed slot preview helper methods:
  - `ShowSlotPreview()`
  - `HideSlotPreview()`
- Kept only new Card system methods:
  - `RegisterCardInAlbum(StateMachine.Card)`
  - `UnregisterCardInAlbum(StateMachine.Card)`
  - `OnCardEnlargeRequested(CardAlbumEnlargedState)`
  - `OnCardShrinkRequested(CardAlbumEnlargedState)`

**Impact:**
- Page only manages backdrop and reparenting for card enlarge states
- No more manual preview management
- Cleaner event-based architecture

---

### 4. BoosterOpeningPage.cs - Already Updated
**Status:**
- Already using new `StateMachine.Card` system
- Uses `CardContext` for setup and event handling
- No changes required - already migrated!

**Current Flow:**
1. Spawns Card prefab with CardContext
2. Calls `context.SetupCard()` and `card.SetupForBoosterReveal()`
3. Subscribes to `context.OnFlipComplete` and `context.OnCardInteractionComplete`
4. Cards handle their own flip and reveal states

---

### 5. DEPRECATED Folder - Deleted
**Deleted Classes:**
- `AlbumCard.cs`
- `FlippableCard.cs`
- `AlbumCardPlacementDraggable.cs`
- `CardDraggable.cs`
- `CardDraggableVisual.cs`
- `CardInteractionHandler.cs`

**Justification:**
- No longer referenced anywhere in the codebase
- All functionality replaced by state-based Card system
- Keeping them would cause confusion

---

## Architecture Benefits

### Event-Based Communication
- **Old:** Parent-seeking, type-checking, manual forwarding
- **New:** Clean pub/sub pattern, decoupled components

### State Management
- **Old:** Multiple wrapper classes (FlippableCard → AlbumCard → CardDisplay)
- **New:** Single Card component + isolated state objects

### Code Reuse
- **Old:** Repeated animation/behavior code in each wrapper
- **New:** Shared CardAnimator, reusable state behaviors

### Flexibility
- **Old:** Hard to add new card contexts (preview, enlarged, etc.)
- **New:** Just add a new state - no wrapper changes needed

---

## Current Card State Flow

### Booster Opening Flow
1. Spawn Card with `SetupForBoosterReveal()` → starts in `IdleState`
2. User clicks → transitions to `FlippingState`
3. Flip completes → transitions to `RevealedState` (new/repeat logic)
4. User interacts → card animates to album icon, destroyed

### Album Placement Flow
1. Spawn Card with `SetupForAlbumPlacement()` → starts in `RevealedState`
2. User drags → transitions to `DraggingState`
3. Dropped in slot → transitions to `PlacedInSlotState`
4. User clicks placed card → transitions to `AlbumEnlargedState`
5. User dismisses → back to `PlacedInSlotState`

### Album Slot Auto-Spawn
1. AlbumCardSlot checks owned cards on Enable
2. If owned, spawns Card with `SetupForAlbumSlot()` → starts in `PlacedInSlotState`
3. Card sits in slot, ready for enlarge interaction

---

## What's Next

### Prefab Setup Required
You'll need to update your prefabs to use the new Card structure:

**Old Prefab Structure:**
```
FlippableCard (or AlbumCard)
└── CardDisplay
    └── [visual elements]
```

**New Prefab Structure:**
```
Card (Card.cs component)
├── CardDisplay (visual renderer)
│   └── [visual elements: image, frame, overlay, etc.]
└── StateMachine (AppleMachine component)
    ├── IdleState (CardIdleState)
    ├── FlippingState (CardFlippingState)
    ├── RevealedState (CardRevealedState)
    ├── DraggingState (CardDraggingState)
    ├── PlacedInSlotState (CardPlacedInSlotState)
    └── AlbumEnlargedState (CardAlbumEnlargedState)
```

### Configuration References
Make sure to update these references in your scenes:
- **BoosterOpeningPage:** `cardPrefab` field → assign new Card prefab
- **AlbumViewPage:** `cardPrefab` field → assign new Card prefab
- **AlbumCardSlot:** `cardPrefab` field → assign new Card prefab

---

## Testing Checklist

- [ ] Booster opening flow works correctly
- [ ] Cards flip and reveal properly
- [ ] New/repeat card logic displays correctly
- [ ] Cards can be dragged from pending list to album slots
- [ ] Cards snap into album slots correctly
- [ ] Placed cards can be enlarged when clicked
- [ ] Enlarged cards can be dismissed
- [ ] Empty slots no longer show preview (feature removed for now)
- [ ] No console errors or null references

---

## Notes

### Preview Functionality
The old preview system (showing locked cards in empty slots) has been removed. If you want to re-implement this:
1. Create a new `EmptySlotPreviewState`
2. Have empty AlbumCardSlots spawn a Card in this state
3. State handles the greyed-out visuals and enlarge/shrink

### Backwards Compatibility
**None.** This is a breaking change. Old prefabs using AlbumCard/FlippableCard will not work and must be updated.

### Performance
The new system is more efficient:
- Fewer component lookups (no parent-seeking)
- State objects pooled per card (not created/destroyed)
- Cleaner event subscription (no manual chain management)

---

## Questions?
Refer to the implementation plan documents or the state machine architecture document for more details.