AppleHillsProduction/docs/booster_prefab_structure_guide.md

# Booster Pack Prefab Structure Guide

## 🎨 Complete Booster Pack Prefab Setup

This guide shows you exactly how to structure your booster pack prefabs for the opening system.

---

## 📦 BoosterPackDraggable Prefab Structure

```
BoosterPackPrefab (RectTransform)
│
├── [Components on Root]
│   ├── RectTransform (200x300 size recommended)
│   ├── Image (IMPORTANT: raycastTarget = TRUE - for clicking/dragging)
│   ├── BoosterPackDraggable (script)
│   └── Canvas Group (optional - for fading)
│
└── Visual (Child GameObject)
    └── [BoosterPackVisual Prefab Instance]
```

---

## 🎭 BoosterPackVisual Prefab Structure

```
BoosterVisual (RectTransform)
│
├── [Components on Root]
│   ├── RectTransform (same size as parent)
│   ├── Canvas (will be controlled at runtime)
│   ├── CanvasGroup (for alpha transitions)
│   └── BoosterPackVisual (script)
│
├── TiltParent (Empty Transform)
│   │   [This rotates for 3D tilt effect]
│   │
│   ├── PackImage (Image)
│   │   ├── Sprite: Your booster pack sprite
│   │   ├── raycastTarget: FALSE
│   │   └── Size: Slightly smaller than parent
│   │
│   ├── FrameImage (Image - optional)
│   │   ├── Sprite: Border/frame decoration
│   │   └── raycastTarget: FALSE
│   │
│   └── RarityIndicator (Image - optional)
│       ├── Sprite: Rarity gem/star
│       └── raycastTarget: FALSE
│
├── ShakeParent (Empty Transform)
│   │   [This is used for shake offset]
│   └── (Currently empty, reserved for effects)
│
└── GlowEffect (Particle System - optional)
    ├── Shape: Circle
    ├── Start Size: 5-10
    ├── Start Color: Golden/sparkly
    ├── Emission Rate: 10-20
    └── Renderer: Sort Order = 1 (above images)
```

---

## ⚙️ Component Configuration

### **BoosterPackDraggable Settings:**

```yaml
[Draggable Settings]
Move Speed: 50
Smooth Movement: ✓
Snap Duration: 0.3

[Visual]
Visual Prefab: (Assign BoosterVisual prefab)
Instantiate Visual: ✓
Visual Parent: (Leave empty - uses canvas)

[Selection]
Is Selectable: ✓
Selection Offset: 50

[Booster Pack Settings]
Can Open On Drop: ☐
Can Open On Double Click: ☐

[Tap to Open]
Can Tap To Open: ✓
Max Taps To Open: 3
```

### **BoosterPackVisual Settings:**

```yaml
[References]
Canvas: (Auto-assigned)
Canvas Group: (Auto-assigned)
Tilt Parent: (Drag TiltParent object)
Shake Parent: (Drag ShakeParent object)

[Follow Parameters]
Follow Speed: 30
Use Follow Delay: ✓

[Rotation/Tilt Parameters]
Rotation Amount: 20
Rotation Speed: 20
Auto Tilt Amount: 30
Manual Tilt Amount: 20
Tilt Speed: 20

[Scale Parameters]
Use Scale Animations: ✓
Scale On Hover: 1.15
Scale On Drag: 1.25
Scale Transition Duration: 0.15

[Idle Animation]
Use Idle Animation: ✓
Idle Animation Speed: 1

[Booster Pack Visual]
Pack Image: (Drag PackImage)
Pack Sprite: (Assign your sprite asset)
Glow Effect: (Drag particle system if using)
Glow Transform: (Drag particle transform if using)

[Opening Animation]
Opening Scale Punch: 0.5
Opening Rotation Punch: 360
Opening Duration: 0.5
```

---

## 🎨 Creating in Unity (Step-by-Step)

### **Step 1: Create Root GameObject**
1. Right-click in Hierarchy → UI → Image
2. Name it: `BoosterPackPrefab`
3. Set Size: 200x300 (Width x Height)
4. Add sprite: Temporary placeholder or your booster sprite
5. **IMPORTANT:** Ensure `raycastTarget` is ✓ checked

### **Step 2: Add BoosterPackDraggable**
1. Add Component → `BoosterPackDraggable`
2. Configure settings (see above)
3. Leave Visual Prefab empty for now

### **Step 3: Create Visual Child**
1. Right-click BoosterPackPrefab → Create Empty
2. Name it: `BoosterVisual`
3. Add Component → `Canvas`
4. Add Component → `Canvas Group`
5. Add Component → `BoosterPackVisual`

### **Step 4: Create TiltParent**
1. Right-click BoosterVisual → Create Empty
2. Name it: `TiltParent`
3. Position: (0, 0, 0)

### **Step 5: Add Images under TiltParent**
1. Right-click TiltParent → UI → Image
2. Name it: `PackImage`
3. Assign your booster sprite
4. **Set raycastTarget to ☐ UNCHECKED**
5. Size: 180x280 (slightly smaller)

