AppleHillsProduction/docs/cards_wip/card_system_implementation_summary.md

# Card State Machine Implementation Summary

## Architecture Overview

**Isolated State Pattern** using Pixelplacement StateMachine:

```
Card (RectTransform - primary animation target)
├─ CardDisplay (always visible)
├─ CardContext (shared references)
├─ CardAnimator (reusable animations)
└─ CardStateMachine (AppleMachine)
    ├─ IdleState/
    ├─ FlippingState/
    │   └─ CardBackVisual ← State owns this
    ├─ EnlargedNewState/
    │   └─ NewCardBadge ← State owns this
    └─ EnlargedRepeatState/
        └─ ProgressBarUI ← State owns this
```

## Key Design Decisions

### 1. State-Owned Visuals
- State-specific GameObjects (CardBackVisual, NewCardBadge, etc.) are **children of their state GameObject**
- When state activates → children activate automatically
- When state deactivates → children deactivate automatically
- **No manual visibility management needed!**

### 2. Transform Animation
- **Root Card.transform** is animated for position/scale (affects all children via Unity hierarchy)
- **State child visuals** can be animated independently (e.g., rotating CardBackVisual during flip)
- States decide WHAT to animate, CardAnimator provides HOW

### 3. Shared Resources
- `CardContext` component provides states access to:
  - CardDisplay
  - CardAnimator
  - StateMachine
  - CardData
  - IsNewCard flag
- States call `_context.Animator.PlayFlip(...)` instead of duplicating tween code

### 4. State Transitions
States explicitly transition via `_context.StateMachine.ChangeState("StateName")`

Example flow:
```
IdleState 
  [click] → FlippingState 
    [flip complete + IsNew] → EnlargedNewState 
      [tap] → RevealedState
```

## Files Created

**Core Components:**
- `CardContext.cs` - Shared context accessible to all states
- `CardAnimator.cs` - Reusable animation methods
- `CardAnimationConfig.cs` - ScriptableObject for designer tweaks

**State Implementations:**
- `States/CardIdleState.cs` - Hover animation, click to flip
- `States/CardFlippingState.cs` - Owns CardBackVisual, flip animation
- `States/CardRevealedState.cs` - Waiting for interaction
- `States/CardEnlargedNewState.cs` - Owns NewCardBadge, tap to dismiss
- `States/CardEnlargedRepeatState.cs` - Owns ProgressBarUI, tap to dismiss

## Next Steps

1. **Create remaining states:**
   - `CardDraggingState` (for album placement flow)
   - `CardPlacedInSlotState` (album slot interaction)
   - `CardAlbumEnlargedState` (enlarge from album)

2. **Build Card prefab:**
   - Setup hierarchy with state children
   - Assign CardBackVisual, NewCardBadge, ProgressBarUI to states
   - Create CardAnimationConfig asset

3. **Migrate existing code:**
   - Update BoosterOpeningPage to use new Card
   - Update AlbumViewPage to use new Card
   - Remove old wrapper scripts (FlippableCard, AlbumCard, etc.)

## Benefits vs Old System

| Aspect | Old System | New System |
|--------|-----------|------------|
| Components per card | 5+ wrappers | 1 root + states |
| Animation code duplication | ~150 lines across 4 files | 0 (shared CardAnimator) |
| State tracking | 12+ boolean flags | 1 state machine |
| Visual element management | Manual SetActive calls | Automatic via state activation |
| Adding new behaviors | Modify 3-4 components | Add 1 new state GameObject |
| Prefab nesting | 5 layers deep | Flat (states as children) |
| Debugging state | Check 12 booleans | Look at active state name |

## Example: Adding New State

Want to add a "Trading" state where card shows trade UI?

**Old system:** Modify FlippableCard, AlbumCard, add new wrapper, update events, etc.

**New system:**
1. Create `CardTradingState.cs`
2. Add `TradingState` GameObject under CardStateMachine
3. Add trade UI as child of TradingState
4. Implement `OnEnterState()` to show UI
5. Call `ChangeState("TradingState")` from wherever needed

Done! No other files touched.