AppleHillsProduction/docs/card_system_integration_and_testing.md

# Card System Integration and Testing Guide

## Overview

This document outlines the integration between the data and UI layers of the Apple Hills card collection system, as well as the testing tools available for development purposes.

## Architecture Summary

The card system follows a clean separation of concerns:

1. **Data Layer** (Assets/Scripts/Data/CardSystem/)
   - `CardSystemManager`: Singleton for managing card data, booster packs, and collection
   - `CardInventory`: Player's collection of cards and booster packs
   - `CardData`: Runtime instance of a collected card
   - `CardDefinition`: ScriptableObject template defining card properties
   - `CardVisualConfig`: Visual settings for cards based on rarity/zone

2. **UI Layer** (Assets/Scripts/UI/CardSystem/)
   - `CardAlbumUI`: Main controller for the card UI system 
   - `UIPageController`: Stack-based navigation system
   - `UIPage`: Base class for UI pages with transition animations
   - Page Components:
     - `CardMenuPage`: Main menu for the card system
     - `AlbumViewPage`: Grid display of collected cards with filtering
     - `BoosterOpeningPage`: Interactive card reveal experience
   - `CardUIElement`: Individual card visual representation
   - `BoosterNotificationDot`: UI element showing booster pack counts

## Integration Points

### Initialization Process

1. `CardSystemManager` initializes during the bootstrap process using `BootCompletionService`
2. UI components register with `BootCompletionService.RegisterInitAction()` for post-boot initialization
3. UI components access card data through `CardSystemManager.Instance`

### Data Flow

1. **Card Collection**:
   - `CardSystemManager` manages the player's `CardInventory`
   - Cards are added via `AddCardToInventory()` 
   - Card collection triggers `OnCardCollected` event

2. **Booster Packs**:
   - Added via `CardSystemManager.AddBoosterPack()`
   - Opened via `CardSystemManager.OpenBoosterPack()`
   - Booster count changes trigger `OnBoosterCountChanged` event
   - Opening boosters triggers `OnBoosterOpened` event

3. **Card Display**:
   - `CardUIElement` displays a card using `SetupCard(cardData)` 
   - `AlbumViewPage` displays cards in a grid with filtering options
   - `BoosterOpeningPage` handles interactive card reveals

### Event System

Key events that connect data and UI layers:

- `OnBoosterCountChanged`: Triggered when booster count changes
- `OnBoosterOpened`: Triggered when a booster is opened
- `OnCardCollected`: Triggered when a new card is added to collection
- `OnCardRarityUpgraded`: Triggered when duplicates upgrade a card's rarity

## Testing Tool: CardSystemTester

The `CardSystemTester` provides a simple interface for testing the card system without requiring full game integration.

### Features

- Adding booster packs
- Opening the card menu
- Opening booster packs
- Browsing the album view
- Generating random test cards
- Clearing the card collection

### Usage

1. Add `CardSystemTester` component to a GameObject in your test scene
2. Reference the `CardAlbumUI` component
3. Enter Play mode and use the inspector buttons
4. All buttons are disabled in edit mode

### Implementation Notes

```csharp
public class CardSystemTester : MonoBehaviour
{
    // Only need reference to CardAlbumUI, the CardSystemManager is accessed via singleton
    [SerializeField] private CardAlbumUI cardAlbumUI;
    
    // Other variables for test configuration
    [SerializeField] [Range(1, 10)] private int boosterPacksToAdd = 3;
    [SerializeField] [Range(1, 100)] private int cardsToGenerate = 10;
    
    // All operations use CardSystemManager.Instance
    public void AddBoosterPacks() { 
        CardSystemManager.Instance.AddBoosterPack(boosterPacksToAdd);
        // Other operations...
    }
    
    // Uses CardAlbumUI to simulate UI interactions
    public void SimulateBackpackClick() {
        // Trigger the backpack button's onClick event
    }
    
    // Additional test methods...
}
```

### Test Scene Setup

1. Create a new scene or use an existing test scene
2. Add a Canvas with proper UI configuration
3. Add the CardSystem prefab (containing CardAlbumUI)
4. Add the CardSystemTester component
5. Make sure you have card definitions configured

## Current Implementation Status

1. **Complete**:
   - Core data management through `CardSystemManager`
   - Card collection and inventory management
   - Basic UI navigation system
   - Booster pack opening flow
   - Album view with filtering

2. **Added API Methods**:
   - `GetAllCardDefinitions()`: Returns list of all card definitions
   - `GetCardInventory()`: Returns reference to player's card inventory
   - `ClearAllCards()`: Resets the player's collection
   - Various utility methods for filtering and statistics

3. **UI Improvements**:
   - Simplified card display in album view
   - Properly integrated card reveal animations
   - Back button functionality for all pages

## Known Issues and Considerations

1. **Performance**: Large collections may require optimization
2. **Save System**: Currently not implemented, needs integration with game save system
3. **Card Definition Loading**: Ensure card definitions are loaded before use
4. **Testing Workflow**: Test specific state scenarios using the CardSystemTester
5. **Animation Timing**: May need adjustment for smoother experience

## Next Steps

1. Implement save/load system for card collection
2. Add collection statistics display
3. Implement rarity-specific effects for card reveals
4. Create more comprehensive test coverage

## Technical References

- Bootstrap system: Use `BootCompletionService.RegisterInitAction(InitializePostBoot)` for initialization
- Data access: Always use `CardSystemManager.Instance` for data access
- Page navigation: Use `UIPageController.Instance.PushPage()` and `PopPage()`
- Card UI: Use `CardUIElement.SetupCard()` to configure card display