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