AppleHillsProduction/docs/card_system_implementation_plan.md

# Card System Implementation Plan

## Current Implementation Analysis

### Data Layer

1. **CardData.cs**:
   - Represents an instance of a card in the player's collection
   - Contains unique ID, rarity, and copies owned
   - Has a reference to its CardDefinition for display information
   - Includes methods for rarity upgrades when collecting duplicates
   - Well-structured with proper serialization support

2. **CardDefinition.cs**:
   - ScriptableObject template for creating card instances
   - Contains basic info (name, description), visuals, and collection data
   - Provides helper methods like CreateCardData() and GetBackgroundColor()
   - Supports different zones (AppleHills, Quarry, Forest, Mountain, Beach)

3. **CardSystemManager.cs**:
   - Singleton manager for the card system
   - Manages available card definitions and player inventory
   - Includes event callbacks for booster packs and card collection
   - Has partial implementation for adding booster packs
   - Has a simple CardInventory class stub

4. **CardVisualConfig.cs**:
   - ScriptableObject for configuring the visual appearance of cards
   - Maps rarities to colors and zones to colors/shapes
   - Uses dictionary lookups for efficient access

### UI Layer

1. **CardUIElement.cs**:
   - Handles displaying a single card in the UI
   - Updates visuals based on card data (rarity, zone)
   - References UI elements like card name text, images, frames, etc.

2. **UIPageController.cs**:
   - Manages UI page transitions with a stack-based navigation system
   - Provides methods for pushing, popping, and clearing the page stack
   - Uses events to notify when pages change

3. **UI Page Components**:
   - Several page-related files (AlbumViewPage.cs, BoosterOpeningPage.cs, CardMenuPage.cs)
   - CardAlbumUI.cs file for handling the album display
   - Base UIPage.cs class for common page functionality

## What's done
1. **Complete CardInventory Implementation**:
    - Move from simple stub to full implementation
    - Add methods to manage the player's card collection
    - Implement filtering, sorting, and organization features

2. **Booster Pack Generation**:
    - Complete the logic to generate random booster packs with appropriate rarity distribution
    - Implement methods for awarding booster packs to the player
    - Add events for notifying UI when booster packs are obtained

## What's currently being worked on
3. **Card Collection UI**:
    - Complete the album browsing UI with filtering and sorting options
    - Implement visual indicators for owned/not owned cards
    - Add UI for tracking collection completion

## What's Missing
Based on the requirements, here's what still needs to be implemented:
4. **Booster Pack Opening UI**:
   - Implement the UI flow for opening booster packs
   - Add card reveal animations and effects
   - Create UI feedback for rare card discoveries

5. **Save/Load System**:
   - Implement persistence for the player's card collection
   - Add autosave functionality for cards and booster packs

## Implementation Plan

### Step 1: Complete the Data Layer

1. **Implement CardInventory.cs**:
   - Create a dedicated class file (replacing the stub in CardSystemManager)
   - Add methods for adding/removing cards, checking duplicates
   - Implement filtering by zone, rarity, etc.
   - Add collection statistics methods

2. **Complete CardSystemManager.cs**:
   - Update references to use the new CardInventory class
   - Add methods for save/load integration
   - Implement additional helper methods for card management

### Step 2: Implement UI Flow

1. **Complete UIPage Implementations**:
   - Implement CardMenuPage.cs as the main card system entry point
   - Complete AlbumViewPage.cs for browsing the collection
   - Implement BoosterOpeningPage.cs for the pack opening experience

2. **Card Collection Browsing**:
   - Complete CardAlbumUI.cs to display the player's collection
   - Add filtering by zone, rarity, etc.
   - Implement pagination for large collections

3. **Booster Pack UI**:
   - Create UI for displaying and opening booster packs
   - Implement card reveal animations and transitions
   - Add sound effects and visual feedback

### Step 3: Integration and Polishing

1. **Connect UI to Data Layer**:
   - Hook up UI components to CardSystemManager events
   - Ensure data flows correctly between UI and data layers

2. **Test and Balance**:
   - Test rarity distribution in booster packs
   - Balance the upgrade system for duplicates

3. **Performance Optimization**:
   - Implement object pooling for card UI elements
   - Optimize loading of card data and sprites

### Step 4: Additional Features (Optional)

1. **Card Trading System**:
   - Allow players to trade cards with NPCs or other players
   
2. **Special Collection Bonuses**:
   - Rewards for completing sets of cards

3. **Card Usage Mechanics**:
   - Ways to use cards in gameplay beyond collection