### **Step 6: Create ShakeParent**
1. Right-click BoosterVisual → Create Empty
2. Name it: `ShakeParent`
3. Position: (0, 0, 0)

### **Step 7: Add Glow Effect (Optional)**
1. Right-click BoosterVisual → Effects → Particle System
2. Name it: `GlowEffect`
3. Configure:
   - Duration: 1
   - Looping: ✓
   - Start Lifetime: 1-2
   - Start Speed: 0
   - Start Size: 5-10
   - Start Color: Gold/Yellow with alpha
   - Shape: Circle, Radius: 1
   - Emission: Rate over Time = 15
   - Renderer: Material = Default Particle, Sort Order = 1

### **Step 8: Wire Up References**
1. Select `BoosterVisual`
2. In BoosterPackVisual component:
   - Tilt Parent: Drag `TiltParent`
   - Shake Parent: Drag `ShakeParent`
   - Pack Image: Drag `PackImage`
   - Pack Sprite: Assign sprite asset
   - Glow Effect: Drag `GlowEffect` (if using)

### **Step 9: Make Prefab**
1. Drag `BoosterPackPrefab` to Project folder
2. Delete from scene
3. You now have a reusable prefab!

---

## 🎯 Instantiation in Scene

### **Option A: Prefab Instances (Recommended)**
In your BoosterOpeningPage scene:
1. Create empty GameObject: `BoosterInstances`
2. Drag 3 instances of your prefab into it
3. Name them: `BoosterPack_0`, `BoosterPack_1`, `BoosterPack_2`
4. Set all to Active = ☐ (unchecked)
5. Position doesn't matter - they'll be assigned to slots

### **Option B: Runtime Instantiation**
- Assign the prefab to BoosterOpeningPage
- Script will instantiate as needed
- (Not implemented yet, but easy to add)

---

## 🧪 Testing Your Prefab

### **Test 1: Visual Check**
1. Place one instance in scene (active)
2. Enter Play Mode
3. Should see: Sprite, idle wobble animation
4. Hover over it: Should scale up slightly

### **Test 2: Drag Test**
1. Create a SlotContainer with a slot
2. Try dragging the booster to the slot
3. Should snap smoothly
4. Visual should lerp-follow with delay

### **Test 3: Tap Test**
1. Place booster in a slot
2. Set Can Tap To Open = ✓, Max Taps = 3
3. Click 3 times
4. Should see increasing shakes

---

## 📐 Size Recommendations

### **For Mobile:**
- Booster: 200x300
- Center Slot Scale: 2x → 400x600
- Card: 180x250

### **For Desktop:**
- Booster: 250x350
- Center Slot Scale: 1.5x → 375x525
- Card: 200x280

### **Spacing:**
- Bottom slots: 120-150 units apart
- Cards: 150-200 units apart

---

## 🎨 Sprite Requirements

### **Booster Pack Sprite:**
- Recommended: 512x768 or 1024x1536
- Format: PNG with transparency
- Style: Vertical rectangle (2:3 ratio)
- Should have clear visual identity

### **Card Back Sprite:**
- Same aspect ratio as cards
- Clearly distinct from front
- Can match booster theme

---

## 🔧 Troubleshooting Prefabs

**Problem: Can't click/drag booster**
→ Check: Root Image has raycastTarget = ✓
→ Check: Visual children have raycastTarget = ☐

**Problem: Visual doesn't follow smoothly**
→ Check: BoosterPackVisual is initialized
→ Check: Follow Speed > 0, Use Follow Delay = ✓

**Problem: No shake animation**
→ Check: BoosterPackVisual subscribes to OnTapped
→ Check: TiltParent and ShakeParent are assigned

**Problem: Booster looks weird when dragging**
→ Check: TiltParent contains the images
→ Check: Rotation parameters are reasonable (10-30)

---

## 💡 Advanced Customization

### **Rarity-Based Visuals:**
Add different sprites or effects based on rarity:
```csharp
// In BoosterPackDraggable or Visual:
public enum BoosterRarity { Common, Rare, Legendary }
public BoosterRarity rarity;

// Change sprite/effects based on rarity
```

### **Opening Sequence:**
Customize the opening animation:
- Adjust Opening Scale Punch (0.5 default)
- Adjust Opening Rotation Punch (360 default)
- Add sound effects in `PlayOpeningAnimation()`

### **Hover Effects:**
Make boosters more responsive:
- Increase Scale On Hover (1.15 → 1.3)
- Add glow intensity on hover
- Tilt toward mouse more (Manual Tilt Amount)

---

## ✅ Final Checklist

Before using your prefab:
- [ ] Root has BoosterPackDraggable
- [ ] Root Image has raycastTarget = TRUE
- [ ] Visual child has BoosterPackVisual
- [ ] TiltParent exists and contains sprites
- [ ] ShakeParent exists
- [ ] All image children have raycastTarget = FALSE
- [ ] References are wired up in Visual
- [ ] Prefab is saved in Project
- [ ] Can Tap To Open = ✓
- [ ] Max Taps To Open = 3 (or your choice)

---

🎉 **You're ready to create beautiful, interactive booster packs!** 🎉