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.