AppleHillsProduction/docs/card_system_ui_setup_guide.md

# Card System UI Setup Guide

This guide provides detailed instructions for setting up the Card System UI in Unity, organized into prefabs that can be easily maintained and modified.

## Prefab Structure Overview

The card system UI should be structured with a modular prefab approach:

1. **Main Card System Prefab** - Contains the CardAlbumUI component and core structure
2. **Individual UI Page Prefabs** - Each page as its own prefab
3. **Card UI Prefabs** - For cards and card slots

## Detailed Prefab Structure

### Main CardSystem Prefab

```
CardSystem (with CardAlbumUI component)
├── BackpackIcon (GameObject)
│   ├── BackpackImage (Image)
│   ├── BoosterCountText (Text)
│   └── NotificationDot (GameObject with Image)
├── UIPageController (automatically added by CardAlbumUI if not present)
└── Notifications (GameObject)
    └── NewCardNotification (GameObject)
        ├── Background (Image)
        └── Text (Text)
```

### Page Prefabs

**1. MainMenuPage Prefab:**
```
MainMenuPage (with CardMenuPage component & CanvasGroup)
├── Background (Image)
├── Title (Text)
├── OpenBoosterButton (Button)
│   └── Text (Text)
├── ViewAlbumButton (Button)
│   └── Text (Text)
├── ChangeClothesButton (Button)
│   └── Text (Text)
└── NoBoostersMessage (GameObject)
    └── Text (Text)
```

**2. AlbumViewPage Prefab:**
```
AlbumViewPage (with AlbumViewPage component & CanvasGroup)
├── Background (Image)
├── FilterPanel (GameObject)
│   ├── ZoneFilterDropdown (Dropdown)
│   │   ├── Label (Text)
│   │   └── Arrow (Image)
│   ├── RarityFilterDropdown (Dropdown)
│   │   ├── Label (Text)
│   │   └── Arrow (Image)
│   └── ResetFiltersButton (Button)
│       └── Text (Text)
├── AlbumScrollView (ScrollRect)
│   └── AlbumGrid (GridLayoutGroup)
├── CardStackContainer (RectTransform)
└── EmptyAlbumMessage (GameObject)
    └── Text (Text)
```

**3. BoosterOpeningPage Prefab:**
```
BoosterOpeningPage (with BoosterOpeningPage component & CanvasGroup)
├── Background (Image)
├── BoosterPackObject (GameObject)
│   └── BoosterImage (Image)
├── CardRevealTransform (Transform)
├── OpenBoosterButton (Button)
│   └── Text (Text)
├── ContinueButton (Button)
│   └── Text (Text)
├── CardRevealSound (AudioSource)
├── RareCardSound (AudioSource)
├── CardRevealParticles (ParticleSystem)
└── RareCardParticles (ParticleSystem)
```

### Card-Related Prefabs

**1. CardSlotPrefab:**
```
CardSlot (GameObject)
├── Background (Image)
└── SlotLabel (Text)
```

**2. CardPrefab:**
```
Card (with CardUIElement component & Button)
├── CardBackground (Image)
├── CardFrame (Image)
├── CardImage (Image)
├── CardNameText (Text)
├── CardDescriptionText (Text)
├── ZoneLabel (Text)
└── RarityIndicator (Image)
```

## Component Setup Guide

### CardAlbumUI Component Setup

This is the central controller for the card system:

```
CardAlbumUI Component Inspector:
- UI References:
  - Backpack Icon: [BackpackIcon GameObject]
  - Main Menu Page: [MainMenuPage Prefab]
  - Album View Page: [AlbumViewPage Prefab]
  - Booster Opening Page: [BoosterOpeningPage Prefab]
- UI Elements:
  - Backpack Button: [BackpackIcon Button Component]
  - Booster Count Text: [BoosterCountText Component]
  - Notification Dot: [NotificationDot GameObject]
  - Backpack Animation Target: [BackpackIcon Transform]
  - New Card Notification: [NewCardNotification GameObject]
- Notification Settings:
  - Notification Duration: 3 seconds (adjustable)
  - Notification Sound: [AudioSource Component]
```

### CardMenuPage Component Setup

```
CardMenuPage Component Inspector:
- Menu Options:
  - Open Booster Button: [OpenBoosterButton]
  - View Album Button: [ViewAlbumButton]
  - Change Clothes Button: [ChangeClothesButton]
- UI Elements:
  - Booster Count Text: [BoosterCountText]
  - No Boosters Message: [NoBoostersMessage]
  - Canvas Group: [CanvasGroup on this GameObject]
```

### AlbumViewPage Component Setup

```
AlbumViewPage Component Inspector:
- Album UI Elements:
  - Album Grid: [AlbumGrid Component]
  - Card Stack Container: [CardStackContainer Transform]
  - Empty Album Message: [EmptyAlbumMessage GameObject]
  - Card Slot Prefab: [CardSlotPrefab Asset]
  - Card Prefab: [CardPrefab Asset]
- Filter UI:
  - Zone Filter Dropdown: [ZoneFilterDropdown]
  - Rarity Filter Dropdown: [RarityFilterDropdown]
  - Reset Filters Button: [ResetFiltersButton]
  - Canvas Group: [CanvasGroup on this GameObject]
```

