Add card inventory classes and helpers

docs/card_system_implementation_plan.md

@@ -0,0 +1,132 @@
+# 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 Missing
+
+Based on the requirements, here's what still needs to be implemented:
+
+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
+
+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
+
+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