AppleHillsProduction/docs/booster_opening_setup_guide.md

# Booster Opening System - Complete Setup Guide

## 📋 Overview
This guide walks you through setting up the complete booster opening flow, from the Album page to opening packs and revealing cards.

---

## 🎯 What Was Implemented

### **Core Components Enhanced:**
1. **DraggableSlot** - Added scale control for occupants
2. **BoosterPackDraggable** - Added tap-to-shake functionality
3. **BoosterPackVisual** - Added progressive shake animations
4. **BoosterOpeningPage** - Complete flow implementation
5. **AlbumViewPage** - Updated to pass booster count

### **Flow Summary:**
1. Album page shows booster buttons → Click → Opens BoosterOpeningPage
2. Opening page shows draggable boosters in bottom-right
3. Player taps or drags booster to center slot
4. Player taps booster X times (configurable, default 3)
5. Booster disappears, 3 card backs appear
6. Player clicks cards to reveal them one-by-one
7. After all revealed → Show next booster OR close page

---

## 🏗️ Scene Setup Instructions

### **Step 1: Create the BoosterOpeningPage GameObject**

1. **In your scene hierarchy:**
   - Create an empty GameObject named `BoosterOpeningPage`
   - Add component: `BoosterOpeningPage` script
   - Add component: `Canvas Group` (for fade transitions)
   - Ensure it's a child of your Canvas

2. **Create UI Structure:**
   ```
   BoosterOpeningPage (BoosterOpeningPage component)
   ├── Background (Image - optional dark overlay)
   ├── CloseButton (Button)
   ├── BottomRightContainer (SlotContainer)
   │   ├── Slot_0 (DraggableSlot)
   │   ├── Slot_1 (DraggableSlot)
   │   └── Slot_2 (DraggableSlot)
   ├── CenterSlot (DraggableSlot)
   ├── CardDisplayContainer (Empty RectTransform)
   └── BoosterInstances (Empty container)
       ├── BoosterPack_0 (BoosterPackDraggable prefab)
       ├── BoosterPack_1 (BoosterPackDraggable prefab)
       └── BoosterPack_2 (BoosterPackDraggable prefab)
   ```

---

## 📐 Detailed Component Setup

### **A. Bottom-Right Slot Container**

**GameObject Setup:**
- Name: `BottomRightContainer`
- Component: `SlotContainer`
- Position: Bottom-right of screen (e.g., anchored to bottom-right)
- Recommended position: X=800, Y=-400 (adjust for your canvas size)

**SlotContainer Settings:**
- Layout Type: `Vertical`
- Spacing: `120`
- Center Slots: ✓
- Auto Register Children: ✓

**Child Slots (Slot_0, Slot_1, Slot_2):**
- Add component: `DraggableSlot` to each
- Size: 150x200 (adjust to your booster size)
- Settings:
  - Filter By Type: ✓
  - Allowed Type Names: `BoosterPackDraggable`
  - Apply Scale To Occupant: ☐ (leave normal size)

---

### **B. Center Opening Slot**

**GameObject Setup:**
- Name: `CenterSlot`
- Component: `DraggableSlot`
- Position: Center of screen (X=0, Y=0)
- Size: 300x400 (larger than boosters)

**DraggableSlot Settings:**
- Filter By Type: ✓
- Allowed Type Names: `BoosterPackDraggable`
- **Apply Scale To Occupant: ✓** ← Important!
- **Occupant Scale: (2, 2, 1)** ← Makes booster 2x bigger
- Scale Transition Duration: `0.3`

---

### **C. Card Display Container**

**GameObject Setup:**
- Name: `CardDisplayContainer`
- Component: `RectTransform` only
- Position: Center of screen (X=0, Y=-100)
- This is where revealed cards will spawn

---

### **D. Booster Pack Instances**

You have two options: **Prefabs** or **Scene Instances**

#### **Option 1: Using Prefabs (Recommended)**