### BoosterOpeningPage Component Setup

```
BoosterOpeningPage Component Inspector:
- UI Elements:
  - Booster Pack Object: [BoosterPackObject]
  - Card Reveal Transform: [CardRevealTransform]
  - Card Prefab: [CardPrefab Asset]
  - Open Booster Button: [OpenBoosterButton]
  - Continue Button: [ContinueButton]
  - Canvas Group: [CanvasGroup on this GameObject]
- Animation Settings:
  - Card Reveal Delay: 0.5 (adjustable)
  - Card Move To Backpack Delay: 1.0 (adjustable)
  - Backpack Target Transform: [BackpackIcon Transform]
  - Card Reveal Sound: [CardRevealSound Component]
  - Rare Card Sound: [RareCardSound Component]
  - Card Reveal Particles: [CardRevealParticles Component]
  - Rare Card Particles: [RareCardParticles Component]
```

### CardUIElement Component Setup

```
CardUIElement Component Inspector:
- Card UI Elements:
  - Card Background Image: [CardBackground Image]
  - Card Frame Image: [CardFrame Image]
  - Card Image: [CardImage]
  - Card Name Text: [CardNameText]
  - Card Description Text: [CardDescriptionText]
  - Zone Label: [ZoneLabel Text]
  - Rarity Label: [RarityIndicator Image]
```

## Prefab Creation Process

### 1. Create Card-Related Prefabs First

Start by creating the card prefabs since other prefabs will reference them:

1. **Create CardSlotPrefab**:
   - Create GameObject → UI → Image
   - Add Text component for slot label
   - Adjust visual appearance for an empty slot
   - Save as prefab

2. **Create CardPrefab**:
   - Create GameObject → UI → Image (for background)
   - Add child Images for frame and card art
   - Add Text components for name, description, zone
   - Add CardUIElement script
   - Configure Inspector references
   - Add Button component
   - Save as prefab

### 2. Create UI Page Prefabs

Create each page prefab individually:

1. **Create MainMenuPage Prefab**:
   - Set up UI elements as shown in structure
   - Add CardMenuPage script
   - Add CanvasGroup component
   - Configure all Inspector references
   - Save as prefab

2. **Create AlbumViewPage Prefab**:
   - Set up UI elements as shown in structure
   - Add AlbumViewPage script
   - Add CanvasGroup component
   - Configure all Inspector references
   - Assign CardSlotPrefab and CardPrefab
   - Save as prefab

3. **Create BoosterOpeningPage Prefab**:
   - Set up UI elements as shown in structure
   - Add BoosterOpeningPage script
   - Add CanvasGroup component
   - Add audio sources and particle systems
   - Configure all Inspector references
   - Assign CardPrefab
   - Save as prefab

### 3. Create Main CardSystem Prefab

Finally, create the main controller prefab:

1. **Create CardSystem GameObject**:
   - Add CardAlbumUI script
   - Set up BackpackIcon and Notifications as shown in structure
   - Assign references to page prefabs (not instances)
   - Configure all Inspector references
   - Save as prefab

## Scene Setup Instructions

### 1. Add CardSystem to Your Scene

1. Drag the CardSystem prefab into your scene
2. Make sure it's on the UI layer
3. Verify it has a Canvas component if needed (or is under a Canvas)

### 2. Configure the CardSystemManager

1. Create a GameObject named "CardSystemManager" if not already present
2. Add the CardSystemManager script
3. Populate it with some test card definitions
4. Ensure it's marked as DontDestroyOnLoad if needed

### 3. Test the System

1. Enter Play mode
2. Test clicking the backpack icon
3. Add test booster packs: `CardSystemManager.Instance.AddBoosterPack(3)`
4. Test opening boosters and viewing the album

## Additional Tips

1. **Canvas Settings**:
   - Set your Canvas to Screen Space - Overlay
   - Use Scale With Screen Size with reference resolution 1920x1080
   - Configure the Canvas Scaler for proper UI scaling

2. **UI Navigation**:
   - Configure button navigation for keyboard/controller support
   - Set tab order for accessibility

3. **Audio Setup**:
   - Keep audio sources on the respective UI elements
   - Adjust spatial blend to 0 (2D) for UI sounds
   - Use appropriate volume for notification sounds

4. **Animation Considerations**:
   - All animations use Pixelplacement.Tween
   - Adjust animation durations in Inspector for fine-tuning
   - Consider creating animation presets for consistent feel

5. **Testing on Different Devices**:
   - Test the UI on different aspect ratios
   - Ensure UI elements are anchored properly for different resolutions
   - Use the Device Simulator to test mobile layouts if targeting mobile

6. **Performance Tips**:
   - Consider object pooling for cards in large collections
   - Disable raycast targets on non-interactive elements
   - Use sprite atlases for card images