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:

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! 🎴