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

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