1. **Create BoosterPack Prefab:**
   ```
   BoosterPackPrefab
   ├── BoosterPackDraggable (component)
   ├── Image (base - raycastTarget = false)
   └── Visual (BoosterPackVisual)
       ├── Canvas
       ├── CanvasGroup
       ├── TiltParent (Transform)
       │   └── PackImage (Image - your booster sprite)
       ├── ShakeParent (Transform)
       └── GlowEffect (ParticleSystem - optional)
   ```

2. **BoosterPackDraggable Settings:**
   - Visual Prefab: Assign the Visual prefab
   - Can Open On Drop: ☐
   - Can Open On Double Click: ☐
   - **Can Tap To Open: ✓**
   - **Max Taps To Open: 3** (or your preference)

3. **In Scene:**
   - Under `BoosterInstances` container, create 3 instances
   - Name them: `BoosterPack_0`, `BoosterPack_1`, `BoosterPack_2`
   - They will start inactive and be shown based on available count

#### **Option 2: Scene Instances**
- Place 3 booster GameObjects directly in the scene
- Configure as above
- Set initial Active state to `false`

---

### **E. Flippable Card Prefab**

**For now (placeholder):**
1. Create a simple prefab named `FlippableCardPrefab`
2. Structure:
   ```
   FlippableCardPrefab
   ├── RectTransform (200x300)
   ├── CardDisplay (component)
   ├── Image (card back sprite initially)
   └── Button (will be added at runtime if not present)
   ```

3. **Important:**
   - The card should show a "back" sprite initially
   - When clicked, `CardDisplay.SetupCard()` will be called
   - In the future, add flip animation here

---

### **F. BoosterOpeningPage Component Configuration**

**In the Inspector:**

**UI References:**
- Canvas Group: Auto-assigned or drag the CanvasGroup
- Close Button: Drag your close button

**Booster Management:**
- Booster Pack Instances: **Array size = 3**
  - Element 0: `BoosterPack_0`
  - Element 1: `BoosterPack_1`
  - Element 2: `BoosterPack_2`
- Bottom Right Slots: Drag `BottomRightContainer`
- Center Opening Slot: Drag `CenterSlot`

**Card Display:**
- Card Display Container: Drag `CardDisplayContainer`
- Flippable Card Prefab: Drag your card prefab
- Card Spacing: `150` (distance between cards)

**Settings:**
- Card Reveal Delay: `0.5`
- Booster Disappear Duration: `0.5`

---

## 🎨 Creating the Booster Pack Visual Prefab

### **Booster Visual Structure:**

```
BoosterVisual (BoosterPackVisual component)
├── Canvas (sort order will be controlled at runtime)
├── CanvasGroup (for fading)
├── TiltParent (empty Transform for 3D tilt effect)
│   ├── PackImage (Image - your booster pack sprite)
│   └── FrameImage (Image - optional frame/border)
├── ShakeParent (empty Transform for shake effects)
└── GlowEffect (Particle System - optional sparkles)
```

### **Component Settings:**

**BoosterPackVisual:**
- Canvas: Auto-assigned
- Canvas Group: Auto-assigned
- Tilt Parent: Drag `TiltParent`
- Shake Parent: Drag `ShakeParent`
- Pack Image: Drag the `PackImage`
- Pack Sprite: Assign your booster sprite asset

**Visual Animation Settings:**
- Follow Speed: `30`
- Rotation Amount: `20`
- Tilt Speed: `20`
- Use Idle Animation: ✓
- Idle Animation Speed: `1`
- Opening Scale Punch: `0.5`
- Opening Rotation Punch: `360`
- Opening Duration: `0.5`

---

## 🔗 Connecting to AlbumViewPage

**In your AlbumViewPage Inspector:**
- Booster Opening Page: Drag your `BoosterOpeningPage` GameObject
- Booster Pack Buttons: Array of booster button GameObjects (already configured)

