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)
   │   │   └── BoosterPack_0 (BoosterPackDraggable prefab instance)
   │   ├── Slot_1 (DraggableSlot)
   │   │   └── BoosterPack_1 (BoosterPackDraggable prefab instance)
   │   └── Slot_2 (DraggableSlot)
   │       └── BoosterPack_2 (BoosterPackDraggable prefab instance)
   ├── CenterSlot (DraggableSlot)
   └── CardDisplayContainer (Empty RectTransform)
   ```
   
   > **💡 Tip:** Boosters are parented directly to their starting slots! This makes authoring easier and the hierarchy cleaner. No separate container needed.

---

## 📐 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` (or `Custom` for hand-authored positions - see custom_layout_guide.md)
- Spacing: `120` (ignored if Layout Type = Custom)
- Center Slots: ✓ (ignored if Layout Type = Custom)
- Auto Register Children: ✓

> **💡 Tip:** Want artistic, scattered slot positions? Set Layout Type to `Custom` and manually position each slot in the Scene View. See `custom_layout_guide.md` for details!

**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**

**Setup as Slot Children (Recommended):**

**Create a single BoosterPackPrefab with visual as a child:**

**BoosterPackPrefab Structure:**
```
BoosterPackPrefab
├── BoosterPackDraggable (component)
├── CanvasGroup (component - for raycast control)
└── Visual (child GameObject)
    ├── Canvas (component - for z-order control)
    ├── CanvasGroup (component - for alpha fading)
    ├── BoosterPackVisual (component)
    ├── ShakeParent (RectTransform - position/rotation punch effects)
    │   └── TiltParent (RectTransform - continuous smooth rotation)
    │       └── PackImage (Image - your booster sprite, raycastTarget = false)
    └── GlowEffect (ParticleSystem - optional)
```

**BoosterPackDraggable Settings:**
- **Visual Prefab:** Leave empty (using child visual instead)
- **Instantiate Visual:** ☐ unchecked (child visual is auto-detected)
- Can Open On Drop: ☐
- Can Open On Double Click: ☐
- **Can Tap To Open: ✓**
- **Max Taps To Open: 3**

**BoosterPackVisual Settings (on the Visual child):**
- Canvas: Auto-assigned or drag the Canvas component
- Canvas Group: Auto-assigned or drag the CanvasGroup component
- Tilt Parent: Drag `TiltParent`
- Shake Parent: Drag `ShakeParent`
- Pack Image: Drag `PackImage`
- Pack Sprite: Assign your booster sprite asset
- Glow Effect: Optional ParticleSystem
- Glow Transform: Optional (for rotation)

> **📝 Simplified Approach!** The visual is now a **direct child** of the BoosterPackPrefab, making authoring much easier. The system auto-detects child visuals using `GetComponentInChildren<DraggableVisual>()`. This gives you:
> - ✅ Full visual authoring control in the prefab
> - ✅ See exactly what your booster looks like
> - ✅ No separate prefab files to manage
> - ✅ Simpler hierarchy and setup
> 
> The visual still follows with smooth lerp/delay and all animations work the same!

> **📝 Note on Hierarchy:** ShakeParent and TiltParent are **nested RectTransforms** (ShakeParent → TiltParent → PackImage) so PackImage gets BOTH effects combined: shake (discrete position/rotation tweens) AND tilt (continuous smooth rotation). This nesting allows transform inheritance through Unity's parent-child chain.

> **📝 Note on Raycast Control:** The root BoosterPackPrefab uses CanvasGroup's `blocksRaycasts` for raycast toggling during drag. Visual children (PackImage, etc.) should have `raycastTarget = false` so clicks reach the root.

> **💡 Advanced Option:** If you prefer the old pattern (separate prefab files), you can still use it by assigning a prefab to `Visual Prefab` and checking `Instantiate Visual`. The system supports both patterns - it checks for a child visual first, then falls back to instantiation if configured.

3. **Add to Slots:**
   - Drag BoosterPackPrefab as child of `Slot_0` → Name it `BoosterPack_0`
   - Drag BoosterPackPrefab as child of `Slot_1` → Name it `BoosterPack_1`
   - Drag BoosterPackPrefab as child of `Slot_2` → Name it `BoosterPack_2`
   - Set each booster's **Active state to ☐ UNCHECKED** (starts inactive)
   - Position: (0, 0) local position (centered in slot)

> **💡 Why Parent to Slots?** The code calls `AssignToSlot()` which reparents anyway, so starting as a child of the slot makes authoring cleaner and more visual. You can see exactly where boosters will appear!

---

### **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 (component - sort order controlled at runtime)
├── CanvasGroup (component - for fading)
├── ShakeParent (RectTransform - outer animation layer)
│   └── TiltParent (RectTransform - inner animation layer)
│       ├── PackImage (Image - your booster pack sprite)
│       └── FrameImage (Image - optional frame/border)
└── GlowEffect (Particle System - optional sparkles)
```

> **💡 Animation Chain:** ShakeParent contains TiltParent, which contains the visuals. This nesting means PackImage gets BOTH shake (position/rotation punch) AND tilt (smooth continuous rotation) effects combined through Unity's transform hierarchy. Both are RectTransforms since this is UI.

### **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!** 🎉