AppleHillsProduction/docs/card_prefab_setup_guide.md

# Card Prefab Setup Guide

## Quick Reference: Building the New Card Prefab

This guide shows you how to create a Card prefab compatible with the new state-based system.

---

## Prerequisites

Before starting, make sure you have:
- All Card state scripts compiled without errors
- CardDisplay.cs working
- Card.cs, CardContext.cs, CardAnimator.cs ready
- PixelPlacement StateMachine (AppleMachine) available

---

## Step 1: Create the Root GameObject

1. Create empty GameObject named "Card"
2. Add component: `Card.cs` (from `UI.CardSystem.StateMachine`)
3. Add component: `RectTransform` (if not already present)
4. Add component: `CanvasGroup` (optional, for fade effects)
5. Add component: `AspectRatioFitter` (optional, to maintain card proportions)

**Card.cs Settings:**
- Initial State: `IdleState`

---

## Step 2: Add CardContext Component

1. On the same "Card" GameObject, add: `CardContext.cs`
2. This component holds:
   - Card data reference
   - IsNew flag
   - IsClickable flag
   - RootTransform reference (auto-assigned)

**CardContext.cs Settings:**
- Root Transform: (leave empty, auto-assigned in Awake)

---

## Step 3: Add CardAnimator Component

1. On the same "Card" GameObject, add: `CardAnimator.cs`
2. This component will handle all animations

**CardAnimator.cs Settings:**
- Card Display: (assign in Step 4)
- Visual Root: (assign the Card GameObject itself)

---

## Step 4: Create CardDisplay Child

1. Create child GameObject under "Card" named "CardDisplay"
2. Add component: `CardDisplay.cs`
3. Add UI elements as children:
   - **CardImage** (Image) - main card artwork
   - **FrameImage** (Image) - rarity frame
   - **OverlayImage** (Image) - rarity overlay effects
   - **BackgroundImage** (Image) - zone background
   - **ZoneShapeImage** (Image) - zone symbol/shape
   - **CardNameText** (TextMeshProUGUI) - card name

**CardDisplay.cs Settings:**
- Assign all the UI element references above
- Visual Config: Assign your CardVisualConfig ScriptableObject

**Layout Tips:**
- Use anchors to stretch images to fill the card
- Layer order (back to front): Background → Zone Shape → Card Image → Frame → Overlay
- Make sure all images have "Raycast Target" enabled for click detection

---

## Step 5: Create CardBack Child (for flip animation)

1. Create child GameObject under "Card" named "CardBack"
2. Add component: `Image`
3. Assign your card back sprite
4. Position/scale to match CardDisplay size

**Settings:**
- Make sure it's initially hidden (will be shown by FlippingState)

---

## Step 6: Create StateMachine Child

1. Create child GameObject under "Card" named "StateMachine"
2. Add component: `AppleMachine` (from Pixelplacement)

**AppleMachine Settings:**
- Starting State: `IdleState`
- Debug: Enable if you want state transition logging

---

## Step 7: Create State Children

Under "StateMachine", create these child GameObjects:

### 7a. IdleState
- GameObject name: "IdleState"
- Add component: `CardIdleState.cs`
- Settings:
  - Hover Lift Distance: `20`
  - Hover Duration: `0.3`

### 7b. FlippingState
- GameObject name: "FlippingState"
- Add component: `CardFlippingState.cs`
- Settings:
  - Flip Duration: `0.6`
  - Next State After Flip: `RevealedState`

### 7c. RevealedState
- GameObject name: "RevealedState"
- Add component: `CardRevealedState.cs`
- Settings:
  - Scale: `1.5` (for NEW card emphasis)
  - Scale Duration: `0.5`

### 7d. DraggingState
- GameObject name: "DraggingState"
- Add component: `CardDraggingState.cs`
- Settings:
  - Drag Scale: `1.2`
  - Drag Rotation: `5` degrees

### 7e. PlacedInSlotState
- GameObject name: "PlacedInSlotState"
- Add component: `CardPlacedInSlotState.cs`
- Settings:
  - (Auto-configured when placed)

