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