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