### 7f. AlbumEnlargedState
- GameObject name: "AlbumEnlargedState"
- Add component: `CardAlbumEnlargedState.cs`
- Settings:
  - Enlarged Scale: `2.5`
  - Scale Duration: `0.3`

---

## Step 8: Wire Up References

Go back to the root "Card" GameObject:

**Card.cs:**
- Context: Drag the Card GameObject (auto-finds CardContext)
- Animator: Drag the Card GameObject (auto-finds CardAnimator)
- State Machine: Drag the "StateMachine" child

**CardAnimator.cs:**
- Card Display: Drag the "CardDisplay" child
- Visual Root: Drag the "Card" GameObject itself

**CardContext.cs:**
- (Everything auto-assigned, nothing to wire)

---

## Step 9: Save as Prefab

1. Drag the "Card" GameObject into your Prefabs folder
2. Name it: `Card.prefab` (or whatever you prefer)
3. Delete the instance from the scene

---

## Step 10: Update Scene References

### BoosterOpeningPage
- Find `BoosterOpeningPage` in your scene
- Assign `cardPrefab` field → your new Card prefab

### AlbumViewPage
- Find `AlbumViewPage` in your scene
- Assign `cardPrefab` field → your new Card prefab

### AlbumCardSlot Prefab
- Open your AlbumCardSlot prefab
- Assign `cardPrefab` field → your new Card prefab

---

## Testing Your Prefab

### Test 1: Booster Opening
1. Play the game
2. Open a booster pack
3. Cards should spawn face-down
4. Click a card → it flips and reveals
5. If NEW → shows enlarged with "NEW" indicator
6. If REPEAT → shows progress bar
7. Click to dismiss → flies to album icon

### Test 2: Album Placement
1. After opening boosters, cards appear in bottom-right
2. Drag a card → it scales up and rotates slightly
3. Drop on valid slot → it snaps in and stays
4. Drop outside → returns to original position

### Test 3: Album Viewing
1. Go to album view
2. Cards in slots should display normally
3. Click a placed card → enlarges with backdrop
4. Click again (or backdrop) → shrinks back to slot

---

## Common Issues & Fixes

### Cards don't flip
- Check FlippingState is assigned in StateMachine
- Verify CardBack GameObject exists and has sprite
- Check CardAnimator has CardDisplay reference

### Cards don't respond to clicks
- Make sure CardDisplay images have "Raycast Target" enabled
- Check EventSystem exists in scene
- Verify Card has CanvasGroup or Image for raycast blocking

### Animations don't play
- Check CardAnimator reference is assigned
- Verify Tween library (Pixelplacement) is imported
- Check state components have correct duration values

### Cards stuck in one state
- Enable StateMachine debug mode to see transitions
- Check state scripts don't have infinite loops
- Verify transition logic in state Enter/Exit methods

---

## Advanced: Customizing States

Want to add your own card behavior? Here's how:

1. Create new script inheriting from `AppleState`
2. Override `Enter()`, `Exit()`, `UpdateState()` as needed
3. Use `Card` reference to access context, animator, etc.
4. Add GameObject under StateMachine with your new component
5. Transition to it via `Card.ChangeState("YourStateName")`

Example:
```csharp
public class CardBurningState : AppleState
{
    private Card _card;
    
    public override void Enter(params object[] args)
    {
        _card = GetComponentInParent<Card>();
        // Play burning animation
        _card.Animator.PlayBurnEffect();
    }
    
    public override void Exit()
    {
        // Clean up
    }
}
```

---

## Final Checklist

Before considering your prefab complete:

- [ ] Root Card GameObject has Card, CardContext, CardAnimator components
- [ ] CardDisplay child is set up with all UI elements
- [ ] CardBack child exists for flip animation
- [ ] StateMachine child has AppleMachine component
- [ ] All 6 state children are created and configured
- [ ] All references wired up on Card component
- [ ] Prefab saved and assigned in scene controllers
- [ ] Tested in both booster and album flows
- [ ] No console errors when playing

---

## Need Help?

Refer to:
- `card_system_migration_summary.md` - What changed and why
- `card_architecture_plan.md` - Architecture overview
- State script files - Implementation details

Happy card building! 🎴