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 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