**That's it!** The AlbumViewPage script already has the updated code to pass booster count.

---

## 🎮 Testing the Flow

### **Test Checklist:**

1. **Setup Test:**
   - ✓ BoosterOpeningPage exists in scene
   - ✓ All slots configured
   - ✓ Booster instances assigned
   - ✓ AlbumViewPage has reference to opening page

2. **Manual Booster Count:**
   - In CardSystemManager, set initial booster count to 3
   - Or use the editor tool to add boosters

3. **Test Flow:**
   1. Open album → Should see 3 booster buttons
   2. Click a booster button → Opens BoosterOpeningPage
   3. Should see 3 boosters in bottom-right
   4. **Drag Test:** Drag a booster to center → Should scale up 2x
   5. **Tap Test:** Tap the booster 3 times:
      - Tap 1: Small shake
      - Tap 2: Medium shake
      - Tap 3: Big shake → Booster disappears
   6. Should see 3 card backs appear
   7. Click each card → Should reveal (show CardDisplay)
   8. After all revealed → Should show next booster OR close page

---

## ⚙️ Configuration Options

### **Adjusting Tap Count:**
- Select any BoosterPackDraggable
- Change `Max Taps To Open` (3 is default)

### **Adjusting Booster Cap:**
- In BoosterOpeningPage, change `Booster Pack Instances` array size
- Add/remove booster instances
- Bottom-right slots should match (add more Slot children)

### **Adjusting Center Slot Scale:**
- Select `CenterSlot`
- Change `Occupant Scale` (2,2,1 = 2x size)

### **Card Spacing:**
- In BoosterOpeningPage, adjust `Card Spacing` (150 default)

---

## 🐛 Troubleshooting

### **Problem: Boosters don't appear**
- Check: `Booster Pack Instances` array is filled
- Check: CardSystemManager has boosters available
- Check: AlbumViewPage passes booster count correctly

### **Problem: Can't drag booster to center**
- Check: CenterSlot has `Filter By Type` with `BoosterPackDraggable`
- Check: CenterSlot is not locked initially
- Check: Booster has Image with `raycastTarget = true` on base object

### **Problem: Tapping doesn't work**
- Check: BoosterPackDraggable has `Can Tap To Open` enabled
- Check: Booster is in the center slot (tap only works when slotted)
- Check: Visual children have `raycastTarget = false` so taps reach the base

### **Problem: Booster doesn't scale up in center**
- Check: CenterSlot has `Apply Scale To Occupant` enabled
- Check: `Occupant Scale` is set (e.g., 2,2,1)

### **Problem: Cards don't reveal**
- Check: `Flippable Card Prefab` is assigned
- Check: Prefab has CardDisplay component
- Check: CardDisplay can receive card data

---

## 🎨 Visual Polish (Optional Next Steps)

### **Enhance Card Flip:**
- Add rotation animation when revealing
- Use DOTween or Tween for 3D flip effect
- Particle effects on reveal

### **Booster Opening Effects:**
- More dramatic particles when opening
- Sound effects on taps and opening
- Screen shake on final tap

### **Transition Polish:**
- Boosters fly in on page open
- Cards fly out after revealing
- Smooth transitions between boosters

---

## 📝 Summary

**You now have:**
✅ Complete booster opening flow
✅ Tap-to-shake interaction (3 taps default)
✅ Drag-and-drop alternative
✅ Card reveal system (click to flip)
✅ Auto-progression to next booster
✅ Auto-close when no boosters left
✅ Scalable system (adjust array size for more boosters)

**Next Steps:**
1. Create your visual assets (booster sprites, card backs)
2. Set up the scene structure as outlined
3. Configure the BoosterOpeningPage component
4. Test the flow
5. Polish with animations and effects

**Need Help?**
- Reference the existing drag-and-drop documentation
- Check CardSystem documentation for card data structure
- Test individual components in isolation first

---

🎉 **Happy Booster Opening!** 🎉