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.