Clean up docs
This commit is contained in:
Michal Pikulski
76551
card_diff.txt
76551
card_diff.txt
File diff suppressed because one or more lines are too long
@@ -1,201 +0,0 @@
|
||||
# Album Slot Migration - Complete ✅
|
||||
|
||||
## Migration Date
|
||||
November 16, 2025
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
Successfully migrated album card states from direct `IPointerClickHandler` to centralized click routing via `ICardClickHandler`, ensuring consistency with booster opening flow.
|
||||
|
||||
---
|
||||
|
||||
## Changes Made
|
||||
|
||||
### 1. CardPlacedInSlotState.cs
|
||||
**Changed:**
|
||||
- ✅ Removed `IPointerClickHandler` interface
|
||||
- ✅ Removed `UnityEngine.EventSystems` using directive
|
||||
- ✅ Added `ICardClickHandler` interface
|
||||
- ✅ Renamed `OnPointerClick(PointerEventData)` → `OnCardClicked(CardContext)`
|
||||
- ✅ Updated method signature to use context parameter
|
||||
|
||||
**Result:**
|
||||
- State now uses centralized click routing from CardContext
|
||||
- Consistent with booster opening states
|
||||
- Click gating via `context.IsClickable` now works
|
||||
|
||||
---
|
||||
|
||||
### 2. CardAlbumEnlargedState.cs
|
||||
**Changed:**
|
||||
- ✅ Removed `IPointerClickHandler` interface
|
||||
- ✅ Removed `UnityEngine.EventSystems` using directive
|
||||
- ✅ Added `ICardClickHandler` interface
|
||||
- ✅ Renamed `OnPointerClick(PointerEventData)` → `OnCardClicked(CardContext)`
|
||||
- ✅ Updated method signature to use context parameter
|
||||
- ✅ Added fallback for when animator is null (transitions to PlacedInSlotState immediately)
|
||||
|
||||
**Result:**
|
||||
- State now uses centralized click routing from CardContext
|
||||
- Consistent with booster opening states
|
||||
- More robust error handling
|
||||
|
||||
---
|
||||
|
||||
### 3. AlbumCardSlot.cs
|
||||
**Changed:**
|
||||
- ✅ Added `AlbumViewPage.RegisterCardInAlbum(card)` call in `SpawnCard()` method
|
||||
- ✅ Finds AlbumViewPage via `FindFirstObjectByType<AlbumViewPage>()`
|
||||
- ✅ Subscribes card's AlbumEnlargedState events to page backdrop/reparenting handlers
|
||||
|
||||
**Result:**
|
||||
- Cards spawned in slots now properly register with page
|
||||
- Backdrop shows when card is enlarged
|
||||
- Card reparents to enlarged container correctly
|
||||
|
||||
---
|
||||
|
||||
## Slot Behavior Verification
|
||||
|
||||
### ✅ Slot Keeps Reference to Assigned Card
|
||||
```csharp
|
||||
private StateMachine.Card _placedCard;
|
||||
```
|
||||
- Reference stored when card is spawned or placed
|
||||
- Accessible via `GetPlacedCard()`
|
||||
|
||||
### ✅ Auto-Spawn Owned Cards
|
||||
**Flow:**
|
||||
1. `OnEnable()` → `CheckAndSpawnOwnedCard()`
|
||||
2. Queries CardSystemManager for owned card (highest rarity)
|
||||
3. If owned → `SpawnCard(cardData)`
|
||||
4. Card spawned with `card.SetupForAlbumSlot(cardData, this)` → starts in `PlacedInSlotState`
|
||||
5. Card sized to match slot dimensions
|
||||
6. Card registered with AlbumViewPage
|
||||
|
||||
### ✅ In Slot → Clickable → Enlarge
|
||||
**Flow:**
|
||||
1. Card in `PlacedInSlotState`
|
||||
2. User clicks → CardContext routes click to state via `ICardClickHandler`
|
||||
3. `PlacedInSlotState.OnCardClicked()` → transitions to `AlbumEnlargedState`
|
||||
4. AlbumEnlargedState fires `OnEnlargeRequested` event
|
||||
5. AlbumViewPage shows backdrop, reparents card to top layer
|
||||
6. Card animates to enlarged scale
|
||||
|
||||
### ✅ Enlarged → Clickable → Dismiss
|
||||
**Flow:**
|
||||
1. Card in `AlbumEnlargedState`
|
||||
2. User clicks → CardContext routes click to state via `ICardClickHandler`
|
||||
3. `AlbumEnlargedState.OnCardClicked()` fires `OnShrinkRequested` event
|
||||
4. AlbumViewPage hides backdrop
|
||||
5. Card shrinks with animation
|
||||
6. On complete → transitions back to `PlacedInSlotState`
|
||||
7. Card reparents back to slot
|
||||
|
||||
### ✅ No Card = No Preview
|
||||
**Current Behavior:**
|
||||
- If player doesn't own card, `ownedCard` remains null
|
||||
- `SpawnCard()` never called
|
||||
- Slot remains empty
|
||||
- No visuals shown
|
||||
|
||||
**Future:** Slot itself clickable for silhouette preview (to be implemented)
|
||||
|
||||
---
|
||||
|
||||
## Architecture Benefits
|
||||
|
||||
### Unified Click Routing
|
||||
**Before:**
|
||||
- Booster states: `ICardClickHandler` (centralized)
|
||||
- Album states: `IPointerClickHandler` (direct)
|
||||
- **Problem:** Two different click systems, confusing
|
||||
|
||||
**After:**
|
||||
- All states: `ICardClickHandler` (centralized)
|
||||
- Single source of truth for click handling
|
||||
- Consistent gating via `context.IsClickable`
|
||||
|
||||
### Click Flow
|
||||
```
|
||||
User clicks card →
|
||||
CardDisplay.OnPointerClick →
|
||||
CardContext.HandleCardDisplayClicked (checks IsClickable) →
|
||||
Finds current state's ICardClickHandler →
|
||||
State.OnCardClicked(context) →
|
||||
State logic executes
|
||||
```
|
||||
|
||||
### Benefits
|
||||
- ✅ Consistent across all card states
|
||||
- ✅ Centralized gating (IsClickable)
|
||||
- ✅ Easy to debug (one routing path)
|
||||
- ✅ Easy to extend (add state, implement ICardClickHandler)
|
||||
- ✅ No more `IPointerClickHandler` scattered across states
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
### Album View Flow
|
||||
- [ ] Album page opens correctly
|
||||
- [ ] Owned cards appear in album slots automatically
|
||||
- [ ] Cards sized correctly to slot dimensions
|
||||
- [ ] Clicking card in slot enlarges it
|
||||
- [ ] Backdrop appears when card enlarged
|
||||
- [ ] Card displays correctly while enlarged
|
||||
- [ ] Clicking enlarged card dismisses it
|
||||
- [ ] Card returns to slot correctly
|
||||
- [ ] Empty slots remain empty (no preview)
|
||||
- [ ] Multiple cards can be enlarged/dismissed sequentially
|
||||
|
||||
### Edge Cases
|
||||
- [ ] Card spawned when entering album (not during booster)
|
||||
- [ ] Multiple rarities of same card (highest shown)
|
||||
- [ ] Very first time opening album (no owned cards)
|
||||
- [ ] Rapid clicking doesn't break states
|
||||
- [ ] Page close during enlarge (cleanup handled)
|
||||
|
||||
---
|
||||
|
||||
## Future: Empty Slot Preview
|
||||
|
||||
When implementing "click empty slot to see silhouette":
|
||||
|
||||
1. Make AlbumCardSlot implement `IPointerClickHandler` for empty state
|
||||
2. Add check in `OnPointerClick()`:
|
||||
```csharp
|
||||
if (!_isOccupiedPermanently && _placedCard == null)
|
||||
{
|
||||
ShowSilhouettePreview();
|
||||
}
|
||||
```
|
||||
3. Create preview state or use temporary visual
|
||||
4. Show card back / silhouette / "???" indicator
|
||||
5. Click to dismiss preview
|
||||
|
||||
**Note:** This won't conflict with card click routing since card won't exist when slot is empty.
|
||||
|
||||
---
|
||||
|
||||
## Files Modified
|
||||
|
||||
- `CardPlacedInSlotState.cs` - Uses ICardClickHandler
|
||||
- `CardAlbumEnlargedState.cs` - Uses ICardClickHandler
|
||||
- `AlbumCardSlot.cs` - Registers cards with AlbumViewPage
|
||||
|
||||
---
|
||||
|
||||
## No Breaking Changes
|
||||
|
||||
- ✅ Existing Card.cs API unchanged
|
||||
- ✅ AlbumViewPage event system unchanged
|
||||
- ✅ Slot validation logic unchanged
|
||||
- ✅ Drag-and-drop from pending cards still works
|
||||
- ✅ All existing states still work
|
||||
|
||||
---
|
||||
|
||||
**Migration Complete!** Album slots now use unified click routing and all requirements verified. 🎉
|
||||
|
||||
@@ -1,297 +0,0 @@
|
||||
# Card Prefab Setup Guide
|
||||
|
||||
## Quick Reference: Building the New Card Prefab
|
||||
|
||||
This guide shows you how to create a Card prefab compatible with the new state-based system.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before starting, make sure you have:
|
||||
- All Card state scripts compiled without errors
|
||||
- CardDisplay.cs working
|
||||
- Card.cs, CardContext.cs, CardAnimator.cs ready
|
||||
- PixelPlacement StateMachine (AppleMachine) available
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create the Root GameObject
|
||||
|
||||
1. Create empty GameObject named "Card"
|
||||
2. Add component: `Card.cs` (from `UI.CardSystem.StateMachine`)
|
||||
3. Add component: `RectTransform` (if not already present)
|
||||
4. Add component: `CanvasGroup` (optional, for fade effects)
|
||||
5. Add component: `AspectRatioFitter` (optional, to maintain card proportions)
|
||||
|
||||
**Card.cs Settings:**
|
||||
- Initial State: `IdleState`
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Add CardContext Component
|
||||
|
||||
1. On the same "Card" GameObject, add: `CardContext.cs`
|
||||
2. This component holds:
|
||||
- Card data reference
|
||||
- IsNew flag
|
||||
- IsClickable flag
|
||||
- RootTransform reference (auto-assigned)
|
||||
|
||||
**CardContext.cs Settings:**
|
||||
- Root Transform: (leave empty, auto-assigned in Awake)
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Add CardAnimator Component
|
||||
|
||||
1. On the same "Card" GameObject, add: `CardAnimator.cs`
|
||||
2. This component will handle all animations
|
||||
|
||||
**CardAnimator.cs Settings:**
|
||||
- Card Display: (assign in Step 4)
|
||||
- Visual Root: (assign the Card GameObject itself)
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Create CardDisplay Child
|
||||
|
||||
1. Create child GameObject under "Card" named "CardDisplay"
|
||||
2. Add component: `CardDisplay.cs`
|
||||
3. Add UI elements as children:
|
||||
- **CardImage** (Image) - main card artwork
|
||||
- **FrameImage** (Image) - rarity frame
|
||||
- **OverlayImage** (Image) - rarity overlay effects
|
||||
- **BackgroundImage** (Image) - zone background
|
||||
- **ZoneShapeImage** (Image) - zone symbol/shape
|
||||
- **CardNameText** (TextMeshProUGUI) - card name
|
||||
|
||||
**CardDisplay.cs Settings:**
|
||||
- Assign all the UI element references above
|
||||
- Visual Config: Assign your CardVisualConfig ScriptableObject
|
||||
|
||||
**Layout Tips:**
|
||||
- Use anchors to stretch images to fill the card
|
||||
- Layer order (back to front): Background → Zone Shape → Card Image → Frame → Overlay
|
||||
- Make sure all images have "Raycast Target" enabled for click detection
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Create CardBack Child (for flip animation)
|
||||
|
||||
1. Create child GameObject under "Card" named "CardBack"
|
||||
2. Add component: `Image`
|
||||
3. Assign your card back sprite
|
||||
4. Position/scale to match CardDisplay size
|
||||
|
||||
**Settings:**
|
||||
- Make sure it's initially hidden (will be shown by FlippingState)
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Create StateMachine Child
|
||||
|
||||
1. Create child GameObject under "Card" named "StateMachine"
|
||||
2. Add component: `AppleMachine` (from Pixelplacement)
|
||||
|
||||
**AppleMachine Settings:**
|
||||
- Starting State: `IdleState`
|
||||
- Debug: Enable if you want state transition logging
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Create State Children
|
||||
|
||||
Under "StateMachine", create these child GameObjects:
|
||||
|
||||
### 7a. IdleState
|
||||
- GameObject name: "IdleState"
|
||||
- Add component: `CardIdleState.cs`
|
||||
- Settings:
|
||||
- Hover Lift Distance: `20`
|
||||
- Hover Duration: `0.3`
|
||||
|
||||
### 7b. FlippingState
|
||||
- GameObject name: "FlippingState"
|
||||
- Add component: `CardFlippingState.cs`
|
||||
- Settings:
|
||||
- Flip Duration: `0.6`
|
||||
- Next State After Flip: `RevealedState`
|
||||
|
||||
### 7c. RevealedState
|
||||
- GameObject name: "RevealedState"
|
||||
- Add component: `CardRevealedState.cs`
|
||||
- Settings:
|
||||
- Scale: `1.5` (for NEW card emphasis)
|
||||
- Scale Duration: `0.5`
|
||||
|
||||
### 7d. DraggingState
|
||||
- GameObject name: "DraggingState"
|
||||
- Add component: `CardDraggingState.cs`
|
||||
- Settings:
|
||||
- Drag Scale: `1.2`
|
||||
- Drag Rotation: `5` degrees
|
||||
|
||||
### 7e. PlacedInSlotState
|
||||
- GameObject name: "PlacedInSlotState"
|
||||
- Add component: `CardPlacedInSlotState.cs`
|
||||
- Settings:
|
||||
- (Auto-configured when placed)
|
||||
|
||||
### 7f. AlbumEnlargedState
|
||||
- GameObject name: "AlbumEnlargedState"
|
||||
- Add component: `CardAlbumEnlargedState.cs`
|
||||
- Settings:
|
||||
- Enlarged Scale: `2.5`
|
||||
- Scale Duration: `0.3`
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Wire Up References
|
||||
|
||||
Go back to the root "Card" GameObject:
|
||||
|
||||
**Card.cs:**
|
||||
- Context: Drag the Card GameObject (auto-finds CardContext)
|
||||
- Animator: Drag the Card GameObject (auto-finds CardAnimator)
|
||||
- State Machine: Drag the "StateMachine" child
|
||||
|
||||
**CardAnimator.cs:**
|
||||
- Card Display: Drag the "CardDisplay" child
|
||||
- Visual Root: Drag the "Card" GameObject itself
|
||||
|
||||
**CardContext.cs:**
|
||||
- (Everything auto-assigned, nothing to wire)
|
||||
|
||||
---
|
||||
|
||||
## Step 9: Save as Prefab
|
||||
|
||||
1. Drag the "Card" GameObject into your Prefabs folder
|
||||
2. Name it: `Card.prefab` (or whatever you prefer)
|
||||
3. Delete the instance from the scene
|
||||
|
||||
---
|
||||
|
||||
## Step 10: Update Scene References
|
||||
|
||||
### BoosterOpeningPage
|
||||
- Find `BoosterOpeningPage` in your scene
|
||||
- Assign `cardPrefab` field → your new Card prefab
|
||||
|
||||
### AlbumViewPage
|
||||
- Find `AlbumViewPage` in your scene
|
||||
- Assign `cardPrefab` field → your new Card prefab
|
||||
|
||||
### AlbumCardSlot Prefab
|
||||
- Open your AlbumCardSlot prefab
|
||||
- Assign `cardPrefab` field → your new Card prefab
|
||||
|
||||
---
|
||||
|
||||
## Testing Your Prefab
|
||||
|
||||
### Test 1: Booster Opening
|
||||
1. Play the game
|
||||
2. Open a booster pack
|
||||
3. Cards should spawn face-down
|
||||
4. Click a card → it flips and reveals
|
||||
5. If NEW → shows enlarged with "NEW" indicator
|
||||
6. If REPEAT → shows progress bar
|
||||
7. Click to dismiss → flies to album icon
|
||||
|
||||
### Test 2: Album Placement
|
||||
1. After opening boosters, cards appear in bottom-right
|
||||
2. Drag a card → it scales up and rotates slightly
|
||||
3. Drop on valid slot → it snaps in and stays
|
||||
4. Drop outside → returns to original position
|
||||
|
||||
### Test 3: Album Viewing
|
||||
1. Go to album view
|
||||
2. Cards in slots should display normally
|
||||
3. Click a placed card → enlarges with backdrop
|
||||
4. Click again (or backdrop) → shrinks back to slot
|
||||
|
||||
---
|
||||
|
||||
## Common Issues & Fixes
|
||||
|
||||
### Cards don't flip
|
||||
- Check FlippingState is assigned in StateMachine
|
||||
- Verify CardBack GameObject exists and has sprite
|
||||
- Check CardAnimator has CardDisplay reference
|
||||
|
||||
### Cards don't respond to clicks
|
||||
- Make sure CardDisplay images have "Raycast Target" enabled
|
||||
- Check EventSystem exists in scene
|
||||
- Verify Card has CanvasGroup or Image for raycast blocking
|
||||
|
||||
### Animations don't play
|
||||
- Check CardAnimator reference is assigned
|
||||
- Verify Tween library (Pixelplacement) is imported
|
||||
- Check state components have correct duration values
|
||||
|
||||
### Cards stuck in one state
|
||||
- Enable StateMachine debug mode to see transitions
|
||||
- Check state scripts don't have infinite loops
|
||||
- Verify transition logic in state Enter/Exit methods
|
||||
|
||||
---
|
||||
|
||||
## Advanced: Customizing States
|
||||
|
||||
Want to add your own card behavior? Here's how:
|
||||
|
||||
1. Create new script inheriting from `AppleState`
|
||||
2. Override `Enter()`, `Exit()`, `UpdateState()` as needed
|
||||
3. Use `Card` reference to access context, animator, etc.
|
||||
4. Add GameObject under StateMachine with your new component
|
||||
5. Transition to it via `Card.ChangeState("YourStateName")`
|
||||
|
||||
Example:
|
||||
```csharp
|
||||
public class CardBurningState : AppleState
|
||||
{
|
||||
private Card _card;
|
||||
|
||||
public override void Enter(params object[] args)
|
||||
{
|
||||
_card = GetComponentInParent<Card>();
|
||||
// Play burning animation
|
||||
_card.Animator.PlayBurnEffect();
|
||||
}
|
||||
|
||||
public override void Exit()
|
||||
{
|
||||
// Clean up
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Final Checklist
|
||||
|
||||
Before considering your prefab complete:
|
||||
|
||||
- [ ] Root Card GameObject has Card, CardContext, CardAnimator components
|
||||
- [ ] CardDisplay child is set up with all UI elements
|
||||
- [ ] CardBack child exists for flip animation
|
||||
- [ ] StateMachine child has AppleMachine component
|
||||
- [ ] All 6 state children are created and configured
|
||||
- [ ] All references wired up on Card component
|
||||
- [ ] Prefab saved and assigned in scene controllers
|
||||
- [ ] Tested in both booster and album flows
|
||||
- [ ] No console errors when playing
|
||||
|
||||
---
|
||||
|
||||
## Need Help?
|
||||
|
||||
Refer to:
|
||||
- `card_system_migration_summary.md` - What changed and why
|
||||
- `card_architecture_plan.md` - Architecture overview
|
||||
- State script files - Implementation details
|
||||
|
||||
Happy card building! 🎴
|
||||
|
||||
@@ -1,295 +0,0 @@
|
||||
# Card System Integration - Completed Work Summary
|
||||
|
||||
**Date:** November 17, 2025
|
||||
**Status:** ✅ Completed
|
||||
|
||||
## Overview
|
||||
This document summarizes the completion of the new Card prefab integration into the Album UI system, addressing all errors and missing implementations from the proposal document.
|
||||
|
||||
---
|
||||
|
||||
## 1. Fixed CardFlippingPendingState Errors ✅
|
||||
|
||||
### Issues Found:
|
||||
- **Error**: Cannot access private method `FindPageForCard(CardData)`
|
||||
- **Warning**: Obsolete `FindObjectOfType` usage
|
||||
- **Warning**: Unused variable `targetPage`
|
||||
- **Warning**: Naming convention violations
|
||||
|
||||
### Solution:
|
||||
- Removed the navigation logic from `CardFlippingPendingState` (it's now handled by `AlbumViewPage.HandlePendingCardDragStart` before the state is entered)
|
||||
- Fixed naming conventions (renamed `context` → `_context`, `cardBack` → `_cardBack`)
|
||||
- Removed obsolete `FindObjectOfType` call
|
||||
- Removed unused `using Core;` directive
|
||||
- Added explanatory comment about navigation flow
|
||||
|
||||
**File:** `CardFlippingPendingState.cs`
|
||||
|
||||
---
|
||||
|
||||
## 2. Completed Missing Implementations ✅
|
||||
|
||||
### Smart Card Selection System
|
||||
Implemented the complete smart selection logic for the NEW face-down card system:
|
||||
|
||||
#### `SelectSmartPendingCard()`
|
||||
- Prioritizes cards that belong on the current album page
|
||||
- Falls back to random selection if no current-page match
|
||||
- Provides better UX by reducing page flipping
|
||||
|
||||
#### `GetDefinitionsOnCurrentPage()`
|
||||
- Scans all `AlbumCardSlot` components in the scene
|
||||
- Filters slots by current book page using hierarchy checks
|
||||
- Returns list of card definition IDs on the current page
|
||||
- Properly handles BookPro's `Paper` structure (Front/Back GameObjects)
|
||||
|
||||
#### `IsSlotOnPage(Transform, int)`
|
||||
- Helper method to check if a slot belongs to a specific book page
|
||||
- Traverses parent hierarchy to match against BookPro's Front/Back page GameObjects
|
||||
- Handles edge cases (null checks, bounds checking)
|
||||
|
||||
#### `FindPageForCard(CardData)`
|
||||
- Locates which album page contains the slot for a given card
|
||||
- Searches all `AlbumCardSlot` components to match definition ID
|
||||
- Returns page index for navigation
|
||||
|
||||
#### `NavigateToAlbumPage(int)`
|
||||
- Uses BookPro's `AutoFlip` component to navigate to target page
|
||||
- Creates AutoFlip component if it doesn't exist
|
||||
- Skips navigation if already on target page
|
||||
- Provides smooth page transitions during card drag
|
||||
|
||||
**File:** `AlbumViewPage.cs`
|
||||
|
||||
---
|
||||
|
||||
## 3. Clarified Duplicate Logic ✅
|
||||
|
||||
### Current Situation:
|
||||
The codebase contains TWO card spawning systems:
|
||||
|
||||
#### OLD SYSTEM (Currently Active)
|
||||
- **Method:** `SpawnPendingCards()`
|
||||
- **Behavior:** Spawns cards already revealed (face-up)
|
||||
- **State:** `SetupForAlbumPlacement` → starts in `RevealedState`
|
||||
- **Flow:** Simple drag-and-drop, no mystery/engagement
|
||||
- **Status:** ⚠️ Active but marked for potential replacement
|
||||
|
||||
#### NEW SYSTEM (Fully Implemented, Not Yet Active)
|
||||
- **Method:** `SpawnPendingCornerCards()`
|
||||
- **Behavior:** Spawns face-down mystery cards
|
||||
- **State:** `SetupForAlbumPending` → starts in `PendingFaceDownState`
|
||||
- **Flow:**
|
||||
1. User drags face-down card
|
||||
2. `HandlePendingCardDragStart()` assigns smart-selected data
|
||||
3. Page auto-navigates to correct location
|
||||
4. Card flips to reveal (`FlippingPendingState`)
|
||||
5. User completes drag to album slot (`DraggingRevealedState`)
|
||||
- **Status:** ✅ Complete and ready to activate
|
||||
|
||||
### Documentation Added:
|
||||
- Clear `#region` markers separating OLD and NEW systems
|
||||
- Detailed comments explaining each system's purpose
|
||||
- Migration instructions in comments
|
||||
- Both systems are functional - project can choose which to use
|
||||
|
||||
**File:** `AlbumViewPage.cs`
|
||||
|
||||
---
|
||||
|
||||
## 4. Additional Enhancements ✅
|
||||
|
||||
### State-Owned Visual Pattern
|
||||
Updated **CardPendingFaceDownState** and **CardFlippingPendingState** to follow the same pattern as **CardIdleState**:
|
||||
- CardBack visuals are **owned by each state** via `[SerializeField] private GameObject cardBackVisual`
|
||||
- States that need a card back (IdleState, PendingFaceDownState, FlippingPendingState) each have their own reference
|
||||
- This allows different states to use different back visuals if needed
|
||||
|
||||
### Prefab Structure
|
||||
Your Card prefab hierarchy should look like:
|
||||
```
|
||||
Card (root)
|
||||
├── CardContext
|
||||
├── CardAnimator
|
||||
├── CardDisplay (front visuals)
|
||||
└── StateMachine
|
||||
├── IdleState
|
||||
│ └── CardBackVisual (child of IdleState)
|
||||
├── PendingFaceDownState
|
||||
│ └── CardBackVisual (child of PendingFaceDownState)
|
||||
├── FlippingPendingState
|
||||
│ └── CardBackVisual (child of FlippingPendingState)
|
||||
├── RevealedState
|
||||
├── DraggingState
|
||||
├── DraggingRevealedState
|
||||
└── PlacedInSlotState
|
||||
```
|
||||
|
||||
**Important:** Each state that shows a card back owns its own CardBackVisual GameObject as a child. You assign this reference in the Inspector via the state's `cardBackVisual` field.
|
||||
|
||||
### AlbumCardSlot
|
||||
- Added `GetTargetCardDefinition()` method for compatibility with smart selection system
|
||||
- Properly exposes `TargetCardDefinition` property
|
||||
|
||||
**Files Modified:**
|
||||
- `CardPendingFaceDownState.cs`
|
||||
- `CardFlippingPendingState.cs`
|
||||
- `AlbumCardSlot.cs`
|
||||
|
||||
---
|
||||
|
||||
## Code Quality Notes
|
||||
|
||||
### Remaining Warnings (Non-Critical):
|
||||
- Naming convention warnings in `AlbumViewPage.cs`:
|
||||
- `zoneTabs` → suggested `_zoneTabs`
|
||||
- `MAX_VISIBLE_CARDS` → suggested `MaxVisibleCards`
|
||||
- `MAX_PENDING_CORNER` → suggested `MaxPendingCorner`
|
||||
|
||||
These are style warnings only and don't affect functionality.
|
||||
|
||||
### All Compile Errors Resolved:
|
||||
- ✅ `CardFlippingPendingState.cs` - No errors
|
||||
- ✅ `CardPendingFaceDownState.cs` - No errors
|
||||
- ✅ `CardDraggingRevealedState.cs` - No errors
|
||||
- ✅ `AlbumViewPage.cs` - No errors
|
||||
- ✅ `AlbumCardSlot.cs` - No errors
|
||||
|
||||
---
|
||||
|
||||
## How to Activate the NEW System
|
||||
|
||||
To switch from OLD to NEW face-down card system:
|
||||
|
||||
1. In `AlbumViewPage.cs`, find calls to `SpawnPendingCards()`
|
||||
2. Replace with `SpawnPendingCornerCards()`
|
||||
3. Test the flow:
|
||||
- Cards spawn face-down in corner
|
||||
- Dragging assigns data via smart selection
|
||||
- Page navigates automatically
|
||||
- Card flips to reveal
|
||||
- Drag completes to album slot
|
||||
|
||||
**Locations to change:**
|
||||
- `TransitionIn()` - Line ~273
|
||||
- `OnPageFlipped()` - Line ~390
|
||||
|
||||
---
|
||||
|
||||
## State Machine Flow (NEW System)
|
||||
|
||||
The flip animation is handled during the state transition (following the same pattern as IdleState → RevealedState):
|
||||
|
||||
```
|
||||
PendingFaceDownState
|
||||
↓ (user drags - triggers OnDragStarted)
|
||||
↓ (data assigned by AlbumViewPage)
|
||||
↓ (page navigates to correct location)
|
||||
↓ (flip animation plays)
|
||||
↓ (onComplete callback)
|
||||
DraggingRevealedState
|
||||
↓ (user drops on album slot)
|
||||
PlacedInSlotState
|
||||
```
|
||||
|
||||
**Key Design Decision:**
|
||||
- ❌ No separate "FlippingPendingState" - flip is a transition, not a state
|
||||
- ✅ Follows existing pattern from IdleState (which flips in OnCardClicked, then transitions)
|
||||
- ✅ PendingFaceDownState.OnDragStarted() handles: data assignment request, page navigation request, flip animation, and transition to DraggingRevealedState
|
||||
- ✅ Cleaner state machine with fewer states
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Why No FlippingPendingState?
|
||||
Looking at the existing codebase, **CardIdleState** already demonstrates the correct pattern:
|
||||
- When clicked, it plays the flip animation
|
||||
- When flip completes (`onComplete` callback), it transitions to the next state
|
||||
- The flip is part of the **exit transition**, not a separate state
|
||||
|
||||
We follow the same pattern for pending cards:
|
||||
- **PendingFaceDownState** handles drag start
|
||||
- Plays flip animation with `onComplete` callback
|
||||
- Transitions to **DraggingRevealedState** when flip completes
|
||||
|
||||
This keeps the state count minimal and follows established patterns in the codebase.
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [x] CardFlippingPendingState compiles without errors
|
||||
- [x] Smart selection logic implemented
|
||||
- [x] Page navigation logic implemented
|
||||
- [x] Book page hierarchy detection works with BookPro structure
|
||||
- [x] Both OLD and NEW systems clearly documented
|
||||
- [x] AlbumCardSlot exposes necessary properties
|
||||
- [ ] Runtime testing of NEW system (requires manual testing)
|
||||
- [ ] Verify page navigation smoothness
|
||||
- [ ] Test edge cases (no pending cards, invalid pages, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
All identified issues have been resolved:
|
||||
1. ✅ **CardFlippingPendingState error fixed** - Removed invalid private method call
|
||||
2. ✅ **Missing implementations completed** - All smart selection and navigation logic working
|
||||
3. ✅ **Duplicate logic addressed** - Both systems documented, ready for decision
|
||||
|
||||
The NEW card system is fully implemented and ready for activation. The project can now choose to:
|
||||
- Continue using the OLD face-up system
|
||||
- Switch to the NEW face-down system with smart selection
|
||||
- Run both in parallel for A/B testing
|
||||
|
||||
All code is production-ready with proper error handling, logging, and documentation.
|
||||
|
||||
---
|
||||
|
||||
## Final Architecture: Generic Event System
|
||||
|
||||
**Latest Refactor:** The system now uses a **generic event pattern** instead of state-specific events.
|
||||
|
||||
### Generic OnDragStarted Event
|
||||
|
||||
**CardContext** exposes a single generic event:
|
||||
```csharp
|
||||
public event Action<CardContext> OnDragStarted;
|
||||
```
|
||||
|
||||
**Card.cs** emits this event for **all** drag starts (not just pending cards):
|
||||
```csharp
|
||||
protected override void OnDragStartedHook()
|
||||
{
|
||||
base.OnDragStartedHook();
|
||||
context?.NotifyDragStarted(); // Generic event for all consumers
|
||||
// Then state-specific logic...
|
||||
}
|
||||
```
|
||||
|
||||
**AlbumViewPage** subscribes and checks state:
|
||||
```csharp
|
||||
private void OnCardDragStarted(CardContext context)
|
||||
{
|
||||
var stateName = context.StateMachine?.currentState?.name;
|
||||
|
||||
// Only handle pending cards
|
||||
if (stateName == "PendingFaceDownState")
|
||||
{
|
||||
// Assign data, navigate page, etc.
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Benefits of Generic Events:
|
||||
|
||||
✅ **Reusable** - Any system can subscribe to card drag starts
|
||||
✅ **Flexible** - Consumers decide what to do based on card state
|
||||
✅ **Decoupled** - Cards have zero knowledge of consumers
|
||||
✅ **Extensible** - Easy to add new drag behaviors without changing Card.cs
|
||||
✅ **Clean** - Single event pattern, not one event per state
|
||||
|
||||
This pattern allows future systems (tutorials, analytics, achievements, etc.) to also react to card drags without modifying the card system itself.
|
||||
|
||||
|
||||
@@ -1,215 +0,0 @@
|
||||
# Card System Migration Summary
|
||||
|
||||
## Overview
|
||||
Successfully migrated the card UI system from the old wrapper-based approach (AlbumCard, FlippableCard) to the new state-based Card system using PixelPlacement's StateMachine.
|
||||
|
||||
## Date
|
||||
Migration completed: November 16, 2025
|
||||
|
||||
---
|
||||
|
||||
## Changes Made
|
||||
|
||||
### 1. CardDisplay.cs - Simplified Click Handling
|
||||
**Changes:**
|
||||
- Removed `_isPreviewMode` and `_previewSlot` tracking
|
||||
- Removed `SetPreviewMode()` and preview visual methods (`SetPreviewVisuals`, `ClearPreviewVisuals`)
|
||||
- Simplified `OnPointerClick()` to only emit `OnCardClicked` event
|
||||
- No more parent-seeking or type-checking logic
|
||||
|
||||
**Impact:**
|
||||
- CardDisplay is now a pure "dumb" visual renderer + click detector
|
||||
- Any wrapper can subscribe to click events without tight coupling
|
||||
- Preview functionality moved to card states
|
||||
|
||||
---
|
||||
|
||||
### 2. AlbumCardSlot.cs - Updated to New Card System
|
||||
**Changes:**
|
||||
- Changed from `AlbumCard` references to `StateMachine.Card`
|
||||
- Removed `IPointerClickHandler` interface (no more manual preview clicks)
|
||||
- Removed all preview-related fields and methods:
|
||||
- `previewCardDisplay`
|
||||
- `_isPreviewShowing`
|
||||
- `_previewOriginalScale`
|
||||
- `SetupPreviewCard()`
|
||||
- `ShowPreview()`
|
||||
- `HidePreview()`
|
||||
- `OnPointerClick()`
|
||||
- `DismissPreview()`
|
||||
- Updated `SpawnCard()` to use `Card.SetupForAlbumSlot()` with `PlacedInSlotState`
|
||||
- Removed registration with AlbumViewPage (no longer needed)
|
||||
- Changed `albumCardPrefab` field to `cardPrefab`
|
||||
|
||||
**Impact:**
|
||||
- Slots now spawn cards in the `PlacedInSlotState` directly
|
||||
- Preview functionality will be handled by card states if needed in the future
|
||||
- Cleaner, simpler slot logic focused only on validation and spawning
|
||||
|
||||
---
|
||||
|
||||
### 3. AlbumViewPage.cs - Removed Legacy Support
|
||||
**Changes:**
|
||||
- Removed legacy `AlbumCard` registration methods:
|
||||
- `RegisterAlbumCard()`
|
||||
- `UnregisterAlbumCard()`
|
||||
- `OnCardEnlargeRequested(AlbumCard)`
|
||||
- `OnCardShrinkRequested(AlbumCard)`
|
||||
- Removed slot preview helper methods:
|
||||
- `ShowSlotPreview()`
|
||||
- `HideSlotPreview()`
|
||||
- Kept only new Card system methods:
|
||||
- `RegisterCardInAlbum(StateMachine.Card)`
|
||||
- `UnregisterCardInAlbum(StateMachine.Card)`
|
||||
- `OnCardEnlargeRequested(CardAlbumEnlargedState)`
|
||||
- `OnCardShrinkRequested(CardAlbumEnlargedState)`
|
||||
|
||||
**Impact:**
|
||||
- Page only manages backdrop and reparenting for card enlarge states
|
||||
- No more manual preview management
|
||||
- Cleaner event-based architecture
|
||||
|
||||
---
|
||||
|
||||
### 4. BoosterOpeningPage.cs - Already Updated
|
||||
**Status:**
|
||||
- Already using new `StateMachine.Card` system
|
||||
- Uses `CardContext` for setup and event handling
|
||||
- No changes required - already migrated!
|
||||
|
||||
**Current Flow:**
|
||||
1. Spawns Card prefab with CardContext
|
||||
2. Calls `context.SetupCard()` and `card.SetupForBoosterReveal()`
|
||||
3. Subscribes to `context.OnFlipComplete` and `context.OnCardInteractionComplete`
|
||||
4. Cards handle their own flip and reveal states
|
||||
|
||||
---
|
||||
|
||||
### 5. DEPRECATED Folder - Deleted
|
||||
**Deleted Classes:**
|
||||
- `AlbumCard.cs`
|
||||
- `FlippableCard.cs`
|
||||
- `AlbumCardPlacementDraggable.cs`
|
||||
- `CardDraggable.cs`
|
||||
- `CardDraggableVisual.cs`
|
||||
- `CardInteractionHandler.cs`
|
||||
|
||||
**Justification:**
|
||||
- No longer referenced anywhere in the codebase
|
||||
- All functionality replaced by state-based Card system
|
||||
- Keeping them would cause confusion
|
||||
|
||||
---
|
||||
|
||||
## Architecture Benefits
|
||||
|
||||
### Event-Based Communication
|
||||
- **Old:** Parent-seeking, type-checking, manual forwarding
|
||||
- **New:** Clean pub/sub pattern, decoupled components
|
||||
|
||||
### State Management
|
||||
- **Old:** Multiple wrapper classes (FlippableCard → AlbumCard → CardDisplay)
|
||||
- **New:** Single Card component + isolated state objects
|
||||
|
||||
### Code Reuse
|
||||
- **Old:** Repeated animation/behavior code in each wrapper
|
||||
- **New:** Shared CardAnimator, reusable state behaviors
|
||||
|
||||
### Flexibility
|
||||
- **Old:** Hard to add new card contexts (preview, enlarged, etc.)
|
||||
- **New:** Just add a new state - no wrapper changes needed
|
||||
|
||||
---
|
||||
|
||||
## Current Card State Flow
|
||||
|
||||
### Booster Opening Flow
|
||||
1. Spawn Card with `SetupForBoosterReveal()` → starts in `IdleState`
|
||||
2. User clicks → transitions to `FlippingState`
|
||||
3. Flip completes → transitions to `RevealedState` (new/repeat logic)
|
||||
4. User interacts → card animates to album icon, destroyed
|
||||
|
||||
### Album Placement Flow
|
||||
1. Spawn Card with `SetupForAlbumPlacement()` → starts in `RevealedState`
|
||||
2. User drags → transitions to `DraggingState`
|
||||
3. Dropped in slot → transitions to `PlacedInSlotState`
|
||||
4. User clicks placed card → transitions to `AlbumEnlargedState`
|
||||
5. User dismisses → back to `PlacedInSlotState`
|
||||
|
||||
### Album Slot Auto-Spawn
|
||||
1. AlbumCardSlot checks owned cards on Enable
|
||||
2. If owned, spawns Card with `SetupForAlbumSlot()` → starts in `PlacedInSlotState`
|
||||
3. Card sits in slot, ready for enlarge interaction
|
||||
|
||||
---
|
||||
|
||||
## What's Next
|
||||
|
||||
### Prefab Setup Required
|
||||
You'll need to update your prefabs to use the new Card structure:
|
||||
|
||||
**Old Prefab Structure:**
|
||||
```
|
||||
FlippableCard (or AlbumCard)
|
||||
└── CardDisplay
|
||||
└── [visual elements]
|
||||
```
|
||||
|
||||
**New Prefab Structure:**
|
||||
```
|
||||
Card (Card.cs component)
|
||||
├── CardDisplay (visual renderer)
|
||||
│ └── [visual elements: image, frame, overlay, etc.]
|
||||
└── StateMachine (AppleMachine component)
|
||||
├── IdleState (CardIdleState)
|
||||
├── FlippingState (CardFlippingState)
|
||||
├── RevealedState (CardRevealedState)
|
||||
├── DraggingState (CardDraggingState)
|
||||
├── PlacedInSlotState (CardPlacedInSlotState)
|
||||
└── AlbumEnlargedState (CardAlbumEnlargedState)
|
||||
```
|
||||
|
||||
### Configuration References
|
||||
Make sure to update these references in your scenes:
|
||||
- **BoosterOpeningPage:** `cardPrefab` field → assign new Card prefab
|
||||
- **AlbumViewPage:** `cardPrefab` field → assign new Card prefab
|
||||
- **AlbumCardSlot:** `cardPrefab` field → assign new Card prefab
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] Booster opening flow works correctly
|
||||
- [ ] Cards flip and reveal properly
|
||||
- [ ] New/repeat card logic displays correctly
|
||||
- [ ] Cards can be dragged from pending list to album slots
|
||||
- [ ] Cards snap into album slots correctly
|
||||
- [ ] Placed cards can be enlarged when clicked
|
||||
- [ ] Enlarged cards can be dismissed
|
||||
- [ ] Empty slots no longer show preview (feature removed for now)
|
||||
- [ ] No console errors or null references
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
### Preview Functionality
|
||||
The old preview system (showing locked cards in empty slots) has been removed. If you want to re-implement this:
|
||||
1. Create a new `EmptySlotPreviewState`
|
||||
2. Have empty AlbumCardSlots spawn a Card in this state
|
||||
3. State handles the greyed-out visuals and enlarge/shrink
|
||||
|
||||
### Backwards Compatibility
|
||||
**None.** This is a breaking change. Old prefabs using AlbumCard/FlippableCard will not work and must be updated.
|
||||
|
||||
### Performance
|
||||
The new system is more efficient:
|
||||
- Fewer component lookups (no parent-seeking)
|
||||
- State objects pooled per card (not created/destroyed)
|
||||
- Cleaner event subscription (no manual chain management)
|
||||
|
||||
---
|
||||
|
||||
## Questions?
|
||||
Refer to the implementation plan documents or the state machine architecture document for more details.
|
||||
|
||||
@@ -1,314 +0,0 @@
|
||||
# CARD STATE MACHINE - COMPLETE IMPLEMENTATION PACKAGE 📦
|
||||
|
||||
## 🎯 What You Asked For
|
||||
✅ Continue implementing the suggested card state machine architecture
|
||||
✅ Create any missing code
|
||||
✅ Provide instructions on assembling prefab combining old and new code
|
||||
|
||||
## ✅ What's Been Delivered
|
||||
|
||||
### CODE (13 Files - All Complete & Ready)
|
||||
|
||||
**Core System:**
|
||||
1. `Card.cs` - Main controller with setup API
|
||||
2. `CardContext.cs` - Shared context for all states
|
||||
3. `CardAnimator.cs` - Centralized animation controller
|
||||
4. `CardAnimationConfig.cs` - ScriptableObject for settings
|
||||
|
||||
**State Implementations:**
|
||||
5. `CardIdleState.cs` - Hover animation, click to flip
|
||||
6. `CardFlippingState.cs` - Flip animation (owns CardBackVisual)
|
||||
7. `CardRevealedState.cs` - Post-flip waiting state
|
||||
8. `CardEnlargedNewState.cs` - New card enlarged (owns NewCardBadge)
|
||||
9. `CardEnlargedRepeatState.cs` - Repeat card enlarged (owns ProgressBarUI)
|
||||
10. `CardDraggingState.cs` - Drag feedback state
|
||||
11. `CardPlacedInSlotState.cs` - In album slot state
|
||||
12. `CardAlbumEnlargedState.cs` - Enlarged from album state
|
||||
13. `CardInteractionHandler.cs` - Optional drag/drop bridge
|
||||
|
||||
**Status:** All files compile-ready. No placeholders. Production-ready code.
|
||||
|
||||
---
|
||||
|
||||
### 📚 DOCUMENTATION (7 Files)
|
||||
|
||||
1. **`README_CARD_SYSTEM.md`** ⭐ **← YOU ARE HERE**
|
||||
2. **`card_prefab_assembly_guide.md`** ⭐ **← YOUR MAIN GUIDE FOR UNITY**
|
||||
3. **`card_prefab_visual_reference.md`** - Visual hierarchy diagrams
|
||||
4. **`card_state_machine_quick_reference.md`** - State flow + API
|
||||
5. **`card_migration_strategy.md`** ⭐ **← OLD SCRIPTS MIGRATION**
|
||||
6. **`card_system_architecture_audit.md`** - Original audit
|
||||
7. **`card_system_implementation_summary.md`** - Architecture decisions
|
||||
|
||||
---
|
||||
|
||||
## ❓ What About Old Scripts?
|
||||
|
||||
**Q: Are FlippableCard, AlbumCard, etc. still needed?**
|
||||
|
||||
**A: NO - they will be REPLACED by the new system.**
|
||||
|
||||
### What Stays ✅
|
||||
- **`CardDisplay.cs`** - Pure visual renderer, used by BOTH systems. **Keep it forever!**
|
||||
|
||||
### What Gets Replaced 🔄
|
||||
- **`FlippableCard.cs`** → Replaced by `Card.cs` with state machine
|
||||
- **`AlbumCard.cs`** → Replaced by `CardPlacedInSlotState` + `CardAlbumEnlargedState`
|
||||
- **`AlbumCardPlacementDraggable.cs`** → Replaced by `Card.cs` with `CardDraggingState`
|
||||
|
||||
### Migration Timeline
|
||||
|
||||
**→ See full details: `card_migration_strategy.md`**
|
||||
|
||||
**TL;DR Migration Path:**
|
||||
1. ✅ **Phase 1:** Build new Card.prefab (you do this first - ~45 min)
|
||||
2. 🔄 **Phase 2:** Replace booster opening flow (~2-4 hours)
|
||||
3. 🔄 **Phase 3:** Replace album system (~4-6 hours)
|
||||
4. 🗑️ **Phase 4:** Delete old scripts (~1 hour)
|
||||
|
||||
**Total: ~10 hours spread across 2-3 weeks. Both systems coexist safely during migration!**
|
||||
|
||||
**Key insight:** You're not fixing bugs - you're replacing the architecture. The old scripts work but are built on wrapper hell. New system uses isolated states.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Architecture Summary
|
||||
|
||||
### Old System Problems
|
||||
- 5 layers of nested wrappers
|
||||
- ~150 lines of duplicate animation code
|
||||
- 12+ boolean flags for state tracking
|
||||
- Complex event callback chains
|
||||
- Hard to debug, hard to extend
|
||||
|
||||
### New System Solution
|
||||
- **Isolated states** using Pixelplacement StateMachine
|
||||
- States own their visual elements (CardBackVisual, etc.)
|
||||
- **Shared CardAnimator** eliminates duplication
|
||||
- Clean state transitions via state machine
|
||||
- Single Card component as entry point
|
||||
|
||||
### Key Innovation
|
||||
**State-owned visuals:** When FlippingState activates, CardBackVisual (its child) automatically activates. When state deactivates, visual deactivates. No manual visibility management!
|
||||
|
||||
```
|
||||
FlippingState GameObject (inactive)
|
||||
└─ CardBackVisual (inactive)
|
||||
|
||||
↓ [State machine activates FlippingState]
|
||||
|
||||
FlippingState GameObject (🟢 ACTIVE)
|
||||
└─ CardBackVisual (🟢 ACTIVE & VISIBLE)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 YOUR NEXT STEPS
|
||||
|
||||
### STEP 1: Create the Asset (2 minutes)
|
||||
1. Open Unity
|
||||
2. Right-click in `Assets/Data/CardSystem/`
|
||||
3. Create → AppleHills → **Card Animation Config**
|
||||
4. Name it `CardAnimationConfig`
|
||||
5. Set values (see guide for details)
|
||||
|
||||
### STEP 2: Build the Prefab (45 minutes)
|
||||
**Follow:** `card_prefab_assembly_guide.md`
|
||||
|
||||
Quick overview:
|
||||
1. Create root "Card" GameObject with RectTransform
|
||||
2. Add Card, CardContext, CardAnimator components
|
||||
3. Add CardDisplay child (use existing or create new)
|
||||
4. Create CardStateMachine child with AppleMachine
|
||||
5. Create 8 state GameObjects under CardStateMachine
|
||||
6. Add state-owned visuals (CardBackVisual, NewCardBadge, ProgressBarUI)
|
||||
7. Wire all references
|
||||
8. Test in Play mode
|
||||
9. Save as prefab
|
||||
|
||||
### STEP 3: Test Integration (30 minutes)
|
||||
Replace one FlippableCard usage with new Card:
|
||||
|
||||
**Old:**
|
||||
```csharp
|
||||
FlippableCard card = Instantiate(flippableCardPrefab, parent);
|
||||
card.SetupCard(cardData);
|
||||
```
|
||||
|
||||
**New:**
|
||||
```csharp
|
||||
Card card = Instantiate(cardPrefab, parent);
|
||||
card.SetupForBoosterReveal(cardData, isNew: true);
|
||||
```
|
||||
|
||||
### STEP 4: Migrate Gradually (Optional but Recommended)
|
||||
Once you have a working Card.prefab:
|
||||
- Keep old system running in album scenes
|
||||
- Replace booster opening first (easier)
|
||||
- Then replace album system
|
||||
- Finally delete old scripts
|
||||
|
||||
**See `card_migration_strategy.md` for detailed migration plan**
|
||||
|
||||
---
|
||||
|
||||
## 🎓 How To Use New System
|
||||
|
||||
### Basic Setup
|
||||
```csharp
|
||||
// Booster reveal flow (starts at IdleState)
|
||||
card.SetupForBoosterReveal(cardData, isNew: true);
|
||||
|
||||
// Album slot flow (starts at PlacedInSlotState)
|
||||
card.SetupForAlbumSlot(cardData, slot);
|
||||
```
|
||||
|
||||
### Manual State Control
|
||||
```csharp
|
||||
// Change state
|
||||
card.ChangeState("FlippingState");
|
||||
|
||||
// Get current state
|
||||
string currentState = card.GetCurrentStateName();
|
||||
|
||||
// Access specific state component
|
||||
var idleState = card.GetStateComponent<CardIdleState>("IdleState");
|
||||
```
|
||||
|
||||
### State Flow Example
|
||||
```
|
||||
Player opens booster pack:
|
||||
├─ Card spawns in IdleState
|
||||
├─ [Player clicks] → FlippingState
|
||||
├─ [Flip completes + isNew] → EnlargedNewState
|
||||
├─ [Player taps] → RevealedState
|
||||
└─ [Player drags to album] → DraggingState → PlacedInSlotState
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 File Locations
|
||||
|
||||
**Created Scripts:**
|
||||
```
|
||||
Assets/Scripts/UI/CardSystem/StateMachine/
|
||||
├─ Card.cs
|
||||
├─ CardContext.cs
|
||||
├─ CardAnimator.cs
|
||||
├─ CardAnimationConfig.cs
|
||||
└─ States/
|
||||
├─ CardIdleState.cs
|
||||
├─ CardFlippingState.cs
|
||||
├─ CardRevealedState.cs
|
||||
├─ CardEnlargedNewState.cs
|
||||
├─ CardEnlargedRepeatState.cs
|
||||
├─ CardDraggingState.cs
|
||||
├─ CardPlacedInSlotState.cs
|
||||
├─ CardAlbumEnlargedState.cs
|
||||
└─ CardInteractionHandler.cs
|
||||
```
|
||||
|
||||
**Documentation:**
|
||||
```
|
||||
docs/
|
||||
├─ README_CARD_SYSTEM.md ← YOU ARE HERE
|
||||
├─ card_prefab_assembly_guide.md ← BUILD PREFAB
|
||||
├─ card_migration_strategy.md ← OLD SCRIPTS INFO
|
||||
├─ card_prefab_visual_reference.md
|
||||
├─ card_state_machine_quick_reference.md
|
||||
├─ card_system_architecture_audit.md
|
||||
└─ card_system_implementation_summary.md
|
||||
```
|
||||
|
||||
**To Create in Unity:**
|
||||
```
|
||||
Assets/Data/CardSystem/
|
||||
└─ CardAnimationConfig.asset (ScriptableObject)
|
||||
|
||||
Assets/Prefabs/UI/CardSystem/
|
||||
└─ Card.prefab (to be created by you)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Success Criteria
|
||||
|
||||
You'll know it's working when:
|
||||
|
||||
1. ✅ Card prefab exists with 8 state children
|
||||
2. ✅ Clicking idle card triggers flip animation
|
||||
3. ✅ CardBackVisual shows during flip, hides after
|
||||
4. ✅ New cards show "NEW CARD" badge when enlarged
|
||||
5. ✅ Repeat cards show "3/5" progress bar
|
||||
6. ✅ Cards can be placed in album slots
|
||||
7. ✅ Cards in album enlarge when clicked
|
||||
8. ✅ No console errors during transitions
|
||||
9. ✅ Performance is smooth (60fps)
|
||||
10. ✅ You can add new states without touching existing code
|
||||
|
||||
---
|
||||
|
||||
## 🆘 If You Get Stuck
|
||||
|
||||
**Can't find where to start?**
|
||||
→ Open `card_prefab_assembly_guide.md` and follow Step 1
|
||||
|
||||
**Confused about hierarchy?**
|
||||
→ Open `card_prefab_visual_reference.md` for visual diagrams
|
||||
|
||||
**Need code examples?**
|
||||
→ Open `card_state_machine_quick_reference.md` for patterns
|
||||
|
||||
**Wondering about old scripts?**
|
||||
→ Open `card_migration_strategy.md` for migration plan
|
||||
|
||||
**Want to understand why?**
|
||||
→ Open `card_system_architecture_audit.md` for deep dive
|
||||
|
||||
**States not transitioning?**
|
||||
→ Enable "Verbose" on AppleMachine, check console logs
|
||||
|
||||
**References null?**
|
||||
→ Check "Wire References" section in assembly guide
|
||||
|
||||
---
|
||||
|
||||
## 📊 Metrics: Old vs New
|
||||
|
||||
| Metric | Old System | New System |
|
||||
|--------|------------|------------|
|
||||
| Lines of code | ~1,200 | ~500 (-60%) |
|
||||
| Animation code locations | 4 files | 1 file |
|
||||
| State tracking | 12+ booleans | 1 state machine |
|
||||
| Prefab nesting | 5 layers | Flat + state children |
|
||||
| Event chains | 12+ events | 3-4 events |
|
||||
| Time to add new state | 4-6 hours | ~30 minutes |
|
||||
| Code duplication | ~150 lines | 0 lines |
|
||||
|
||||
---
|
||||
|
||||
## 🎉 You're All Set!
|
||||
|
||||
**Status: IMPLEMENTATION COMPLETE**
|
||||
|
||||
All code is written. All documentation is ready. The architecture is solid.
|
||||
|
||||
**Your job:**
|
||||
1. Open Unity
|
||||
2. Follow `card_prefab_assembly_guide.md`
|
||||
3. Build the Card.prefab
|
||||
4. Test it
|
||||
5. Gradually migrate from old system
|
||||
|
||||
**Time investment:** ~2 hours for first working implementation.
|
||||
|
||||
**Return on investment:** 60% less code, infinitely more maintainable, easy to extend.
|
||||
|
||||
**Good luck!** 🚀
|
||||
|
||||
---
|
||||
|
||||
_Last updated: November 11, 2025_
|
||||
_Implementation by: Senior Software Engineer (AI Assistant)_
|
||||
_Architecture: Isolated State Pattern with Pixelplacement StateMachine_
|
||||
_Status: Production-ready, awaiting Unity prefab creation_
|
||||
@@ -1 +0,0 @@
|
||||
|
||||
@@ -1,291 +0,0 @@
|
||||
# Card Drag/Drop Integration - Refactor Summary
|
||||
|
||||
## What Was Changed
|
||||
|
||||
### ✅ **Files Modified:**
|
||||
|
||||
1. **Card.cs** - Now inherits from `DraggableObject`
|
||||
- Added drag event hooks (`OnDragStartedHook`, `OnDragEndedHook`)
|
||||
- Added setup methods for different flows (booster, album placement, album slot)
|
||||
- Changed `Awake()` to `Initialize()` to match DraggableObject pattern
|
||||
|
||||
2. **CardDraggingState.cs** - Simplified to visual-only
|
||||
- Removed position update methods (handled by DraggableObject base)
|
||||
- Kept scale animation for visual feedback
|
||||
- Removed redundant methods (`UpdateDragPosition`, `OnDroppedInSlot`, etc.)
|
||||
|
||||
### ✅ **Files Moved to DEPRECATED:**
|
||||
|
||||
- `CardDraggable.cs` → `DEPRECATED/` (redundant wrapper)
|
||||
- `CardDraggableVisual.cs` → `DEPRECATED/` (tied to old system)
|
||||
- `FlippableCard.cs` → `DEPRECATED/` (old card implementation)
|
||||
|
||||
**Note:** AlbumCardPlacementDraggable.cs remains in DragDrop/ for now (used by album corner cards)
|
||||
|
||||
---
|
||||
|
||||
## How It Works Now
|
||||
|
||||
### **Card.cs Inheritance Chain:**
|
||||
```
|
||||
Card → DraggableObject → MonoBehaviour
|
||||
```
|
||||
|
||||
Card now has all DraggableObject capabilities:
|
||||
- ✅ Drag/drop detection (OnBeginDrag, OnDrag, OnEndDrag)
|
||||
- ✅ Slot detection and snapping
|
||||
- ✅ Pointer events (OnPointerEnter, OnPointerExit, etc.)
|
||||
- ✅ Enable/disable dragging via `SetDraggingEnabled(bool)`
|
||||
|
||||
### **Drag Event Flow:**
|
||||
|
||||
```
|
||||
1. Player starts dragging card
|
||||
↓
|
||||
2. DraggableObject.OnBeginDrag() fires
|
||||
↓
|
||||
3. Calls Card.OnDragStartedHook()
|
||||
↓
|
||||
4. Card transitions to DraggingState
|
||||
↓
|
||||
5. DraggingState.OnEnterState() scales card up (visual feedback)
|
||||
↓
|
||||
6. Player drags (DraggableObject handles position updates)
|
||||
↓
|
||||
7. Player releases drag
|
||||
↓
|
||||
8. DraggableObject.OnEndDrag() fires
|
||||
↓
|
||||
9. DraggableObject finds closest slot
|
||||
↓
|
||||
10. Calls Card.OnDragEndedHook()
|
||||
↓
|
||||
11. Card checks if dropped in AlbumCardSlot:
|
||||
- YES → Transition to PlacedInSlotState
|
||||
- NO → Transition to RevealedState
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Setup Methods
|
||||
|
||||
### **For Booster Opening Flow:**
|
||||
```csharp
|
||||
card.SetupForBoosterReveal(cardData, isNew: true);
|
||||
// - Starts in IdleState
|
||||
// - Dragging DISABLED (booster cards can't be dragged)
|
||||
```
|
||||
|
||||
### **For Album Placement Flow:**
|
||||
```csharp
|
||||
card.SetupForAlbumPlacement(cardData);
|
||||
// - Starts in RevealedState
|
||||
// - Dragging ENABLED (can drag to album slots)
|
||||
```
|
||||
|
||||
### **For Cards Already in Album:**
|
||||
```csharp
|
||||
card.SetupForAlbumSlot(cardData, albumSlot);
|
||||
// - Starts in PlacedInSlotState
|
||||
// - Dragging DISABLED (can't drag out of album)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Existing Drag/Drop System
|
||||
|
||||
### **Works with AlbumCardSlot:**
|
||||
```csharp
|
||||
// AlbumCardSlot.cs doesn't need changes!
|
||||
// It expects DraggableObject, and Card now IS a DraggableObject
|
||||
public class AlbumCardSlot : DraggableSlot
|
||||
{
|
||||
public bool CanAccept(DraggableObject draggable)
|
||||
{
|
||||
// Works with Card because Card inherits from DraggableObject
|
||||
if (draggable is Card card)
|
||||
{
|
||||
return CanAcceptCard(card.CardData);
|
||||
}
|
||||
return false;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### **No Visual Component Needed:**
|
||||
- DraggableObject can optionally use a DraggableVisual child
|
||||
- Card doesn't need one - the state machine handles all visuals
|
||||
- Card itself IS the visual representation
|
||||
|
||||
---
|
||||
|
||||
## State Machine Integration
|
||||
|
||||
### **States that interact with drag system:**
|
||||
|
||||
1. **RevealedState** - Card waits here, dragging enabled
|
||||
- Player can click to flip (if corner card)
|
||||
- Player can drag to album slot (if placement card)
|
||||
|
||||
2. **DraggingState** - Visual feedback during drag
|
||||
- Scales card up (1.1x by default)
|
||||
- DraggableObject handles actual drag movement
|
||||
|
||||
3. **PlacedInSlotState** - Card placed in album
|
||||
- Dragging disabled
|
||||
- Can be clicked to enlarge
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
### **Cleaner Architecture:**
|
||||
- ✅ No wrapper scripts needed (Card, CardDraggable, CardDraggableVisual → Just Card)
|
||||
- ✅ Drag capability at top level (Card manages it directly)
|
||||
- ✅ States handle visuals only (DraggingState shows scale, not position)
|
||||
- ✅ Separation of concerns (drag logic ≠ visual logic)
|
||||
|
||||
### **Reuses Generic Base:**
|
||||
- ✅ DraggableObject does all heavy lifting (snapping, slot detection, events)
|
||||
- ✅ No card-specific drag code duplication
|
||||
- ✅ Works with existing SlotContainer, DraggableSlot system
|
||||
|
||||
### **Backward Compatible:**
|
||||
- ✅ Old files moved to DEPRECATED/ (not deleted)
|
||||
- ✅ AlbumCardPlacementDraggable still exists for old corner cards
|
||||
- ✅ Can migrate gradually (new Card works alongside old FlippableCard)
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
### **Booster Opening Flow:**
|
||||
- [ ] Cards spawn in center (not draggable)
|
||||
- [ ] Click card → flips → enlarges
|
||||
- [ ] Tap enlarged card → shrinks to revealed state
|
||||
- [ ] Try dragging card → should be blocked (dragging disabled)
|
||||
|
||||
### **Album Placement Flow:**
|
||||
- [ ] Cards spawn in corner (draggable)
|
||||
- [ ] Click card → flips → shows which card it is
|
||||
- [ ] Card enters RevealedState (draggable)
|
||||
- [ ] Drag card → enters DraggingState (scales up)
|
||||
- [ ] Drop in valid AlbumCardSlot → PlacedInSlotState
|
||||
- [ ] Drop outside slot → returns to RevealedState
|
||||
- [ ] Card in slot is NOT draggable
|
||||
|
||||
### **Album Slot Interaction:**
|
||||
- [ ] Click card in slot → AlbumEnlargedState
|
||||
- [ ] Tap enlarged card → shrinks back to PlacedInSlotState
|
||||
- [ ] Card cannot be dragged out of slot
|
||||
|
||||
---
|
||||
|
||||
## Migration Path for Old Code
|
||||
|
||||
### **Current State:**
|
||||
- ✅ New Card.cs works with drag/drop
|
||||
- ✅ Old FlippableCard.cs in DEPRECATED/ (still compiles)
|
||||
- ✅ Old AlbumCardPlacementDraggable.cs still in DragDrop/ (for corner cards)
|
||||
|
||||
### **Next Steps:**
|
||||
1. Update BoosterOpeningPage to use new Card.SetupForBoosterReveal()
|
||||
2. Update AlbumViewPage corner cards to use Card.SetupForAlbumPlacement()
|
||||
3. Test both flows thoroughly
|
||||
4. Once stable, delete DEPRECATED/ folder
|
||||
|
||||
---
|
||||
|
||||
## Example Usage
|
||||
|
||||
### **BoosterOpeningPage.cs (New):**
|
||||
```csharp
|
||||
// Spawn booster cards (NOT draggable)
|
||||
Card card = Instantiate(cardPrefab);
|
||||
card.SetupForBoosterReveal(cardData, isNew: isNewCard);
|
||||
card.Context.IsClickable = true;
|
||||
|
||||
// Subscribe to events
|
||||
card.Context.OnFlipComplete += OnCardFlipComplete;
|
||||
card.Context.OnCardInteractionComplete += OnCardComplete;
|
||||
```
|
||||
|
||||
### **AlbumViewPage.cs (New - Corner Cards):**
|
||||
```csharp
|
||||
// Spawn unrevealed corner card (DRAGGABLE)
|
||||
Card card = Instantiate(cardPrefab);
|
||||
card.SetupForAlbumPlacement(cardData);
|
||||
|
||||
// Card can now be dragged to matching album slot
|
||||
// When dropped, automatically transitions to PlacedInSlotState
|
||||
```
|
||||
|
||||
### **AlbumViewPage.cs (New - Already Placed):**
|
||||
```csharp
|
||||
// Card already in album slot (NOT draggable)
|
||||
Card card = Instantiate(cardPrefab, albumSlot.transform);
|
||||
card.SetupForAlbumSlot(cardData, albumSlot);
|
||||
|
||||
// Card can be clicked to enlarge, but not dragged out
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Technical Notes
|
||||
|
||||
### **Why Card inherits from DraggableObject:**
|
||||
- **Single Responsibility:** Card manages its own drag capability
|
||||
- **No Wrappers:** Simpler prefab structure (no CardDraggable wrapper)
|
||||
- **Polymorphism:** AlbumCardSlot accepts DraggableObject, Card IS a DraggableObject
|
||||
- **Event Integration:** DraggableObject events trigger state transitions
|
||||
|
||||
### **Why DraggingState is visual-only:**
|
||||
- **DraggableObject handles movement:** OnDrag() updates transform.position automatically
|
||||
- **State shows feedback:** Scaling up indicates "I'm being dragged"
|
||||
- **Clean separation:** Drag logic (base class) vs visual feedback (state)
|
||||
|
||||
### **Why SetDraggingEnabled():**
|
||||
- **Booster cards:** Should never be draggable (opens in place)
|
||||
- **Corner cards:** Should be draggable (placement flow)
|
||||
- **Album cards:** Should NOT be draggable once placed (locked in slot)
|
||||
- **Runtime control:** Can enable/disable per card instance
|
||||
|
||||
---
|
||||
|
||||
## Files Structure After Refactor
|
||||
|
||||
```
|
||||
CardSystem/
|
||||
├─ Card.cs ← NOW inherits from DraggableObject
|
||||
├─ CardContext.cs
|
||||
├─ CardAnimator.cs
|
||||
├─ ProgressBarController.cs
|
||||
├─ StateMachine/
|
||||
│ ├─ States/
|
||||
│ │ ├─ CardDraggingState.cs ← Simplified (visual-only)
|
||||
│ │ ├─ CardRevealedState.cs ← Drag starts from here
|
||||
│ │ ├─ CardPlacedInSlotState.cs ← Drag ends here (if valid slot)
|
||||
│ │ └─ [other states...]
|
||||
├─ DragDrop/
|
||||
│ ├─ AlbumCardSlot.cs ← Works with Card (DraggableObject)
|
||||
│ └─ AlbumCardPlacementDraggable.cs ← OLD system, for corner cards
|
||||
└─ DEPRECATED/ ✨ NEW
|
||||
├─ CardDraggable.cs ← Moved
|
||||
├─ CardDraggableVisual.cs ← Moved
|
||||
└─ FlippableCard.cs ← Moved
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
✅ **Card.cs now inherits from DraggableObject** - Owns drag capability
|
||||
✅ **Drag events trigger state transitions** - OnDragStarted → DraggingState
|
||||
✅ **DraggingState is visual-only** - Shows scale feedback
|
||||
✅ **Setup methods control dragging** - Enable/disable per flow
|
||||
✅ **Backward compatible** - Old files in DEPRECATED/
|
||||
✅ **Works with existing slots** - AlbumCardSlot unchanged
|
||||
✅ **Cleaner architecture** - No wrappers, states handle visuals
|
||||
|
||||
**Status: Drag/Drop integration complete! Ready for testing and migration.**
|
||||
|
||||
@@ -1,321 +0,0 @@
|
||||
# Card State Machine - Implementation Complete ✅
|
||||
|
||||
## 🚀 QUICK START
|
||||
|
||||
**→ New to this implementation? Start here: `README_CARD_SYSTEM.md`**
|
||||
|
||||
That document has everything you need in one place:
|
||||
- What was delivered
|
||||
- How to use it
|
||||
- Step-by-step next actions
|
||||
- Troubleshooting
|
||||
|
||||
---
|
||||
|
||||
## 📦 All Files Created
|
||||
|
||||
### Core Components (4 files)
|
||||
Located in: `Assets/Scripts/UI/CardSystem/StateMachine/`
|
||||
|
||||
1. ✅ **Card.cs**
|
||||
- Main controller component
|
||||
- Provides API for card setup and state control
|
||||
- Entry point for all card operations
|
||||
|
||||
2. ✅ **CardContext.cs**
|
||||
- Shared context component
|
||||
- Provides states access to common data/components
|
||||
- Holds CardData, IsNewCard flag, etc.
|
||||
|
||||
3. ✅ **CardAnimator.cs**
|
||||
- Reusable animation controller
|
||||
- Eliminates duplicate tween code
|
||||
- Used by all states for consistent animations
|
||||
|
||||
4. ✅ **CardAnimationConfig.cs**
|
||||
- ScriptableObject for animation settings
|
||||
- Designer-friendly configuration
|
||||
- Single source of truth for animation parameters
|
||||
|
||||
### State Scripts (8 files)
|
||||
Located in: `Assets/Scripts/UI/CardSystem/StateMachine/States/`
|
||||
|
||||
5. ✅ **CardIdleState.cs**
|
||||
- Initial state for booster cards
|
||||
- Handles hover animation and click to flip
|
||||
- No owned visuals
|
||||
|
||||
6. ✅ **CardFlippingState.cs**
|
||||
- Handles card flip animation
|
||||
- **Owns:** CardBackVisual (child GameObject)
|
||||
- Transitions to EnlargedNew/EnlargedRepeat/Revealed based on card type
|
||||
|
||||
7. ✅ **CardRevealedState.cs**
|
||||
- Card is flipped and visible
|
||||
- Waiting for player interaction
|
||||
- No owned visuals
|
||||
|
||||
8. ✅ **CardEnlargedNewState.cs**
|
||||
- Shows enlarged view for NEW cards
|
||||
- **Owns:** NewCardBadge (child GameObject with "NEW CARD" text)
|
||||
- Click to dismiss and return to revealed state
|
||||
|
||||
9. ✅ **CardEnlargedRepeatState.cs**
|
||||
- Shows enlarged view for REPEAT cards
|
||||
- **Owns:** ProgressBarUI (child GameObject with progress bar X/5)
|
||||
- Click to dismiss and return to revealed state
|
||||
|
||||
10. ✅ **CardDraggingState.cs**
|
||||
- Handles card being dragged for album placement
|
||||
- Scales up during drag for visual feedback
|
||||
- Transitions to PlacedInSlot or back to Revealed on drop
|
||||
|
||||
11. ✅ **CardPlacedInSlotState.cs**
|
||||
- Card is placed in an album slot
|
||||
- Stores reference to parent AlbumCardSlot
|
||||
- Click to transition to AlbumEnlarged state
|
||||
|
||||
12. ✅ **CardAlbumEnlargedState.cs**
|
||||
- Enlarged view when clicked from album
|
||||
- Stores original transform for restoration
|
||||
- Click to shrink back to PlacedInSlot state
|
||||
|
||||
### Optional Helper (1 file)
|
||||
13. ✅ **CardInteractionHandler.cs**
|
||||
- Optional bridge between state machine and drag/drop system
|
||||
- Implements IBeginDragHandler, IDragHandler, IEndDragHandler
|
||||
- Can be added to Card root if using Unity's drag system
|
||||
|
||||
## 📚 Documentation Created
|
||||
|
||||
### Primary Guides (3 documents)
|
||||
|
||||
1. ✅ **card_system_architecture_audit.md**
|
||||
- Complete audit of old system
|
||||
- Identified problems and architectural issues
|
||||
- Proposed solution with state machine pattern
|
||||
- Migration strategy and metrics
|
||||
|
||||
2. ✅ **card_prefab_assembly_guide.md**
|
||||
- **Step-by-step guide to building the Card prefab**
|
||||
- **THIS IS YOUR MAIN REFERENCE FOR UNITY WORK**
|
||||
- Complete hierarchy breakdown
|
||||
- Component assignment instructions
|
||||
- Integration examples
|
||||
- Troubleshooting section
|
||||
|
||||
3. ✅ **card_state_machine_quick_reference.md**
|
||||
- State flow diagram
|
||||
- API quick reference
|
||||
- Common patterns
|
||||
- Debugging tips
|
||||
|
||||
### Summary Documents (2 documents)
|
||||
|
||||
4. ✅ **card_system_implementation_summary.md**
|
||||
- Architecture overview
|
||||
- Key design decisions
|
||||
- Benefits comparison table
|
||||
|
||||
5. ✅ **card_implementation_complete.md** *(this file)*
|
||||
- Complete file listing
|
||||
- Implementation checklist
|
||||
|
||||
---
|
||||
|
||||
## ✅ Implementation Checklist
|
||||
|
||||
### Code Implementation (Complete)
|
||||
- [x] Created CardContext for shared state access
|
||||
- [x] Created CardAnimator with reusable animation methods
|
||||
- [x] Created CardAnimationConfig ScriptableObject
|
||||
- [x] Created Card controller component
|
||||
- [x] Implemented IdleState (hover + click)
|
||||
- [x] Implemented FlippingState (owns CardBackVisual)
|
||||
- [x] Implemented RevealedState (waiting for interaction)
|
||||
- [x] Implemented EnlargedNewState (owns NewCardBadge)
|
||||
- [x] Implemented EnlargedRepeatState (owns ProgressBarUI)
|
||||
- [x] Implemented DraggingState (drag feedback)
|
||||
- [x] Implemented PlacedInSlotState (album slot reference)
|
||||
- [x] Implemented AlbumEnlargedState (enlarge from album)
|
||||
- [x] Created optional CardInteractionHandler for drag/drop
|
||||
|
||||
### Unity Prefab Setup (To Do)
|
||||
- [ ] Create CardAnimationConfig asset in Unity
|
||||
- [ ] Create base Card prefab GameObject
|
||||
- [ ] Add CardContext, CardAnimator, Card components to root
|
||||
- [ ] Add or reference existing CardDisplay component
|
||||
- [ ] Create CardStateMachine GameObject with AppleMachine
|
||||
- [ ] Create 8 state GameObjects under CardStateMachine
|
||||
- [ ] Add state components to each state GameObject
|
||||
- [ ] Create and assign state-owned visuals:
|
||||
- [ ] CardBackVisual (FlippingState child)
|
||||
- [ ] NewCardBadge (EnlargedNewState child)
|
||||
- [ ] ProgressBarUI (EnlargedRepeatState child)
|
||||
- [ ] Wire up all component references
|
||||
- [ ] Set default state on AppleMachine
|
||||
- [ ] Test state transitions in Play mode
|
||||
- [ ] Save as Card.prefab
|
||||
|
||||
### Integration (To Do)
|
||||
- [ ] Update BoosterOpeningPage to use new Card prefab
|
||||
- [ ] Update AlbumViewPage to use new Card prefab
|
||||
- [ ] Test booster opening flow
|
||||
- [ ] Test album placement flow
|
||||
- [ ] Test enlarge/shrink interactions
|
||||
- [ ] Verify state transitions work correctly
|
||||
- [ ] Performance test with multiple cards
|
||||
|
||||
### Migration (To Do)
|
||||
- [ ] Create migration script (optional)
|
||||
- [ ] Convert existing card instances to new system
|
||||
- [ ] Test all card interactions in game
|
||||
- [ ] Deprecate old wrapper scripts (FlippableCard, AlbumCard, etc.)
|
||||
- [ ] Archive old prefabs for reference
|
||||
- [ ] Update team documentation
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps - What You Need To Do
|
||||
|
||||
### IMMEDIATE: Follow the Prefab Assembly Guide
|
||||
|
||||
**→ Open: `docs/card_prefab_assembly_guide.md`**
|
||||
|
||||
This is your primary reference for building the Card prefab in Unity. It has:
|
||||
- Step-by-step instructions with screenshots context
|
||||
- Exact hierarchy structure
|
||||
- Component assignment details
|
||||
- Troubleshooting tips
|
||||
- Integration code examples
|
||||
|
||||
### Step-by-Step Summary:
|
||||
|
||||
1. **Create CardAnimationConfig asset** (2 min)
|
||||
- Right-click in Project → Create → AppleHills → Card Animation Config
|
||||
- Set animation values matching your current FlippableCard
|
||||
|
||||
2. **Build Card prefab hierarchy** (15-20 min)
|
||||
- Create root GameObject with RectTransform
|
||||
- Add Card, CardContext, CardAnimator components
|
||||
- Add CardDisplay (from existing prefab or create new)
|
||||
- Create CardStateMachine child with AppleMachine
|
||||
- Create 8 state GameObjects with their components
|
||||
|
||||
3. **Create state-owned visuals** (10-15 min)
|
||||
- CardBackVisual under FlippingState
|
||||
- NewCardBadge under EnlargedNewState
|
||||
- ProgressBarUI under EnlargedRepeatState
|
||||
|
||||
4. **Wire references** (5 min)
|
||||
- Assign visuals to state components
|
||||
- Set default state on AppleMachine
|
||||
- Verify CardContext has all references
|
||||
|
||||
5. **Test in Play mode** (10 min)
|
||||
- Call SetupForBoosterReveal() with test data
|
||||
- Click card to trigger flip
|
||||
- Verify state transitions work
|
||||
- Check console for any errors
|
||||
|
||||
6. **Save as prefab** (1 min)
|
||||
- Drag to Prefabs folder
|
||||
- Name it Card.prefab
|
||||
|
||||
7. **Integrate into one scene** (20-30 min)
|
||||
- Start with BoosterOpeningPage
|
||||
- Replace FlippableCard spawning with Card spawning
|
||||
- Test pack opening flow
|
||||
- Fix any integration issues
|
||||
|
||||
8. **Expand to all scenes** (varies)
|
||||
- Once booster opening works, do album placement
|
||||
- Test thoroughly
|
||||
- Gradually deprecate old system
|
||||
|
||||
---
|
||||
|
||||
## 📊 What You've Gained
|
||||
|
||||
### Code Metrics
|
||||
- **Lines of code reduced:** ~60% (from ~1200 to ~500)
|
||||
- **Animation duplication:** Eliminated (4 files → 1 CardAnimator)
|
||||
- **State tracking:** Boolean soup → Clean state machine
|
||||
- **Prefab nesting:** 5 layers → Flat structure
|
||||
|
||||
### Architecture Improvements
|
||||
- ✅ **Single Responsibility:** Each state handles one concern
|
||||
- ✅ **State Isolation:** States own their visuals, no global management
|
||||
- ✅ **Reusable Animations:** CardAnimator shared by all states
|
||||
- ✅ **Clear Transitions:** Explicit state machine flow
|
||||
- ✅ **Extensibility:** Add new states without touching existing code
|
||||
|
||||
### Developer Experience
|
||||
- ✅ **Easier debugging:** Check current state name vs. 12 booleans
|
||||
- ✅ **Faster iteration:** Add new state = 1 new file + GameObject
|
||||
- ✅ **Better testing:** States are isolated and testable
|
||||
- ✅ **Designer-friendly:** State machine visible in hierarchy
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Need Help?
|
||||
|
||||
### Stuck on Prefab Assembly?
|
||||
→ See troubleshooting section in `card_prefab_assembly_guide.md`
|
||||
|
||||
### Need Code Examples?
|
||||
→ See `card_state_machine_quick_reference.md` for patterns
|
||||
|
||||
### Want to Understand Architecture?
|
||||
→ See `card_system_architecture_audit.md` for deep dive
|
||||
|
||||
### Integration Questions?
|
||||
→ See integration section in `card_prefab_assembly_guide.md`
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Success Indicators
|
||||
|
||||
You'll know the implementation is successful when:
|
||||
|
||||
1. ✅ Card prefab exists with 8 functional states
|
||||
2. ✅ Clicking card in idle state triggers flip
|
||||
3. ✅ New cards show "NEW CARD" badge when enlarged
|
||||
4. ✅ Repeat cards show progress bar (X/5)
|
||||
5. ✅ Cards can be placed in album slots
|
||||
6. ✅ Cards in album can be clicked to enlarge
|
||||
7. ✅ No console errors during any state transition
|
||||
8. ✅ Performance is smooth (60fps) with multiple cards
|
||||
9. ✅ Old wrapper scripts are no longer needed
|
||||
10. ✅ Team understands and can work with new system
|
||||
|
||||
---
|
||||
|
||||
## 📝 Final Notes
|
||||
|
||||
**The code is complete.** All scripts are written and ready to use.
|
||||
|
||||
**Your next action:** Open Unity and follow the prefab assembly guide step-by-step.
|
||||
|
||||
**Time estimate:**
|
||||
- Prefab creation: ~45 minutes
|
||||
- Testing: ~30 minutes
|
||||
- Integration (one scene): ~30 minutes
|
||||
- **Total first implementation: ~2 hours**
|
||||
|
||||
Once you have the prefab working in one scene, expanding to the rest of the game is straightforward.
|
||||
|
||||
**Remember:** You're not replacing everything at once. Start with booster opening, validate it works, then move to album interactions. The old system can coexist during migration.
|
||||
|
||||
Good luck! The architecture is solid and the code is clean. You've got this! 💪
|
||||
|
||||
---
|
||||
|
||||
**Files ready for use:**
|
||||
- 13 code files (all compilation-ready)
|
||||
- 5 documentation files
|
||||
- 1 ScriptableObject definition (create asset in Unity)
|
||||
- 1 prefab to build (follow guide)
|
||||
|
||||
**Status: READY FOR UNITY IMPLEMENTATION** ✅
|
||||
|
||||
@@ -1,463 +0,0 @@
|
||||
# Old Card Scripts - Migration Strategy
|
||||
|
||||
## TL;DR: What Happens to Old Scripts?
|
||||
|
||||
**Answer:** They are **REPLACED** by the new state machine system, but **CardDisplay stays**.
|
||||
|
||||
### Keep (Don't Touch) ✅
|
||||
- **`CardDisplay.cs`** - Core visual renderer, used by both old and new systems
|
||||
|
||||
### Replace (Eventually Deprecate) 🔄
|
||||
- **`FlippableCard.cs`** → Replaced by `Card.cs` with state machine
|
||||
- **`AlbumCard.cs`** → Replaced by `CardPlacedInSlotState.cs` + `CardAlbumEnlargedState.cs`
|
||||
- **`AlbumCardPlacementDraggable.cs`** → Replaced by `Card.cs` with `CardDraggingState.cs`
|
||||
|
||||
---
|
||||
|
||||
## Current Usage Analysis
|
||||
|
||||
### Where FlippableCard is Used:
|
||||
1. **BoosterOpeningPage.cs** (8 references)
|
||||
- Line 592: Instantiate FlippableCard for booster reveal
|
||||
- Line 601, 643, 660, 752, 770: GetComponent calls
|
||||
- **Impact:** High - main booster opening flow
|
||||
|
||||
2. **AlbumCardPlacementDraggable.cs** (1 reference)
|
||||
- Line 45: GetComponent reference
|
||||
- **Impact:** Medium - album placement flow
|
||||
|
||||
3. **AlbumCard.cs** (1 reference)
|
||||
- Line 94: GetComponentInParent during click forwarding
|
||||
- **Impact:** Low - will be removed when AlbumCard is replaced
|
||||
|
||||
### Where AlbumCard is Used:
|
||||
1. **AlbumCardSlot.cs** (2 references)
|
||||
- Line 186-187: Instantiate and GetComponent for pre-placed cards
|
||||
- **Impact:** High - album slot system
|
||||
|
||||
2. **AlbumViewPage.cs** (2 references)
|
||||
- Line 346: GetComponent when handling enlarge
|
||||
- Line 457-458: Instantiate AlbumCardPlacementDraggable
|
||||
- **Impact:** High - album view interactions
|
||||
|
||||
3. **CardDisplay.cs** (1 reference)
|
||||
- Line 316: GetComponentInParent for preview mode
|
||||
- **Impact:** Low - preview feature
|
||||
|
||||
4. **FlippableCard.cs** (1 reference)
|
||||
- Line 73: GetComponentInChildren reference
|
||||
- **Impact:** Will be removed when FlippableCard is replaced
|
||||
|
||||
---
|
||||
|
||||
## Migration Phases
|
||||
|
||||
### Phase 1: Parallel Development (Current) ✅
|
||||
**Status:** Both systems coexist, no breaking changes
|
||||
|
||||
```
|
||||
Old System (Active) New System (Being Built)
|
||||
├─ FlippableCard.cs ├─ Card.cs
|
||||
├─ AlbumCard.cs ├─ CardContext.cs
|
||||
├─ AlbumCardPlacement... ├─ CardAnimator.cs
|
||||
└─ CardDisplay.cs ←──────────┼─→ CardDisplay.cs (shared!)
|
||||
└─ State scripts...
|
||||
```
|
||||
|
||||
**Action:** Build new Card prefab, test in isolation
|
||||
**Timeline:** Current (you're here!)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Partial Replacement - Booster Opening (Recommended Start)
|
||||
**Status:** Replace booster cards only, album cards still use old system
|
||||
|
||||
#### Changes Required:
|
||||
|
||||
**File: `BoosterOpeningPage.cs`**
|
||||
|
||||
**Old code:**
|
||||
```csharp
|
||||
[SerializeField] private GameObject flippableCardPrefab;
|
||||
|
||||
// In SpawnCards()
|
||||
GameObject cardObj = Instantiate(flippableCardPrefab, cardDisplayContainer);
|
||||
FlippableCard flippableCard = cardObj.GetComponent<FlippableCard>();
|
||||
flippableCard.SetupCard(cardData);
|
||||
flippableCard.OnCardRevealed += HandleCardRevealed;
|
||||
flippableCard.OnCardTappedAfterReveal += HandleCardTapped;
|
||||
```
|
||||
|
||||
**New code:**
|
||||
```csharp
|
||||
[SerializeField] private GameObject cardPrefab; // New Card prefab
|
||||
|
||||
// In SpawnCards()
|
||||
GameObject cardObj = Instantiate(cardPrefab, cardDisplayContainer);
|
||||
StateMachine.Card card = cardObj.GetComponent<StateMachine.Card>();
|
||||
card.SetupForBoosterReveal(cardData, isNew: true);
|
||||
|
||||
// Subscribe to state events (if needed)
|
||||
var flippingState = card.GetStateComponent<StateMachine.States.CardFlippingState>("FlippingState");
|
||||
// Add custom events if needed, or just let state machine handle it
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Test new system in one isolated flow
|
||||
- Booster opening is cleanest use case (no complex album interactions)
|
||||
- Easy to rollback if issues arise
|
||||
|
||||
**Timeline:** 2-4 hours
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Full Replacement - Album System
|
||||
**Status:** Replace album cards, old system fully deprecated
|
||||
|
||||
#### Changes Required:
|
||||
|
||||
**File: `AlbumCardSlot.cs`**
|
||||
|
||||
**Old code:**
|
||||
```csharp
|
||||
[SerializeField] private GameObject albumCardPrefab;
|
||||
|
||||
// In SpawnPreviewCard()
|
||||
GameObject cardObj = Instantiate(albumCardPrefab, transform);
|
||||
AlbumCard albumCard = cardObj.GetComponent<AlbumCard>();
|
||||
albumCard.SetupCard(cardData);
|
||||
albumCard.SetParentSlot(this);
|
||||
albumCard.OnEnlargeRequested += HandleEnlarge;
|
||||
albumCard.OnShrinkRequested += HandleShrink;
|
||||
```
|
||||
|
||||
**New code:**
|
||||
```csharp
|
||||
[SerializeField] private GameObject cardPrefab; // Same Card prefab as booster
|
||||
|
||||
// In SpawnPreviewCard()
|
||||
GameObject cardObj = Instantiate(cardPrefab, transform);
|
||||
StateMachine.Card card = cardObj.GetComponent<StateMachine.Card>();
|
||||
card.SetupForAlbumSlot(cardData, this);
|
||||
|
||||
// Subscribe to enlarge events (if needed)
|
||||
var albumEnlargedState = card.GetStateComponent<StateMachine.States.CardAlbumEnlargedState>("AlbumEnlargedState");
|
||||
albumEnlargedState.OnEnlargeRequested += HandleEnlarge;
|
||||
albumEnlargedState.OnShrinkRequested += HandleShrink;
|
||||
```
|
||||
|
||||
**File: `AlbumViewPage.cs`**
|
||||
|
||||
Similar changes for handling enlarged cards and backdrop.
|
||||
|
||||
**Timeline:** 4-6 hours
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Cleanup - Remove Old Scripts
|
||||
**Status:** Old scripts deleted, prefabs archived
|
||||
|
||||
#### Files to Remove:
|
||||
- ❌ `FlippableCard.cs`
|
||||
- ❌ `AlbumCard.cs`
|
||||
- ❌ `AlbumCardPlacementDraggable.cs` (if drag system is integrated)
|
||||
|
||||
#### Files to Keep:
|
||||
- ✅ `CardDisplay.cs` - Still used by new system!
|
||||
- ✅ `AlbumCardSlot.cs` - Updated to use new Card prefab
|
||||
- ✅ `BoosterOpeningPage.cs` - Updated to use new Card prefab
|
||||
- ✅ `AlbumViewPage.cs` - Updated to use new Card prefab
|
||||
|
||||
**Timeline:** 1 hour (after Phases 2-3 are stable)
|
||||
|
||||
---
|
||||
|
||||
## Coexistence Strategy (During Migration)
|
||||
|
||||
### Option A: Gradual Scene-by-Scene (Recommended)
|
||||
Replace one scene at a time:
|
||||
|
||||
```
|
||||
Week 1: Booster Opening Scene
|
||||
└─ Uses new Card.prefab
|
||||
|
||||
Week 2: Album View Scene
|
||||
└─ Uses new Card.prefab
|
||||
|
||||
Week 3: Any other card scenes
|
||||
└─ Uses new Card.prefab
|
||||
|
||||
Week 4: Remove old scripts
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- Low risk, easy rollback
|
||||
- Test thoroughly at each step
|
||||
- Team can adapt gradually
|
||||
|
||||
**Cons:**
|
||||
- Longer timeline
|
||||
- Maintain both systems temporarily
|
||||
|
||||
---
|
||||
|
||||
### Option B: Big Bang Replacement
|
||||
Replace all at once in one PR/branch:
|
||||
|
||||
```
|
||||
Day 1-2: Update BoosterOpeningPage
|
||||
Day 3-4: Update AlbumViewPage + AlbumCardSlot
|
||||
Day 5: Test everything
|
||||
Day 6: Delete old scripts
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
- Faster completion
|
||||
- No long-term coexistence
|
||||
|
||||
**Cons:**
|
||||
- Higher risk
|
||||
- More testing needed
|
||||
- Harder to rollback
|
||||
|
||||
---
|
||||
|
||||
## Feature Mapping: Old → New
|
||||
|
||||
### FlippableCard → Card with States
|
||||
|
||||
| Old Feature | Old Implementation | New Implementation |
|
||||
|-------------|-------------------|-------------------|
|
||||
| Idle hover | FlippableCard._idleHoverTween | CardIdleState.OnEnterState() |
|
||||
| Click to flip | FlippableCard.OnPointerClick() | CardIdleState.OnPointerClick() |
|
||||
| Flip animation | FlippableCard.FlipToReveal() | CardFlippingState.OnEnterState() |
|
||||
| New card badge | FlippableCard.ShowAsNew() | CardEnlargedNewState (owns badge) |
|
||||
| Repeat progress | FlippableCard.ShowAsRepeat() | CardEnlargedRepeatState (owns bar) |
|
||||
| Tap to dismiss | FlippableCard.OnPointerClick() when waiting | CardEnlargedNewState.OnPointerClick() |
|
||||
|
||||
### AlbumCard → CardPlacedInSlotState + CardAlbumEnlargedState
|
||||
|
||||
| Old Feature | Old Implementation | New Implementation |
|
||||
|-------------|-------------------|-------------------|
|
||||
| Store parent slot | AlbumCard._parentSlot | CardPlacedInSlotState.SetParentSlot() |
|
||||
| Click to enlarge | AlbumCard.OnPointerClick() | CardPlacedInSlotState.OnPointerClick() |
|
||||
| Enlarge animation | AlbumCard.EnlargeCard() | CardAlbumEnlargedState.OnEnterState() |
|
||||
| Shrink animation | AlbumCard.ShrinkCard() | CardAlbumEnlargedState.OnPointerClick() |
|
||||
| Transform tracking | AlbumCard._originalParent, etc. | CardAlbumEnlargedState (same fields) |
|
||||
|
||||
### AlbumCardPlacementDraggable → Card with CardDraggingState
|
||||
|
||||
| Old Feature | Old Implementation | New Implementation |
|
||||
|-------------|-------------------|-------------------|
|
||||
| Drag feedback | AlbumCardPlacement... | CardDraggingState |
|
||||
| Snap to slot | SnapToAlbumSlot() | CardDraggingState.OnDroppedInSlot() |
|
||||
| Flip on drag | Nested FlippableCard | Just use Card with state machine |
|
||||
|
||||
---
|
||||
|
||||
## Events Migration
|
||||
|
||||
### Old Events (FlippableCard)
|
||||
```csharp
|
||||
flippableCard.OnCardRevealed += (card, data) => { };
|
||||
flippableCard.OnCardTappedAfterReveal += (card) => { };
|
||||
flippableCard.OnFlipStarted += (card) => { };
|
||||
flippableCard.OnClickedWhileInactive += (card) => { };
|
||||
```
|
||||
|
||||
### New Events (State-based)
|
||||
```csharp
|
||||
// Option 1: Listen to state machine transitions
|
||||
var flippingState = card.GetStateComponent<CardFlippingState>("FlippingState");
|
||||
// Then add custom events to states if needed
|
||||
|
||||
// Option 2: Poll current state
|
||||
if (card.GetCurrentStateName() == "RevealedState")
|
||||
{
|
||||
// Card was revealed
|
||||
}
|
||||
|
||||
// Option 3: Add custom events to Card.cs that relay from states
|
||||
card.OnCardRevealed += (data) => { };
|
||||
```
|
||||
|
||||
**Note:** Some events may not be needed anymore because state machine handles transitions internally.
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Phase 2 Testing (Booster Only)
|
||||
- [ ] Open booster pack
|
||||
- [ ] Cards spawn in IdleState
|
||||
- [ ] Click card triggers flip
|
||||
- [ ] Flip animation plays correctly
|
||||
- [ ] New cards show "NEW CARD" badge
|
||||
- [ ] Repeat cards show progress bar
|
||||
- [ ] Tap dismisses enlarged view
|
||||
- [ ] Multiple cards work simultaneously
|
||||
- [ ] No console errors
|
||||
|
||||
### Phase 3 Testing (Album Added)
|
||||
- [ ] Cards appear in album slots
|
||||
- [ ] Click card in album enlarges it
|
||||
- [ ] Tap enlarged card shrinks it
|
||||
- [ ] Backdrop shows/hides correctly
|
||||
- [ ] Reparenting works (card moves to top layer)
|
||||
- [ ] Card returns to correct slot
|
||||
- [ ] Page flipping doesn't break card state
|
||||
- [ ] No console errors
|
||||
|
||||
### Regression Testing (Both Phases)
|
||||
- [ ] CardDisplay still renders correctly
|
||||
- [ ] Card data persists across states
|
||||
- [ ] Animations are smooth (60fps)
|
||||
- [ ] Click detection works
|
||||
- [ ] No memory leaks (profile with 20+ cards)
|
||||
|
||||
---
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If new system has issues:
|
||||
|
||||
### During Phase 2 (Booster Only)
|
||||
1. Revert `BoosterOpeningPage.cs` changes
|
||||
2. Re-assign old `flippableCardPrefab` in inspector
|
||||
3. Old system still intact for album
|
||||
|
||||
### During Phase 3 (Album Added)
|
||||
1. Revert `AlbumCardSlot.cs` and `AlbumViewPage.cs`
|
||||
2. Re-assign old prefabs in inspector
|
||||
3. Both systems revert to old
|
||||
|
||||
### After Phase 4 (Old Scripts Deleted)
|
||||
1. Restore old scripts from Git history
|
||||
2. Recreate old prefabs (if not archived)
|
||||
3. Revert consumer scripts
|
||||
|
||||
**Prevention:** Archive old prefabs before deleting!
|
||||
|
||||
---
|
||||
|
||||
## CardDisplay.cs - The Survivor
|
||||
|
||||
**Why CardDisplay is NOT replaced:**
|
||||
|
||||
CardDisplay is a **pure visual renderer**. It:
|
||||
- Takes CardData and displays it
|
||||
- Has no state management
|
||||
- Has no animation logic
|
||||
- Has no interaction logic
|
||||
|
||||
This is **exactly what we want**! The new system uses CardDisplay as-is.
|
||||
|
||||
**Old hierarchy:**
|
||||
```
|
||||
FlippableCard
|
||||
└─ AlbumCard
|
||||
└─ CardDisplay ← renders visuals
|
||||
```
|
||||
|
||||
**New hierarchy:**
|
||||
```
|
||||
Card (state machine)
|
||||
└─ CardDisplay ← same renderer!
|
||||
```
|
||||
|
||||
CardDisplay is already well-designed - it's a "presenter" in the MVP pattern. Keep it!
|
||||
|
||||
---
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
### Preparation
|
||||
- [ ] New Card.prefab created and tested in isolation
|
||||
- [ ] CardAnimationConfig asset created
|
||||
- [ ] All state scripts compiled without errors
|
||||
- [ ] Team aware of upcoming changes
|
||||
|
||||
### Phase 2: Booster Opening
|
||||
- [ ] Update BoosterOpeningPage.cs to use Card.prefab
|
||||
- [ ] Remove FlippableCard references
|
||||
- [ ] Update prefab assignments in inspector
|
||||
- [ ] Test booster opening flow thoroughly
|
||||
- [ ] Fix any issues before proceeding
|
||||
|
||||
### Phase 3: Album System
|
||||
- [ ] Update AlbumCardSlot.cs to use Card.prefab
|
||||
- [ ] Update AlbumViewPage.cs to use Card.prefab
|
||||
- [ ] Remove AlbumCard references
|
||||
- [ ] Update prefab assignments in inspector
|
||||
- [ ] Test album interactions thoroughly
|
||||
- [ ] Test booster→album flow (cards placed after opening)
|
||||
|
||||
### Phase 4: Cleanup
|
||||
- [ ] Archive old prefabs (FlippableCard, AlbumCard)
|
||||
- [ ] Delete FlippableCard.cs
|
||||
- [ ] Delete AlbumCard.cs
|
||||
- [ ] Delete AlbumCardPlacementDraggable.cs (if fully replaced)
|
||||
- [ ] Run full regression test suite
|
||||
- [ ] Update team documentation
|
||||
- [ ] Celebrate! 🎉
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Can I use both systems simultaneously?**
|
||||
A: Yes, during migration. One scene can use FlippableCard while another uses Card.prefab.
|
||||
|
||||
**Q: Will old prefabs still work?**
|
||||
A: Yes, until you delete the old scripts. Prefabs using FlippableCard will continue to function.
|
||||
|
||||
**Q: Do I need to migrate all at once?**
|
||||
A: No! Recommended approach is scene-by-scene (Phase 2, then Phase 3).
|
||||
|
||||
**Q: What about CardDisplay?**
|
||||
A: Keep it! It's used by both old and new systems. It's well-designed and doesn't need changes.
|
||||
|
||||
**Q: What if I find bugs in the new system?**
|
||||
A: Rollback to old system (see Rollback Plan section), fix bugs, then retry migration.
|
||||
|
||||
**Q: How long will migration take?**
|
||||
A: Estimated 6-10 hours total (2-4 for booster, 4-6 for album, testing time).
|
||||
|
||||
**Q: Will performance improve?**
|
||||
A: Yes! 60% less code, more efficient state management, shared animation system.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
### Old Scripts Status:
|
||||
|
||||
| Script | Status | Timeline |
|
||||
|--------|--------|----------|
|
||||
| CardDisplay.cs | ✅ **KEEP** | Forever (it's perfect!) |
|
||||
| FlippableCard.cs | 🔄 **REPLACE** | Phase 2 (booster) |
|
||||
| AlbumCard.cs | 🔄 **REPLACE** | Phase 3 (album) |
|
||||
| AlbumCardPlacementDraggable.cs | 🔄 **REPLACE** | Phase 3 (album) |
|
||||
|
||||
### Migration Path:
|
||||
|
||||
```
|
||||
Now Phase 2 Phase 3 Future
|
||||
────────────────────────────────────────────────────────────
|
||||
Both systems → Booster uses → All use → Old scripts
|
||||
coexist new Card, new Card deleted
|
||||
album uses old
|
||||
```
|
||||
|
||||
### Key Insight:
|
||||
|
||||
**You're not "fixing" the old scripts - you're replacing their ARCHITECTURE.**
|
||||
|
||||
The old scripts work, but they're built on a flawed foundation (wrapper hell, boolean soup). The new system solves this with isolated states and clean separation of concerns.
|
||||
|
||||
Think of it like replacing a house's foundation - you keep the furniture (CardDisplay), but rebuild the structure underneath.
|
||||
|
||||
---
|
||||
|
||||
**Ready to start? Begin with Phase 2 (Booster Opening) - it's the cleanest migration path!**
|
||||
|
||||
@@ -1,528 +0,0 @@
|
||||
# Old vs New Card System - Visual Comparison
|
||||
|
||||
## Architecture Comparison
|
||||
|
||||
### OLD SYSTEM (Wrapper Hell)
|
||||
```
|
||||
FlippableCard.cs (425 lines)
|
||||
├─ Manages: flip, hover, new/repeat UI, clickability
|
||||
├─ Has: 8 boolean state flags
|
||||
├─ Contains: ~60 lines of animation code
|
||||
│
|
||||
└─ AlbumCard.cs (192 lines)
|
||||
├─ Manages: enlarge, shrink, slot reference
|
||||
├─ Has: 4 boolean state flags
|
||||
├─ Contains: ~40 lines of animation code
|
||||
│
|
||||
└─ CardDisplay.cs (350 lines)
|
||||
└─ Renders: card visuals
|
||||
|
||||
Total: ~970 lines just for ONE card configuration!
|
||||
Plus: AlbumCardPlacementDraggable.cs (200+ lines)
|
||||
```
|
||||
|
||||
### NEW SYSTEM (State Machine)
|
||||
```
|
||||
Card.cs (100 lines)
|
||||
├─ Orchestrates: state machine, setup API
|
||||
│
|
||||
├─ CardContext.cs (50 lines)
|
||||
│ └─ Shares: data, references
|
||||
│
|
||||
├─ CardAnimator.cs (150 lines)
|
||||
│ └─ Provides: ALL animation methods (no duplication)
|
||||
│
|
||||
└─ CardStateMachine (AppleMachine)
|
||||
├─ IdleState.cs (60 lines)
|
||||
├─ FlippingState.cs (50 lines)
|
||||
├─ RevealedState.cs (30 lines)
|
||||
├─ EnlargedNewState.cs (50 lines)
|
||||
├─ EnlargedRepeatState.cs (70 lines)
|
||||
├─ DraggingState.cs (50 lines)
|
||||
├─ PlacedInSlotState.cs (40 lines)
|
||||
└─ AlbumEnlargedState.cs (60 lines)
|
||||
|
||||
Total: ~610 lines for ALL card configurations!
|
||||
Plus: CardDisplay.cs (reused from old system)
|
||||
```
|
||||
|
||||
**Savings: 37% reduction in code, 100% reduction in duplication**
|
||||
|
||||
---
|
||||
|
||||
## Prefab Structure Comparison
|
||||
|
||||
### OLD SYSTEM PREFAB
|
||||
```
|
||||
FlippableCard Prefab (nested 4 deep)
|
||||
├─ FlippableCard Component
|
||||
├─ CardBackObject GameObject
|
||||
├─ CardFrontObject GameObject
|
||||
│ └─ AlbumCard Prefab Instance
|
||||
│ ├─ AlbumCard Component
|
||||
│ └─ CardDisplay Prefab Instance
|
||||
│ ├─ CardDisplay Component
|
||||
│ ├─ CardImage
|
||||
│ ├─ CardNameText
|
||||
│ ├─ FrameImage
|
||||
│ ├─ OverlayImage
|
||||
│ ├─ BackgroundImage
|
||||
│ └─ ZoneShapeImage
|
||||
├─ NewCardText GameObject (always present, manually shown/hidden)
|
||||
├─ NewCardIdleText GameObject (always present, manually shown/hidden)
|
||||
├─ RepeatText GameObject (always present, manually shown/hidden)
|
||||
└─ ProgressBarContainer GameObject (always present, manually shown/hidden)
|
||||
|
||||
Problems:
|
||||
❌ Deep nesting (hard to navigate)
|
||||
❌ State-specific UI always present (memory waste)
|
||||
❌ Manual visibility management (error-prone)
|
||||
❌ Components tightly coupled
|
||||
❌ Hard to modify without breaking references
|
||||
```
|
||||
|
||||
### NEW SYSTEM PREFAB
|
||||
```
|
||||
Card Prefab (flat with state children)
|
||||
├─ Card Component
|
||||
├─ CardContext Component
|
||||
├─ CardAnimator Component
|
||||
├─ CardDisplay GameObject
|
||||
│ ├─ CardDisplay Component (reused!)
|
||||
│ ├─ CardImage
|
||||
│ ├─ CardNameText
|
||||
│ ├─ FrameImage
|
||||
│ ├─ OverlayImage
|
||||
│ ├─ BackgroundImage
|
||||
│ └─ ZoneShapeImage
|
||||
└─ CardStateMachine GameObject
|
||||
├─ AppleMachine Component
|
||||
├─ IdleState/ (no special visuals)
|
||||
├─ FlippingState/
|
||||
│ └─ CardBackVisual (only exists here)
|
||||
├─ RevealedState/ (no special visuals)
|
||||
├─ EnlargedNewState/
|
||||
│ └─ NewCardBadge (only exists here)
|
||||
├─ EnlargedRepeatState/
|
||||
│ └─ ProgressBarUI (only exists here)
|
||||
├─ DraggingState/ (no special visuals)
|
||||
├─ PlacedInSlotState/ (no special visuals)
|
||||
└─ AlbumEnlargedState/ (no special visuals)
|
||||
|
||||
Benefits:
|
||||
✅ Flat structure (easy to navigate)
|
||||
✅ State-specific UI only in states (memory efficient)
|
||||
✅ Automatic visibility via state activation (bug-free)
|
||||
✅ Components loosely coupled via CardContext
|
||||
✅ Easy to modify/extend (just add new state GameObject)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## State Management Comparison
|
||||
|
||||
### OLD SYSTEM (Boolean Soup)
|
||||
```csharp
|
||||
// FlippableCard.cs
|
||||
private bool _isFlipped = false;
|
||||
private bool _isFlipping = false;
|
||||
private bool _isWaitingForTap = false;
|
||||
private bool _isNew = false;
|
||||
private bool _isClickable = true;
|
||||
|
||||
// AlbumCard.cs
|
||||
private bool _isEnlarged;
|
||||
private AlbumCardSlot _parentSlot; // null = not in slot
|
||||
|
||||
// AlbumCardPlacementDraggable.cs
|
||||
private bool _isRevealed = false;
|
||||
private bool _isDragRevealing = false;
|
||||
private bool _waitingForPlacementTap = false;
|
||||
private bool _isHolding = false;
|
||||
|
||||
// Total: 12 boolean flags across 3 components!
|
||||
|
||||
// Complex conditional logic:
|
||||
if (_isFlipped && !_isFlipping && _isWaitingForTap && !_isClickable) {
|
||||
// What state are we in???
|
||||
}
|
||||
|
||||
if (_parentSlot == null) {
|
||||
// Forward click to FlippableCard parent
|
||||
FlippableCard parent = GetComponentInParent<FlippableCard>();
|
||||
parent.OnPointerClick(eventData);
|
||||
}
|
||||
```
|
||||
|
||||
### NEW SYSTEM (State Machine)
|
||||
```csharp
|
||||
// Card.cs - Just one state machine!
|
||||
public string GetCurrentStateName()
|
||||
{
|
||||
return stateMachine.currentState?.name ?? "None";
|
||||
}
|
||||
|
||||
// Clean state checks:
|
||||
if (card.GetCurrentStateName() == "EnlargedNewState")
|
||||
{
|
||||
// We know EXACTLY what state we're in!
|
||||
}
|
||||
|
||||
// State transitions:
|
||||
_context.StateMachine.ChangeState("FlippingState");
|
||||
|
||||
// No boolean soup, no complex conditionals, no ambiguity!
|
||||
|
||||
// State machine automatically ensures:
|
||||
// - Only one state active at a time
|
||||
// - Clean enter/exit for each state
|
||||
// - Visual state visible in hierarchy
|
||||
// - Easy debugging (just look at active state GameObject)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Animation Code Comparison
|
||||
|
||||
### OLD SYSTEM (Duplicated)
|
||||
|
||||
**FlippableCard.cs - Flip Animation (~40 lines)**
|
||||
```csharp
|
||||
private void FlipToReveal()
|
||||
{
|
||||
_isFlipping = true;
|
||||
StopIdleHover();
|
||||
|
||||
// Phase 1: Rotate to 90°
|
||||
if (cardBackObject != null)
|
||||
{
|
||||
Tween.LocalRotation(cardBackObject.transform,
|
||||
Quaternion.Euler(0, 90, 0),
|
||||
flipDuration * 0.5f, 0f, Tween.EaseInOut);
|
||||
}
|
||||
|
||||
if (cardFrontObject != null)
|
||||
{
|
||||
Tween.LocalRotation(cardFrontObject.transform,
|
||||
Quaternion.Euler(0, 90, 0),
|
||||
flipDuration * 0.5f, 0f, Tween.EaseInOut,
|
||||
completeCallback: () => {
|
||||
// Swap visibility
|
||||
cardBackObject.SetActive(false);
|
||||
cardFrontObject.SetActive(true);
|
||||
|
||||
// Phase 2: Rotate to 0°
|
||||
Tween.LocalRotation(cardFrontObject.transform,
|
||||
Quaternion.Euler(0, 0, 0),
|
||||
flipDuration * 0.5f, 0f, Tween.EaseInOut,
|
||||
completeCallback: () => {
|
||||
_isFlipped = true;
|
||||
_isFlipping = false;
|
||||
OnCardRevealed?.Invoke(this, _cardData);
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
// Scale punch
|
||||
Vector3 originalScale = transform.localScale;
|
||||
Tween.LocalScale(transform, originalScale * flipScalePunch,
|
||||
flipDuration * 0.5f, 0f, Tween.EaseOutBack,
|
||||
completeCallback: () => {
|
||||
Tween.LocalScale(transform, originalScale,
|
||||
flipDuration * 0.5f, 0f, Tween.EaseInBack);
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
**AlbumCard.cs - Enlarge Animation (~20 lines)**
|
||||
```csharp
|
||||
public void EnlargeCard()
|
||||
{
|
||||
if (_isEnlarged) return;
|
||||
_isEnlarged = true;
|
||||
|
||||
_originalParent = transform.parent;
|
||||
_originalLocalPosition = transform.localPosition;
|
||||
_originalLocalRotation = transform.localRotation;
|
||||
|
||||
Tween.LocalScale(transform, _originalScale * enlargedScale,
|
||||
scaleDuration, 0f, Tween.EaseOutBack);
|
||||
}
|
||||
|
||||
public void ShrinkCard(System.Action onComplete = null)
|
||||
{
|
||||
if (!_isEnlarged) return;
|
||||
_isEnlarged = false;
|
||||
|
||||
Tween.LocalScale(transform, _originalScale, scaleDuration,
|
||||
0f, Tween.EaseInBack, completeCallback: () => onComplete?.Invoke());
|
||||
}
|
||||
```
|
||||
|
||||
**Plus similar animation code in AlbumCardPlacementDraggable.cs!**
|
||||
|
||||
**Total: ~150 lines of duplicate tween logic**
|
||||
|
||||
---
|
||||
|
||||
### NEW SYSTEM (Shared)
|
||||
|
||||
**CardAnimator.cs - ALL Animations (150 lines total)**
|
||||
```csharp
|
||||
public void PlayFlip(Transform cardBack, Transform cardFront, Action onComplete = null)
|
||||
{
|
||||
// Same flip logic, but only written ONCE
|
||||
cardBack.gameObject.SetActive(true);
|
||||
cardFront.gameObject.SetActive(false);
|
||||
cardBack.localRotation = Quaternion.Euler(0, 0, 0);
|
||||
|
||||
Tween.LocalRotation(cardBack, Quaternion.Euler(0, 90, 0),
|
||||
config.flipDuration * 0.5f, 0f, Tween.EaseInOut,
|
||||
completeCallback: () => {
|
||||
cardBack.gameObject.SetActive(false);
|
||||
cardFront.gameObject.SetActive(true);
|
||||
cardFront.localRotation = Quaternion.Euler(0, 90, 0);
|
||||
Tween.LocalRotation(cardFront, Quaternion.Euler(0, 0, 0),
|
||||
config.flipDuration * 0.5f, 0f, Tween.EaseInOut,
|
||||
completeCallback: onComplete);
|
||||
});
|
||||
}
|
||||
|
||||
public void PlayEnlarge(Transform target, Action onComplete = null)
|
||||
{
|
||||
// Enlarge logic, only written ONCE
|
||||
Vector3 targetScale = target.localScale * config.enlargedScale;
|
||||
Tween.LocalScale(target, targetScale, config.scaleDuration,
|
||||
0f, Tween.EaseOutBack, completeCallback: onComplete);
|
||||
}
|
||||
|
||||
// Plus: PlayShrink, PlayIdleHover, PlayHoverScaleUp/Down, etc.
|
||||
```
|
||||
|
||||
**States just call the shared methods:**
|
||||
```csharp
|
||||
// FlippingState.cs
|
||||
_context.Animator.PlayFlip(cardBackVisual.transform,
|
||||
_context.CardDisplay.transform, OnFlipComplete);
|
||||
|
||||
// EnlargedNewState.cs
|
||||
_context.Animator.PlayEnlarge(_context.RootTransform);
|
||||
```
|
||||
|
||||
**Total: 150 lines written ONCE, used by ALL states**
|
||||
|
||||
**Savings: 100% reduction in duplication**
|
||||
|
||||
---
|
||||
|
||||
## Event System Comparison
|
||||
|
||||
### OLD SYSTEM (Event Spaghetti)
|
||||
|
||||
**12+ events across components:**
|
||||
```csharp
|
||||
// FlippableCard events
|
||||
public event Action<FlippableCard, CardData> OnCardRevealed;
|
||||
public event Action<FlippableCard> OnCardTappedAfterReveal;
|
||||
public event Action<FlippableCard> OnClickedWhileInactive;
|
||||
public event Action<FlippableCard> OnFlipStarted;
|
||||
|
||||
// AlbumCard events
|
||||
public event Action<AlbumCard> OnEnlargeRequested;
|
||||
public event Action<AlbumCard> OnShrinkRequested;
|
||||
|
||||
// AlbumCardPlacementDraggable events
|
||||
public event Action<AlbumCardPlacementDraggable, CardData> OnCardRevealed;
|
||||
public event Action<AlbumCardPlacementDraggable, CardData> OnCardPlacedInAlbum;
|
||||
|
||||
// Usage (chained callbacks):
|
||||
card.OnEnlargeRequested += HandleEnlargeRequest;
|
||||
|
||||
void HandleEnlargeRequest(AlbumCard card)
|
||||
{
|
||||
backdrop.SetActive(true);
|
||||
card.transform.SetParent(topLayer);
|
||||
card.EnlargeCard(); // Which calls more events...
|
||||
}
|
||||
```
|
||||
|
||||
**Problems:**
|
||||
- Events scattered across components
|
||||
- Callbacks chain together
|
||||
- Hard to trace execution flow
|
||||
- Memory leaks if not unsubscribed
|
||||
|
||||
---
|
||||
|
||||
### NEW SYSTEM (Minimal Events)
|
||||
|
||||
**State machine handles most transitions internally:**
|
||||
```csharp
|
||||
// States transition via state machine
|
||||
_context.StateMachine.ChangeState("FlippingState");
|
||||
|
||||
// Optional: Add events only where external systems need notifications
|
||||
var albumEnlargedState = card.GetStateComponent<CardAlbumEnlargedState>("AlbumEnlargedState");
|
||||
albumEnlargedState.OnEnlargeRequested += HandleEnlargeRequest;
|
||||
|
||||
// OR: Just poll current state
|
||||
if (card.GetCurrentStateName() == "EnlargedNewState")
|
||||
{
|
||||
// React to state
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Fewer events needed
|
||||
- State machine manages flow
|
||||
- Easy to trace (just follow state transitions)
|
||||
- Less memory leak risk
|
||||
|
||||
---
|
||||
|
||||
## Debugging Comparison
|
||||
|
||||
### OLD SYSTEM
|
||||
```
|
||||
Q: Why isn't this card clickable?
|
||||
|
||||
A: Check:
|
||||
1. _isClickable flag in FlippableCard
|
||||
2. _isWaitingForTap flag
|
||||
3. _isFlipped flag
|
||||
4. _isFlipping flag
|
||||
5. _isEnlarged flag in AlbumCard
|
||||
6. _parentSlot reference in AlbumCard
|
||||
7. _isRevealed flag in AlbumCardPlacementDraggable
|
||||
8. _isDragRevealing flag
|
||||
9. _waitingForPlacementTap flag
|
||||
10. Click forwarding logic in AlbumCard
|
||||
11. Event subscriptions in parent page
|
||||
12. ...your head explodes 🤯
|
||||
|
||||
Debugging time: 20-30 minutes to trace all flags
|
||||
```
|
||||
|
||||
### NEW SYSTEM
|
||||
```
|
||||
Q: Why isn't this card clickable?
|
||||
|
||||
A: Look at active state in hierarchy:
|
||||
|
||||
Card
|
||||
└─ CardStateMachine
|
||||
└─ FlippingState (🟢 ACTIVE)
|
||||
|
||||
Answer: Card is in FlippingState, which doesn't handle clicks.
|
||||
|
||||
Solution: Wait for transition to RevealedState.
|
||||
|
||||
Debugging time: 5 seconds ✨
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adding New Feature Comparison
|
||||
|
||||
### Scenario: Add "Trading" State
|
||||
|
||||
**OLD SYSTEM:**
|
||||
1. Add `_isTrading` boolean to FlippableCard
|
||||
2. Add `_tradingUIShown` boolean
|
||||
3. Add trading UI GameObjects to prefab (always present)
|
||||
4. Add `ShowTradingUI()` and `HideTradingUI()` methods
|
||||
5. Add conditional logic to `OnPointerClick()`:
|
||||
```csharp
|
||||
if (_isTrading) {
|
||||
// Handle trading click
|
||||
} else if (_isWaitingForTap) {
|
||||
// Handle enlarged dismiss
|
||||
} else if (_isFlipped) {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
6. Add `SetActive()` calls in multiple places
|
||||
7. Update AlbumCard to forward clicks during trading
|
||||
8. Add events for trading start/end
|
||||
9. Update BoosterOpeningPage to handle trading events
|
||||
10. Test all existing states still work
|
||||
11. Fix bugs where trading flag conflicts with other flags
|
||||
12. Add more `if (!_isTrading)` checks everywhere
|
||||
|
||||
**Time:** 4-6 hours + debugging
|
||||
|
||||
---
|
||||
|
||||
**NEW SYSTEM:**
|
||||
1. Create `CardTradingState.cs`:
|
||||
```csharp
|
||||
public class CardTradingState : AppleState, IPointerClickHandler
|
||||
{
|
||||
[SerializeField] private GameObject tradingUI;
|
||||
private CardContext _context;
|
||||
|
||||
void Awake() => _context = GetComponentInParent<CardContext>();
|
||||
|
||||
public override void OnEnterState()
|
||||
{
|
||||
tradingUI.SetActive(true);
|
||||
}
|
||||
|
||||
public void OnPointerClick(PointerEventData eventData)
|
||||
{
|
||||
// Handle trade confirmation
|
||||
_context.StateMachine.ChangeState("PlacedInSlotState");
|
||||
}
|
||||
|
||||
void OnDisable()
|
||||
{
|
||||
tradingUI.SetActive(false);
|
||||
}
|
||||
}
|
||||
```
|
||||
2. Add `TradingState` GameObject under CardStateMachine in prefab
|
||||
3. Add trading UI as child of TradingState
|
||||
4. Drag TradingState GameObject to CardTradingState component's tradingUI field
|
||||
5. Transition to it when needed:
|
||||
```csharp
|
||||
card.ChangeState("TradingState");
|
||||
```
|
||||
|
||||
**Time:** 30 minutes ✨
|
||||
|
||||
**No other files touched. No conflicts with existing states. Perfect isolation.**
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
### Old System
|
||||
- ❌ Wrapper hell (5 layers deep)
|
||||
- ❌ Code duplication (~150 lines)
|
||||
- ❌ Boolean soup (12+ flags)
|
||||
- ❌ Event spaghetti (12+ events)
|
||||
- ❌ Hard to debug (trace through 3 components)
|
||||
- ❌ Slow to extend (4-6 hours per feature)
|
||||
- ❌ Brittle (one change breaks multiple components)
|
||||
|
||||
### New System
|
||||
- ✅ Flat structure (states as children)
|
||||
- ✅ Zero duplication (shared CardAnimator)
|
||||
- ✅ Clean state machine (1 active state)
|
||||
- ✅ Minimal events (state machine handles flow)
|
||||
- ✅ Easy to debug (look at active GameObject)
|
||||
- ✅ Fast to extend (~30 min per feature)
|
||||
- ✅ Robust (isolated states can't break each other)
|
||||
|
||||
---
|
||||
|
||||
**The new system isn't "better code" - it's better ARCHITECTURE.**
|
||||
|
||||
The old code works. It's just built on a foundation of wrappers and boolean flags that made sense in a rush but doesn't scale.
|
||||
|
||||
The new system solves the root problem: **separation of concerns + state isolation**.
|
||||
|
||||
Each state knows what IT does. States don't know about each other. Add/remove/modify states without affecting others.
|
||||
|
||||
**That's the power of the state machine pattern.** 🎯
|
||||
|
||||
@@ -1,425 +0,0 @@
|
||||
# Card Prefab Assembly Guide
|
||||
|
||||
## Overview
|
||||
This guide walks you through creating the new Card prefab with state machine architecture while integrating with existing CardDisplay components.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create CardAnimationConfig Asset
|
||||
|
||||
1. In Unity Project window, right-click in `Assets/Data/CardSystem/`
|
||||
2. Select **Create → AppleHills → Card Animation Config**
|
||||
3. Name it `CardAnimationConfig`
|
||||
4. Configure settings (these match your current FlippableCard settings):
|
||||
- **Flip Animation**
|
||||
- Flip Duration: `0.6`
|
||||
- Flip Scale Punch: `1.1`
|
||||
- **Enlarge Animation**
|
||||
- Enlarged Scale: `2.5`
|
||||
- Scale Duration: `0.3`
|
||||
- **Hover Animation**
|
||||
- Hover Height: `10`
|
||||
- Hover Duration: `1.5`
|
||||
- Hover Scale Multiplier: `1.05`
|
||||
- **Drag Animation**
|
||||
- Drag Scale: `1.1`
|
||||
- Snap Duration: `0.4`
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create Base Card Prefab
|
||||
|
||||
### Create Root GameObject
|
||||
1. In Hierarchy, right-click → **Create Empty**
|
||||
2. Name it `Card`
|
||||
3. Add Component → **Rect Transform** (converts to UI element)
|
||||
4. Set **Anchors** to center-middle
|
||||
5. Set **Size** to `200 x 280` (standard card size)
|
||||
|
||||
### Add Core Components to Root
|
||||
1. **Add CardContext component:**
|
||||
- Click **Add Component** → search `CardContext`
|
||||
- Leave references empty for now (will auto-find)
|
||||
|
||||
2. **Add CardAnimator component:**
|
||||
- Click **Add Component** → search `CardAnimator`
|
||||
- Drag `CardAnimationConfig` asset to **Config** field
|
||||
|
||||
3. **Add Card component:**
|
||||
- Click **Add Component** → search `Card`
|
||||
- Set **Initial State** to `IdleState`
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Add CardDisplay (From Existing Prefab)
|
||||
|
||||
### Option A: If you have existing CardDisplay prefab
|
||||
1. Drag `CardDisplay` prefab into hierarchy as child of `Card`
|
||||
2. Position at `(0, 0, 0)` local position
|
||||
3. Ensure it fills the card area
|
||||
|
||||
### Option B: Create CardDisplay from scratch
|
||||
1. Right-click `Card` in hierarchy → **Create Empty**
|
||||
2. Name it `CardDisplay`
|
||||
3. Add Component → **Card Display** (your existing script)
|
||||
4. Setup UI elements as children:
|
||||
- Add **Image** for card image
|
||||
- Add **TextMeshProUGUI** for card name
|
||||
- Add **Image** for frame
|
||||
- Add **Image** for overlay
|
||||
- Add **Image** for background
|
||||
- Add **Image** for zone shape
|
||||
5. Assign these to CardDisplay component fields
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Create State Machine Hierarchy
|
||||
|
||||
### Create StateMachine GameObject
|
||||
1. Right-click `Card` → **Create Empty**
|
||||
2. Name it `CardStateMachine`
|
||||
3. Add Component → **Apple Machine** (from Pixelplacement)
|
||||
4. Configure AppleMachine:
|
||||
- **Verbose**: unchecked (unless debugging)
|
||||
- **Allow Reentry**: unchecked
|
||||
- **Return To Default On Disable**: checked
|
||||
|
||||
### Create State GameObjects (as children of CardStateMachine)
|
||||
|
||||
For each state, follow this pattern:
|
||||
|
||||
#### 1. IdleState
|
||||
1. Right-click `CardStateMachine` → **Create Empty**
|
||||
2. Name it `IdleState`
|
||||
3. Add Component → **Card Idle State**
|
||||
4. **Create CardBackVisual child:**
|
||||
- Right-click `IdleState` → **UI → Image**
|
||||
- Name it `CardBackVisual`
|
||||
- Set **Anchors** to stretch-stretch
|
||||
- Set **Left/Right/Top/Bottom** to `0`
|
||||
- Assign your card back sprite to **Source Image**
|
||||
- Drag this to **Card Back Visual** field on CardIdleState component
|
||||
- **Note:** This state handles both idle behavior AND flip animation
|
||||
|
||||
#### 2. RevealedState
|
||||
1. Right-click `CardStateMachine` → **Create Empty**
|
||||
2. Name it `RevealedState`
|
||||
3. Add Component → **Card Revealed State**
|
||||
4. **Create idle badge visuals:**
|
||||
- Right-click `RevealedState` → **Create Empty**
|
||||
- Name it `NewCardIdleBadge`
|
||||
- Add child **UI → Image** for small badge background
|
||||
- Add child **UI → TextMeshProUGUI** for "NEW!" text
|
||||
- Position at top-right corner (e.g., X offset +70, Y offset +100)
|
||||
- Drag `NewCardIdleBadge` to **New Card Idle Badge** field
|
||||
|
||||
- Right-click `RevealedState` → **Create Empty**
|
||||
- Name it `RepeatCardIdleBadge`
|
||||
- Add child **UI → Image** for small badge background
|
||||
- Add child **UI → TextMeshProUGUI** for "REPEAT" text
|
||||
- Position at top-right corner (same position as NEW badge)
|
||||
- Drag `RepeatCardIdleBadge` to **Repeat Card Idle Badge** field
|
||||
|
||||
#### 3. EnlargedNewState
|
||||
1. Right-click `CardStateMachine` → **Create Empty**
|
||||
2. Name it `EnlargedNewState`
|
||||
3. Add Component → **Card Enlarged New State**
|
||||
4. **Create NewCardBadge child:**
|
||||
- Right-click `EnlargedNewState` → **Create Empty**
|
||||
- Name it `NewCardBadge`
|
||||
- Add child **UI → Image** for badge background
|
||||
- Add child **UI → TextMeshProUGUI** for "NEW CARD" text
|
||||
- Position badge at top of card (e.g., Y offset +100)
|
||||
- Drag parent `NewCardBadge` to **New Card Badge** field on CardEnlargedNewState
|
||||
|
||||
#### 4. EnlargedRepeatState
|
||||
1. Right-click `CardStateMachine` → **Create Empty**
|
||||
2. Name it `EnlargedRepeatState`
|
||||
3. Add Component → **Card Enlarged Repeat State**
|
||||
4. **Create ProgressBarUI child:**
|
||||
- Right-click `EnlargedRepeatState` → **Create Empty** (or drag your ProgressBarUI prefab)
|
||||
- Name it `ProgressBarUI`
|
||||
- Add **ProgressBarController** component to this GameObject
|
||||
- Add **VerticalLayoutGroup** component (enable "Reverse Arrangement")
|
||||
- Create 5 child **UI → Image** elements under ProgressBarUI
|
||||
- Name them `ProgressElement1` through `ProgressElement5`
|
||||
- Position at bottom of card (e.g., Y offset -100)
|
||||
- Drag `ProgressBarController` component to **Progress Bar** field on CardEnlargedRepeatState
|
||||
|
||||
#### 5. DraggingState
|
||||
1. Right-click `CardStateMachine` → **Create Empty**
|
||||
2. Name it `DraggingState`
|
||||
3. Add Component → **Card Dragging State**
|
||||
4. Set **Drag Scale** to `1.1`
|
||||
5. **No child visuals needed** for this state
|
||||
|
||||
#### 6. PlacedInSlotState
|
||||
1. Right-click `CardStateMachine` → **Create Empty**
|
||||
2. Name it `PlacedInSlotState`
|
||||
3. Add Component → **Card Placed In Slot State**
|
||||
4. **No child visuals needed** for this state
|
||||
|
||||
#### 7. AlbumEnlargedState
|
||||
1. Right-click `CardStateMachine` → **Create Empty**
|
||||
2. Name it `AlbumEnlargedState`
|
||||
3. Add Component → **Card Album Enlarged State**
|
||||
4. **No child visuals needed** for this state
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Wire Up References
|
||||
|
||||
### On CardStateMachine (AppleMachine component)
|
||||
1. Select `CardStateMachine` GameObject
|
||||
2. Set **Default State** to `IdleState` GameObject (drag from hierarchy)
|
||||
|
||||
### On Card Root (Card component)
|
||||
1. Select root `Card` GameObject
|
||||
2. **Context** should auto-find CardContext component
|
||||
3. **Animator** should auto-find CardAnimator component
|
||||
4. **State Machine** should auto-find CardStateMachine/AppleMachine
|
||||
5. If not auto-found, drag components manually
|
||||
|
||||
### On CardContext Component
|
||||
1. Select root `Card` GameObject
|
||||
2. In CardContext component:
|
||||
- **Card Display**: Drag `CardDisplay` child GameObject
|
||||
- **Card Animator**: Should auto-find on same GameObject
|
||||
- **State Machine**: Should auto-find CardStateMachine child
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Test the State Machine
|
||||
|
||||
### Test in Editor (Play Mode)
|
||||
1. Select root `Card` in hierarchy
|
||||
2. In Card component, call `SetupCard()` from inspector (you'll need test data)
|
||||
3. Watch the state machine transition through states
|
||||
4. Check **CardStateMachine → Current State** field to see active state
|
||||
5. Click the card to trigger state transitions
|
||||
|
||||
### Debug Tips
|
||||
- Enable **Verbose** on AppleMachine to see state change logs
|
||||
- Watch hierarchy - active state GameObject will be enabled (blue icon)
|
||||
- Inactive states will be disabled (gray icon)
|
||||
- State-owned visuals (CardBackVisual, NewCardBadge, etc.) should activate/deactivate with their parent state
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Save as Prefab
|
||||
|
||||
1. Drag the root `Card` GameObject from hierarchy to `Assets/Prefabs/UI/CardSystem/`
|
||||
2. Name it `Card.prefab`
|
||||
3. Delete the instance from hierarchy (prefab is saved)
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Integration with Existing Code
|
||||
|
||||
### Spawning New Cards (BoosterOpeningPage example)
|
||||
|
||||
**Old code:**
|
||||
```csharp
|
||||
GameObject cardObj = Instantiate(flippableCardPrefab, cardDisplayContainer);
|
||||
FlippableCard card = cardObj.GetComponent<FlippableCard>();
|
||||
card.SetupCard(cardData);
|
||||
```
|
||||
|
||||
**New code:**
|
||||
```csharp
|
||||
GameObject cardObj = Instantiate(cardPrefab, cardDisplayContainer);
|
||||
Card card = cardObj.GetComponent<Card>();
|
||||
card.SetupForBoosterReveal(cardData, isNew: true);
|
||||
```
|
||||
|
||||
### Placing Cards in Album (AlbumViewPage example)
|
||||
|
||||
**Old code:**
|
||||
```csharp
|
||||
AlbumCard albumCard = Instantiate(albumCardPrefab, slot.transform);
|
||||
albumCard.SetupCard(cardData);
|
||||
albumCard.SetParentSlot(slot);
|
||||
```
|
||||
|
||||
**New code:**
|
||||
```csharp
|
||||
Card card = Instantiate(cardPrefab, slot.transform);
|
||||
card.SetupForAlbumSlot(cardData, slot);
|
||||
```
|
||||
|
||||
### Listening to State Events
|
||||
|
||||
**Example - Listening for card reveal:**
|
||||
```csharp
|
||||
Card card = GetComponent<Card>();
|
||||
var flippingState = card.GetStateComponent<CardFlippingState>("FlippingState");
|
||||
|
||||
// Subscribe to flip complete (you may need to add custom events)
|
||||
// Or check current state:
|
||||
if (card.GetCurrentStateName() == "RevealedState")
|
||||
{
|
||||
// Card was revealed
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 9: Create Prefab Variants (Optional)
|
||||
|
||||
You can create variants for different card contexts:
|
||||
|
||||
### BoosterCard Variant
|
||||
1. Right-click `Card.prefab` → **Create → Prefab Variant**
|
||||
2. Name it `BoosterCard.prefab`
|
||||
3. Adjust initial state to `IdleState`
|
||||
4. Customize appearance if needed
|
||||
|
||||
### AlbumCard Variant
|
||||
1. Right-click `Card.prefab` → **Create → Prefab Variant**
|
||||
2. Name it `AlbumCard.prefab`
|
||||
3. Adjust initial state to `PlacedInSlotState`
|
||||
4. Remove states not needed (like IdleState, FlippingState if cards are pre-placed)
|
||||
|
||||
---
|
||||
|
||||
## Hierarchy Reference (Final Structure)
|
||||
|
||||
```
|
||||
Card (RectTransform)
|
||||
├─ [CardContext component]
|
||||
├─ [CardAnimator component]
|
||||
├─ [Card component]
|
||||
├─ CardDisplay
|
||||
│ ├─ CardImage (Image)
|
||||
│ ├─ CardNameText (TextMeshProUGUI)
|
||||
│ ├─ FrameImage (Image)
|
||||
│ ├─ OverlayImage (Image)
|
||||
│ ├─ BackgroundImage (Image)
|
||||
│ └─ ZoneShapeImage (Image)
|
||||
└─ CardStateMachine
|
||||
├─ [AppleMachine component]
|
||||
├─ IdleState
|
||||
│ ├─ [CardIdleState component]
|
||||
│ └─ CardBackVisual (Image)
|
||||
├─ RevealedState
|
||||
│ ├─ [CardRevealedState component]
|
||||
│ ├─ NewCardIdleBadge
|
||||
│ │ ├─ BadgeBackground (Image)
|
||||
│ │ └─ BadgeText (TextMeshProUGUI - "NEW!")
|
||||
│ └─ RepeatCardIdleBadge
|
||||
│ ├─ BadgeBackground (Image)
|
||||
│ └─ BadgeText (TextMeshProUGUI - "REPEAT")
|
||||
├─ EnlargedNewState
|
||||
│ ├─ [CardEnlargedNewState component]
|
||||
│ └─ NewCardBadge
|
||||
│ ├─ BadgeBackground (Image)
|
||||
│ └─ BadgeText (TextMeshProUGUI - "NEW CARD")
|
||||
├─ EnlargedRepeatState
|
||||
│ ├─ [CardEnlargedRepeatState component]
|
||||
│ └─ ProgressBarUI
|
||||
│ ├─ [ProgressBarController component]
|
||||
│ ├─ [VerticalLayoutGroup component - Reverse Arrangement]
|
||||
│ ├─ ProgressElement1 (Image - 1/5)
|
||||
│ ├─ ProgressElement2 (Image - 2/5)
|
||||
│ ├─ ProgressElement3 (Image - 3/5)
|
||||
│ ├─ ProgressElement4 (Image - 4/5)
|
||||
│ └─ ProgressElement5 (Image - 5/5)
|
||||
├─ DraggingState
|
||||
│ └─ [CardDraggingState component]
|
||||
├─ PlacedInSlotState
|
||||
│ └─ [CardPlacedInSlotState component]
|
||||
└─ AlbumEnlargedState
|
||||
└─ [CardAlbumEnlargedState component]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: States not transitioning
|
||||
- **Check:** AppleMachine **Default State** is assigned
|
||||
- **Check:** State names match exactly (case-sensitive: "IdleState" not "idlestate")
|
||||
- **Check:** Enable **Verbose** on AppleMachine to see logs
|
||||
|
||||
### Issue: Visuals not showing
|
||||
- **Check:** State-owned visuals (CardBackVisual, etc.) are assigned in state components
|
||||
- **Check:** Images have sprites assigned
|
||||
- **Check:** RectTransforms are sized properly (not 0x0)
|
||||
|
||||
### Issue: CardContext references null
|
||||
- **Check:** CardDisplay is assigned on CardContext component
|
||||
- **Check:** CardAnimator has CardAnimationConfig asset assigned
|
||||
- **Check:** All components are on correct GameObjects
|
||||
|
||||
### Issue: Animations not playing
|
||||
- **Check:** CardAnimationConfig asset is assigned to CardAnimator
|
||||
- **Check:** Tween system (Pixelplacement) is in project
|
||||
- **Check:** Config values are not zero
|
||||
|
||||
### Issue: Click not working
|
||||
- **Check:** Canvas has **Graphic Raycaster** component
|
||||
- **Check:** EventSystem exists in scene
|
||||
- **Check:** Card has **CanvasGroup** with **Blocks Raycasts** enabled (or Image component)
|
||||
- **Check:** State components implement IPointerClickHandler (IdleState, RevealedState, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
- [ ] Created CardAnimationConfig asset
|
||||
- [ ] Created base Card prefab with all components
|
||||
- [ ] Created all 7 state GameObjects under CardStateMachine
|
||||
- [ ] Assigned state-owned visuals (CardBackVisual, NewCardBadge, ProgressBarUI)
|
||||
- [ ] Wired up all component references
|
||||
- [ ] Tested state transitions in Play mode
|
||||
- [ ] Saved as prefab
|
||||
- [ ] Updated BoosterOpeningPage to use new Card prefab
|
||||
- [ ] Updated AlbumViewPage to use new Card prefab
|
||||
- [ ] Tested booster opening flow
|
||||
- [ ] Tested album placement flow
|
||||
- [ ] Tested enlarge/shrink interactions
|
||||
- [ ] (Optional) Deprecated old prefabs (FlippableCard, AlbumCard, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps After Prefab Creation
|
||||
|
||||
1. **Test Booster Opening Flow:**
|
||||
- Open BoosterOpeningPage scene
|
||||
- Replace FlippableCard prefab references with Card prefab
|
||||
- Test pack opening, card reveal, new/repeat states
|
||||
|
||||
2. **Test Album Flow:**
|
||||
- Open AlbumViewPage scene
|
||||
- Replace AlbumCard prefab references with Card prefab
|
||||
- Test placing cards in slots, enlarging from album
|
||||
|
||||
3. **Performance Testing:**
|
||||
- Spawn 10+ cards at once
|
||||
- Check frame rate, tween performance
|
||||
- Verify no memory leaks from state transitions
|
||||
|
||||
4. **Clean Up Old Code:**
|
||||
- Once new system is stable, deprecate:
|
||||
- `FlippableCard.cs`
|
||||
- `AlbumCard.cs`
|
||||
- `AlbumCardPlacementDraggable.cs` (if fully replaced)
|
||||
- Keep `CardDisplay.cs` (still used!)
|
||||
- Archive old prefabs for reference
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ Card prefab created with 7 functional states
|
||||
✅ State transitions work (Idle → Revealed → Enlarged, etc.)
|
||||
✅ State-owned visuals activate/deactivate automatically
|
||||
✅ Animations play correctly (flip, enlarge, hover)
|
||||
✅ Click interactions work in all states
|
||||
✅ Integration with BoosterOpeningPage works
|
||||
✅ Integration with AlbumViewPage works
|
||||
✅ No console errors during state transitions
|
||||
✅ Performance is acceptable (60fps with multiple cards)
|
||||
|
||||
Once all criteria met, you have successfully migrated to the new card system! 🎉
|
||||
|
||||
@@ -1,310 +0,0 @@
|
||||
# Card Prefab Visual Assembly Reference
|
||||
|
||||
## Complete Hierarchy with Components
|
||||
|
||||
```
|
||||
📦 Card (GameObject)
|
||||
│ 🔧 RectTransform
|
||||
│ 🔧 Card (component)
|
||||
│ 🔧 CardContext (component)
|
||||
│ 🔧 CardAnimator (component)
|
||||
│ 🔧 [Optional] CardInteractionHandler (component)
|
||||
│
|
||||
├─📄 CardDisplay (GameObject)
|
||||
│ │ 🔧 Card Display (component) ← Your existing script
|
||||
│ │
|
||||
│ ├─🖼️ CardImage (Image)
|
||||
│ ├─📝 CardNameText (TextMeshProUGUI)
|
||||
│ ├─🖼️ FrameImage (Image)
|
||||
│ ├─🖼️ OverlayImage (Image)
|
||||
│ ├─🖼️ BackgroundImage (Image)
|
||||
│ └─🖼️ ZoneShapeImage (Image)
|
||||
│
|
||||
└─🎮 CardStateMachine (GameObject)
|
||||
│ 🔧 AppleMachine (component) ← Pixelplacement StateMachine
|
||||
│ ⚙️ Default State: → IdleState
|
||||
│ ⚙️ Verbose: ☐ (check for debugging)
|
||||
│ ⚙️ Allow Reentry: ☐
|
||||
│ ⚙️ Return To Default On Disable: ☑
|
||||
│
|
||||
├─🟦 IdleState (GameObject) ← Active when idle
|
||||
│ └─🔧 CardIdleState (component)
|
||||
│
|
||||
├─🟦 FlippingState (GameObject) ← Active during flip
|
||||
│ │ 🔧 CardFlippingState (component)
|
||||
│ │ 🔗 Card Back Visual: → CardBackVisual
|
||||
│ │
|
||||
│ └─🖼️ CardBackVisual (Image)
|
||||
│ ⚙️ Source Image: [Your card back sprite]
|
||||
│ ⚙️ Anchors: Stretch-Stretch
|
||||
│ ⚙️ Left/Right/Top/Bottom: 0
|
||||
│
|
||||
├─🟦 RevealedState (GameObject) ← Active after flip
|
||||
│ └─🔧 CardRevealedState (component)
|
||||
│
|
||||
├─🟦 EnlargedNewState (GameObject) ← Active when new card enlarged
|
||||
│ │ 🔧 CardEnlargedNewState (component)
|
||||
│ │ 🔗 New Card Badge: → NewCardBadge
|
||||
│ │
|
||||
│ └─📋 NewCardBadge (GameObject)
|
||||
│ ⚙️ Anchored Position: (0, 100, 0) ← Top of card
|
||||
│ │
|
||||
│ ├─🖼️ BadgeBackground (Image)
|
||||
│ │ ⚙️ Source Image: [Badge background sprite]
|
||||
│ │ ⚙️ Size: 150 x 40
|
||||
│ │
|
||||
│ └─📝 BadgeText (TextMeshProUGUI)
|
||||
│ ⚙️ Text: "NEW CARD!"
|
||||
│ ⚙️ Font Size: 18
|
||||
│ ⚙️ Alignment: Center
|
||||
│
|
||||
├─🟦 EnlargedRepeatState (GameObject) ← Active when repeat card enlarged
|
||||
│ │ 🔧 CardEnlargedRepeatState (component)
|
||||
│ │ 🔗 Progress Bar Container: → ProgressBarContainer
|
||||
│ │ 🔗 Progress Bar Fill: → BarFill
|
||||
│ │ 🔗 Progress Text: → CountText
|
||||
│ │ ⚙️ Cards To Upgrade: 5
|
||||
│ │
|
||||
│ └─📋 ProgressBarContainer (GameObject)
|
||||
│ ⚙️ Anchored Position: (0, -100, 0) ← Bottom of card
|
||||
│ │
|
||||
│ ├─🖼️ BarBackground (Image)
|
||||
│ │ ⚙️ Source Image: [Progress bar background]
|
||||
│ │ ⚙️ Size: 180 x 20
|
||||
│ │ ⚙️ Color: Gray
|
||||
│ │
|
||||
│ ├─🖼️ BarFill (Image)
|
||||
│ │ ⚙️ Source Image: [Same as background]
|
||||
│ │ ⚙️ Image Type: Filled (Horizontal)
|
||||
│ │ ⚙️ Fill Amount: 0.6 (example)
|
||||
│ │ ⚙️ Color: Green/Yellow
|
||||
│ │ ⚙️ Size: Same as BarBackground
|
||||
│ │
|
||||
│ └─📝 CountText (TextMeshProUGUI)
|
||||
│ ⚙️ Text: "3/5"
|
||||
│ ⚙️ Font Size: 14
|
||||
│ ⚙️ Alignment: Center
|
||||
│
|
||||
├─🟦 DraggingState (GameObject) ← Active during drag
|
||||
│ │ 🔧 CardDraggingState (component)
|
||||
│ │ ⚙️ Drag Scale: 1.1
|
||||
│ │
|
||||
├─🟦 PlacedInSlotState (GameObject) ← Active when in album
|
||||
│ └─🔧 CardPlacedInSlotState (component)
|
||||
│
|
||||
└─🟦 AlbumEnlargedState (GameObject) ← Active when enlarged from album
|
||||
└─🔧 CardAlbumEnlargedState (component)
|
||||
```
|
||||
|
||||
## Component Reference Wiring
|
||||
|
||||
### On Root "Card" GameObject:
|
||||
|
||||
#### Card (component)
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ Card Component │
|
||||
├─────────────────────────────────┤
|
||||
│ Context: → CardContext │ ← Auto-finds
|
||||
│ Animator: → CardAnimator │ ← Auto-finds
|
||||
│ State Machine: → AppleMachine │ ← Auto-finds in children
|
||||
│ Initial State: "IdleState" │ ← Type manually
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### CardContext (component)
|
||||
```
|
||||
┌──────────────────────────────────────┐
|
||||
│ CardContext Component │
|
||||
├──────────────────────────────────────┤
|
||||
│ Card Display: → CardDisplay │ ← Drag from hierarchy
|
||||
│ Card Animator: → CardAnimator │ ← Auto-finds
|
||||
│ State Machine: → AppleMachine │ ← Auto-finds in children
|
||||
└──────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### CardAnimator (component)
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ CardAnimator Component │
|
||||
├──────────────────────────────────────────┤
|
||||
│ Config: → CardAnimationConfig (asset) │ ← Drag from Project
|
||||
└──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### On "CardStateMachine" GameObject:
|
||||
|
||||
#### AppleMachine (component)
|
||||
```
|
||||
┌────────────────────────────────────────────┐
|
||||
│ AppleMachine Component │
|
||||
├────────────────────────────────────────────┤
|
||||
│ Default State: → IdleState (GameObject) │ ← Drag from children
|
||||
│ Current State: (runtime only) │
|
||||
│ Verbose: ☐ │
|
||||
│ Allow Reentry: ☐ │
|
||||
│ Return To Default On Disable: ☑ │
|
||||
└────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### On State GameObjects:
|
||||
|
||||
Each state GameObject only has its state component (e.g., CardIdleState).
|
||||
States with owned visuals have additional references:
|
||||
|
||||
#### FlippingState → CardFlippingState
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ CardFlippingState Component │
|
||||
├─────────────────────────────────────────┤
|
||||
│ Card Back Visual: → CardBackVisual │ ← Drag child Image
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### EnlargedNewState → CardEnlargedNewState
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ CardEnlargedNewState Component │
|
||||
├─────────────────────────────────────────┤
|
||||
│ New Card Badge: → NewCardBadge │ ← Drag child GameObject
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### EnlargedRepeatState → CardEnlargedRepeatState
|
||||
```
|
||||
┌──────────────────────────────────────────────┐
|
||||
│ CardEnlargedRepeatState Component │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ Progress Bar Container: → ProgressBarCont. │ ← Drag child
|
||||
│ Progress Bar Fill: → BarFill │ ← Drag grandchild
|
||||
│ Progress Text: → CountText │ ← Drag grandchild
|
||||
│ Cards To Upgrade: 5 │ ← Type number
|
||||
└──────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Asset Creation
|
||||
|
||||
### CardAnimationConfig Asset
|
||||
```
|
||||
Project Window:
|
||||
Assets/Data/CardSystem/
|
||||
└─ 📄 CardAnimationConfig.asset
|
||||
├─ Flip Duration: 0.6
|
||||
├─ Flip Scale Punch: 1.1
|
||||
├─ Enlarged Scale: 2.5
|
||||
├─ Scale Duration: 0.3
|
||||
├─ Hover Height: 10
|
||||
├─ Hover Duration: 1.5
|
||||
├─ Hover Scale Multiplier: 1.05
|
||||
├─ Drag Scale: 1.1
|
||||
└─ Snap Duration: 0.4
|
||||
```
|
||||
|
||||
## Visual Reference - Inactive vs Active States
|
||||
|
||||
**When idle (IdleState active):**
|
||||
```
|
||||
Card (enabled)
|
||||
├─ CardDisplay (enabled, visible)
|
||||
└─ CardStateMachine (enabled)
|
||||
├─ IdleState (🟢 ACTIVE/ENABLED)
|
||||
├─ FlippingState (⚫ inactive)
|
||||
├─ RevealedState (⚫ inactive)
|
||||
├─ EnlargedNewState (⚫ inactive)
|
||||
├─ EnlargedRepeatState (⚫ inactive)
|
||||
├─ DraggingState (⚫ inactive)
|
||||
├─ PlacedInSlotState (⚫ inactive)
|
||||
└─ AlbumEnlargedState (⚫ inactive)
|
||||
```
|
||||
|
||||
**During flip (FlippingState active):**
|
||||
```
|
||||
Card (enabled)
|
||||
├─ CardDisplay (disabled during flip, enabled after)
|
||||
└─ CardStateMachine (enabled)
|
||||
├─ IdleState (⚫ inactive)
|
||||
├─ FlippingState (🟢 ACTIVE/ENABLED)
|
||||
│ └─ CardBackVisual (🟢 VISIBLE during flip)
|
||||
├─ RevealedState (⚫ inactive)
|
||||
└─ ... (other states inactive)
|
||||
```
|
||||
|
||||
**When enlarged (EnlargedNewState active):**
|
||||
```
|
||||
Card (enabled, scaled up 2.5x)
|
||||
├─ CardDisplay (enabled, visible, scaled with parent)
|
||||
└─ CardStateMachine (enabled)
|
||||
├─ IdleState (⚫ inactive)
|
||||
├─ FlippingState (⚫ inactive)
|
||||
├─ RevealedState (⚫ inactive)
|
||||
├─ EnlargedNewState (🟢 ACTIVE/ENABLED)
|
||||
│ └─ NewCardBadge (🟢 VISIBLE)
|
||||
└─ ... (other states inactive)
|
||||
```
|
||||
|
||||
## Color Coding Legend
|
||||
|
||||
- 📦 = GameObject (container)
|
||||
- 🔧 = Component attached to GameObject
|
||||
- 🖼️ = Image component (UI visual)
|
||||
- 📝 = TextMeshProUGUI component (UI text)
|
||||
- 📋 = Container GameObject (holds other UI elements)
|
||||
- 📄 = Asset in Project window
|
||||
- 🎮 = State Machine GameObject
|
||||
- 🟦 = State GameObject
|
||||
- 🟢 = Currently active/enabled
|
||||
- ⚫ = Currently inactive/disabled
|
||||
- → = Reference/link to another object
|
||||
- ⚙️ = Property/setting to configure
|
||||
- ☐ = Checkbox unchecked
|
||||
- ☑ = Checkbox checked
|
||||
|
||||
## Quick Assembly Checklist
|
||||
|
||||
Use this while building the prefab:
|
||||
|
||||
**Root Setup:**
|
||||
- [ ] Create GameObject named "Card"
|
||||
- [ ] Add RectTransform
|
||||
- [ ] Add Card component
|
||||
- [ ] Add CardContext component
|
||||
- [ ] Add CardAnimator component
|
||||
- [ ] Set Card size to 200x280
|
||||
|
||||
**CardDisplay:**
|
||||
- [ ] Add CardDisplay child (or drag existing prefab)
|
||||
- [ ] Verify all image/text children exist
|
||||
- [ ] Verify CardDisplay component references are set
|
||||
|
||||
**State Machine:**
|
||||
- [ ] Add CardStateMachine child GameObject
|
||||
- [ ] Add AppleMachine component to it
|
||||
- [ ] Create 8 state GameObjects as children
|
||||
|
||||
**State-Owned Visuals:**
|
||||
- [ ] FlippingState: Add CardBackVisual child Image
|
||||
- [ ] EnlargedNewState: Add NewCardBadge child with badge UI
|
||||
- [ ] EnlargedRepeatState: Add ProgressBarContainer with progress UI
|
||||
|
||||
**Wire References:**
|
||||
- [ ] Card → Context, Animator, StateMachine
|
||||
- [ ] CardContext → CardDisplay, Animator, StateMachine
|
||||
- [ ] CardAnimator → CardAnimationConfig asset
|
||||
- [ ] AppleMachine → Default State (IdleState)
|
||||
- [ ] FlippingState → CardBackVisual
|
||||
- [ ] EnlargedNewState → NewCardBadge
|
||||
- [ ] EnlargedRepeatState → ProgressBarContainer, BarFill, CountText
|
||||
|
||||
**Test:**
|
||||
- [ ] Enter Play mode
|
||||
- [ ] No console errors on load
|
||||
- [ ] Click card to test state transitions
|
||||
- [ ] Verify visuals show/hide correctly
|
||||
|
||||
**Save:**
|
||||
- [ ] Drag to Prefabs/UI/CardSystem/
|
||||
- [ ] Name "Card.prefab"
|
||||
- [ ] Delete hierarchy instance
|
||||
|
||||
Done! 🎉
|
||||
|
||||
@@ -1,242 +0,0 @@
|
||||
# Card State Machine - Implementation Guide
|
||||
|
||||
## Summary
|
||||
|
||||
We've implemented a **state-based card system** using the **Isolated State Pattern** with Pixelplacement StateMachine. This eliminates code duplication, replaces boolean flags with explicit states, and provides a cleaner architecture.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
Card (RectTransform - Top Level)
|
||||
├─ CardDisplay (always visible card front)
|
||||
├─ CardContext (shared data/references)
|
||||
├─ CardAnimator (reusable animation methods)
|
||||
└─ CardStateMachine (AppleMachine child)
|
||||
├─ IdleState/
|
||||
│ └─ (optional hover visuals)
|
||||
├─ FlippingState/
|
||||
│ └─ CardBackVisual ← State owns this GameObject
|
||||
├─ EnlargedNewState/
|
||||
│ └─ NewCardBadge ← State owns this GameObject
|
||||
└─ EnlargedRepeatState/
|
||||
└─ ProgressBarUI ← State owns this GameObject
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
### 1. **CardContext.cs** ✅ IMPLEMENTED
|
||||
- Provides shared access to:
|
||||
- `CardDisplay` - The visual card front
|
||||
- `CardAnimator` - Animation helper
|
||||
- `StateMachine` - Pixelplacement AppleMachine
|
||||
- `CardData` - The card's data
|
||||
- `IsNewCard` - Whether this is a new card
|
||||
- `RepeatCardCount` - For repeat cards
|
||||
- States access context via `_context` field
|
||||
|
||||
### 2. **CardAnimator.cs** ✅ IMPLEMENTED
|
||||
Centralized animation methods using Pixelplacement Tween:
|
||||
|
||||
**Scale Animations:**
|
||||
- `AnimateScale(targetScale, duration?, onComplete?)` - Smooth scale transition
|
||||
- `PulseScale(pulseAmount, duration, onComplete?)` - Scale up then down
|
||||
- `PopIn(duration?, onComplete?)` - Scale from 0 with overshoot
|
||||
- `PopOut(duration?, onComplete?)` - Scale to 0
|
||||
|
||||
**Position Animations:**
|
||||
- `AnimateAnchoredPosition(targetPos, duration?, onComplete?)` - For UI RectTransforms
|
||||
- `AnimateLocalPosition(targetPos, duration?, onComplete?)` - For regular transforms
|
||||
|
||||
**Rotation Animations:**
|
||||
- `AnimateLocalRotation(targetRotation, duration?, onComplete?)` - Rotate the card root
|
||||
- `AnimateChildRotation(childTransform, targetRotation, duration, onComplete?)` - Rotate state visuals
|
||||
|
||||
**Hover Animations:**
|
||||
- `HoverEnter(liftAmount, scaleMultiplier, duration, onComplete?)` - Lift and scale on hover
|
||||
- `HoverExit(originalPosition, duration, onComplete?)` - Return to normal
|
||||
- `StartIdleHover(hoverHeight, duration)` - Gentle bobbing loop (returns TweenBase to stop later)
|
||||
|
||||
**Flip Animations (Two-Phase):**
|
||||
- `FlipPhase1_HideBack(cardBackTransform, duration, onHalfwayComplete)` - Rotate back 0° → 90°
|
||||
- `FlipPhase2_RevealFront(cardFrontTransform, duration, onComplete)` - Rotate front 180° → 0°
|
||||
- `FlipScalePunch(punchMultiplier, totalDuration)` - Scale punch during flip
|
||||
|
||||
**Utility:**
|
||||
- `StopAllAnimations()` - Stop all active tweens
|
||||
- `ResetTransform()` - Reset to default state
|
||||
- `GetAnchoredPosition()` - Get current anchored position
|
||||
|
||||
### 3. **State Classes** (Next to implement)
|
||||
Each state inherits from `Pixelplacement.State` and implements:
|
||||
- `OnEnterState()` - Setup when state becomes active
|
||||
- `OnExitState()` - Cleanup when state ends
|
||||
|
||||
States to create:
|
||||
- `CardIdleState` - Idle hover, click to flip
|
||||
- `CardFlippingState` - Flip animation with CardBackVisual
|
||||
- `CardRevealedState` - Card flipped, waiting for interaction
|
||||
- `CardEnlargedNewState` - Shows "NEW!" badge
|
||||
- `CardEnlargedRepeatState` - Shows progress bar
|
||||
- `CardDraggingState` - Being dragged to album
|
||||
- `CardPlacedInSlotState` - In album slot
|
||||
|
||||
## How States Work
|
||||
|
||||
### State-Owned Visuals
|
||||
Each state can have child GameObjects that are automatically activated/deactivated:
|
||||
|
||||
```
|
||||
FlippingState (State script attached)
|
||||
└─ CardBackVisual (Image showing card back)
|
||||
└─ Glow effect
|
||||
└─ Border
|
||||
```
|
||||
|
||||
When `FlippingState` activates → CardBackVisual activates automatically
|
||||
When `FlippingState` exits → CardBackVisual deactivates automatically
|
||||
|
||||
### Animation Flow
|
||||
States use `CardAnimator` for animations:
|
||||
|
||||
```csharp
|
||||
public class CardFlippingState : State
|
||||
{
|
||||
private CardContext _context;
|
||||
private Transform _cardBackVisual;
|
||||
|
||||
protected override void OnEnterState()
|
||||
{
|
||||
_context = GetComponentInParent<CardContext>();
|
||||
_cardBackVisual = transform.GetChild(0); // CardBackVisual child
|
||||
|
||||
// Use animator to flip
|
||||
_context.Animator.FlipPhase1_HideBack(_cardBackVisual, 0.3f, () =>
|
||||
{
|
||||
// Halfway through flip
|
||||
_context.CardDisplay.gameObject.SetActive(true);
|
||||
_context.Animator.FlipPhase2_RevealFront(_context.CardDisplay.transform, 0.3f, () =>
|
||||
{
|
||||
// Flip complete - transition to next state
|
||||
if (_context.IsNewCard)
|
||||
_context.StateMachine.ChangeState("EnlargedNewState");
|
||||
else
|
||||
_context.StateMachine.ChangeState("RevealedState");
|
||||
});
|
||||
});
|
||||
|
||||
// Add scale punch
|
||||
_context.Animator.FlipScalePunch(1.1f, 0.6f);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Transform Hierarchy Benefits
|
||||
- Animating **Card.transform** (root) affects **all children** (CardDisplay, StateMachine, all states)
|
||||
- States can animate their **own children** independently (e.g., rotating CardBackVisual)
|
||||
- No manual syncing needed - Unity hierarchy handles it!
|
||||
|
||||
## Prefab Assembly Guide
|
||||
|
||||
### Step 1: Create Card Root
|
||||
1. Create empty GameObject "Card"
|
||||
2. Add RectTransform component
|
||||
3. Add `CardContext` component
|
||||
4. Add `CardAnimator` component
|
||||
|
||||
### Step 2: Add CardDisplay
|
||||
1. Drag existing `CardDisplay` prefab as child of Card
|
||||
2. Assign to CardContext's `cardDisplay` field
|
||||
|
||||
### Step 3: Add StateMachine
|
||||
1. Create child GameObject "CardStateMachine"
|
||||
2. Add `AppleMachine` component (from Core.SaveLoad)
|
||||
3. Set initial state to "IdleState"
|
||||
|
||||
### Step 4: Add States
|
||||
For each state (e.g., FlippingState):
|
||||
1. Create child GameObject under CardStateMachine (name: "FlippingState")
|
||||
2. Add the state script component (e.g., `CardFlippingState`)
|
||||
3. Add state-specific visuals as children:
|
||||
- For FlippingState: Add "CardBackVisual" (Image)
|
||||
- For EnlargedNewState: Add "NewCardBadge" (UI group)
|
||||
- For EnlargedRepeatState: Add "ProgressBarUI" (UI group)
|
||||
|
||||
### Final Hierarchy
|
||||
```
|
||||
Card (RectTransform, CardContext, CardAnimator)
|
||||
├─ CardDisplay (from existing prefab)
|
||||
└─ CardStateMachine (AppleMachine)
|
||||
├─ IdleState (CardIdleState script)
|
||||
├─ FlippingState (CardFlippingState script)
|
||||
│ └─ CardBackVisual (Image)
|
||||
├─ RevealedState (CardRevealedState script)
|
||||
├─ EnlargedNewState (CardEnlargedNewState script)
|
||||
│ └─ NewCardBadge (UI group)
|
||||
└─ EnlargedRepeatState (CardEnlargedRepeatState script)
|
||||
└─ ProgressBarUI (UI group)
|
||||
```
|
||||
|
||||
## Old vs New Comparison
|
||||
|
||||
### Old System (Nested Wrappers)
|
||||
- `FlippableCard` wraps `AlbumCard` wraps `CardDisplay`
|
||||
- 5+ MonoBehaviour components per card
|
||||
- ~150 lines of duplicated animation code
|
||||
- 12+ boolean flags for state tracking
|
||||
- Manual `SetActive()` calls everywhere
|
||||
- Hard to add new behaviors
|
||||
|
||||
### New System (State Machine)
|
||||
- Single `Card` root with isolated states
|
||||
- Shared `CardAnimator` (0 duplication)
|
||||
- States explicitly named and isolated
|
||||
- Automatic visual activation/deactivation
|
||||
- Easy to add new states (just create new state GameObject + script)
|
||||
|
||||
## What About Old Scripts?
|
||||
|
||||
**FlippableCard, AlbumCard, etc. are NO LONGER NEEDED** once fully migrated.
|
||||
|
||||
The new Card prefab handles:
|
||||
- ✅ Flipping (via FlippingState + CardAnimator)
|
||||
- ✅ Album placement (via DraggingState + PlacedInSlotState)
|
||||
- ✅ New/Repeat display (via EnlargedNewState/EnlargedRepeatState)
|
||||
- ✅ Hover effects (via IdleState + CardAnimator)
|
||||
|
||||
Old scripts provided these behaviors through nesting, but the new state machine consolidates everything into one clean prefab with isolated states.
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Implement remaining states:**
|
||||
- CardIdleState
|
||||
- CardFlippingState
|
||||
- CardRevealedState
|
||||
- CardEnlargedNewState
|
||||
- CardEnlargedRepeatState
|
||||
|
||||
2. **Create Card prefab** following assembly guide above
|
||||
|
||||
3. **Test in BoosterOpeningPage:**
|
||||
- Spawn new Card prefabs instead of FlippableCard
|
||||
- Drive state transitions via CardStateMachine
|
||||
- Remove old FlippableCard references
|
||||
|
||||
4. **Migrate Album flow:**
|
||||
- Add DraggingState and PlacedInSlotState
|
||||
- Update AlbumViewPage to use new Card
|
||||
- Remove old AlbumCard references
|
||||
|
||||
## Benefits Realized
|
||||
|
||||
✅ **Zero animation duplication** - All in CardAnimator
|
||||
✅ **Clear state flow** - Explicit state names instead of booleans
|
||||
✅ **Automatic visual management** - States activate/deactivate their children
|
||||
✅ **Easy to extend** - Add new state = add new GameObject + script
|
||||
✅ **Simpler debugging** - Check active state name instead of 12 booleans
|
||||
✅ **Flatter hierarchy** - States as siblings instead of 5 layers deep
|
||||
|
||||
---
|
||||
|
||||
**Implementation Date:** November 11, 2025
|
||||
**Status:** Core components complete, state implementations next
|
||||
|
||||
@@ -1,216 +0,0 @@
|
||||
# Card State Machine - Quick Reference
|
||||
|
||||
## State Flow Diagram
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ IdleState │ ← Booster card waiting to be clicked
|
||||
└──────┬──────┘
|
||||
│ [click]
|
||||
▼
|
||||
┌──────────────┐
|
||||
│FlippingState │ ← Card flipping animation (owns CardBackVisual)
|
||||
└──────┬───────┘
|
||||
│ [flip complete]
|
||||
├──[if IsNew]──────────┐
|
||||
│ ▼
|
||||
│ ┌────────────────┐
|
||||
│ │EnlargedNewState│ ← Shows "NEW CARD" badge
|
||||
│ └───────┬────────┘
|
||||
│ │ [tap]
|
||||
│ ▼
|
||||
├──[if Repeat]────────┐
|
||||
│ ▼
|
||||
│ ┌──────────────────────┐
|
||||
│ │EnlargedRepeatState │ ← Shows progress bar X/5
|
||||
│ └──────────┬───────────┘
|
||||
│ │ [tap]
|
||||
│ ▼
|
||||
└──────────────────────►┌──────────────┐
|
||||
│RevealedState │ ← Card visible, waiting for action
|
||||
└──────┬───────┘
|
||||
│
|
||||
┌──────────────┼──────────────┐
|
||||
│ [drag] │ [in album, │
|
||||
▼ │ click] ▼
|
||||
┌──────────────┐ │ ┌─────────────────────┐
|
||||
│DraggingState │ │ │AlbumEnlargedState │
|
||||
└──────┬───────┘ │ └──────────┬──────────┘
|
||||
│ │ │ [tap]
|
||||
│ [drop] │ │
|
||||
▼ │ ▼
|
||||
┌─────────────────┐ │ ┌──────────────────┐
|
||||
│PlacedInSlotState│◄─┘ │PlacedInSlotState │
|
||||
└─────────────────┘ └──────────────────┘
|
||||
▲
|
||||
│ [click while in album]
|
||||
└───────────────────────┘
|
||||
```
|
||||
|
||||
## Component Responsibilities
|
||||
|
||||
| Component | Purpose |
|
||||
|-----------|---------|
|
||||
| **Card** | Main controller, provides API for setup and state control |
|
||||
| **CardContext** | Shared data/references accessible to all states |
|
||||
| **CardAnimator** | Reusable animation methods (no duplicate code) |
|
||||
| **CardDisplay** | Pure visual renderer (unchanged from old system) |
|
||||
| **State Scripts** | Each state handles its own behavior and owned visuals |
|
||||
|
||||
## API Quick Reference
|
||||
|
||||
### Setup Card for Booster Reveal
|
||||
```csharp
|
||||
Card card = Instantiate(cardPrefab, parent);
|
||||
card.SetupForBoosterReveal(cardData, isNew: true);
|
||||
// Starts at IdleState, player clicks to flip
|
||||
```
|
||||
|
||||
### Setup Card for Album Slot
|
||||
```csharp
|
||||
Card card = Instantiate(cardPrefab, slot.transform);
|
||||
card.SetupForAlbumSlot(cardData, slot);
|
||||
// Starts at PlacedInSlotState, player can click to enlarge
|
||||
```
|
||||
|
||||
### Manual State Transition
|
||||
```csharp
|
||||
card.ChangeState("FlippingState");
|
||||
```
|
||||
|
||||
### Get Current State
|
||||
```csharp
|
||||
string currentState = card.GetCurrentStateName();
|
||||
```
|
||||
|
||||
### Access Specific State Component
|
||||
```csharp
|
||||
var idleState = card.GetStateComponent<CardIdleState>("IdleState");
|
||||
```
|
||||
|
||||
## State-Owned Visuals
|
||||
|
||||
| State | Owned Visual | Purpose |
|
||||
|-------|--------------|---------|
|
||||
| FlippingState | CardBackVisual | Card back shown during flip |
|
||||
| EnlargedNewState | NewCardBadge | "NEW CARD" text/badge |
|
||||
| EnlargedRepeatState | ProgressBarUI | Progress bar showing X/5 copies |
|
||||
| All Others | (none) | Use shared CardDisplay |
|
||||
|
||||
## Animation Methods (CardAnimator)
|
||||
|
||||
```csharp
|
||||
// Hover animation
|
||||
animator.PlayIdleHover(rectTransform, originalPosition);
|
||||
animator.StopIdleHover(rectTransform, originalPosition);
|
||||
|
||||
// Flip animation
|
||||
animator.PlayFlip(cardBack, cardFront, onComplete);
|
||||
animator.PlayFlipScalePunch(transform);
|
||||
|
||||
// Enlarge/shrink
|
||||
animator.PlayEnlarge(transform, onComplete);
|
||||
animator.PlayShrink(transform, originalScale, onComplete);
|
||||
|
||||
// Hover scale
|
||||
animator.PlayHoverScaleUp(transform);
|
||||
animator.PlayHoverScaleDown(transform);
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern: Add Custom Event to State
|
||||
```csharp
|
||||
// In state script
|
||||
public event Action<CardData> OnCustomEvent;
|
||||
|
||||
public override void OnEnterState()
|
||||
{
|
||||
// Do state work
|
||||
OnCustomEvent?.Invoke(_context.CardData);
|
||||
}
|
||||
|
||||
// In consuming code
|
||||
var state = card.GetStateComponent<SomeState>("SomeState");
|
||||
state.OnCustomEvent += (cardData) => { /* handle */ };
|
||||
```
|
||||
|
||||
### Pattern: Conditional State Transition
|
||||
```csharp
|
||||
// In FlippingState.OnFlipComplete()
|
||||
if (_context.IsNewCard)
|
||||
_context.StateMachine.ChangeState("EnlargedNewState");
|
||||
else if (_context.RepeatCardCount > 0)
|
||||
_context.StateMachine.ChangeState("EnlargedRepeatState");
|
||||
else
|
||||
_context.StateMachine.ChangeState("RevealedState");
|
||||
```
|
||||
|
||||
### Pattern: Store State-Specific Data
|
||||
```csharp
|
||||
// In CardContext
|
||||
public int RepeatCardCount { get; set; }
|
||||
public AlbumCardSlot CurrentSlot { get; set; }
|
||||
|
||||
// States read/write this data
|
||||
_context.RepeatCardCount = 3;
|
||||
```
|
||||
|
||||
## Files Created
|
||||
|
||||
**Core:**
|
||||
- `Card.cs` - Main controller
|
||||
- `CardContext.cs` - Shared context
|
||||
- `CardAnimator.cs` - Animation controller
|
||||
- `CardAnimationConfig.cs` - ScriptableObject config
|
||||
|
||||
**States:**
|
||||
- `States/CardIdleState.cs`
|
||||
- `States/CardFlippingState.cs`
|
||||
- `States/CardRevealedState.cs`
|
||||
- `States/CardEnlargedNewState.cs`
|
||||
- `States/CardEnlargedRepeatState.cs`
|
||||
- `States/CardDraggingState.cs`
|
||||
- `States/CardPlacedInSlotState.cs`
|
||||
- `States/CardAlbumEnlargedState.cs`
|
||||
|
||||
**Optional:**
|
||||
- `States/CardInteractionHandler.cs` - Drag/drop bridge
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
1. **Enable Verbose Logging**
|
||||
- Select CardStateMachine GameObject
|
||||
- Check "Verbose" on AppleMachine component
|
||||
- Console will log every state transition
|
||||
|
||||
2. **Inspect Current State**
|
||||
- Select Card in hierarchy during Play mode
|
||||
- Look at CardStateMachine → Current State field
|
||||
- Active state GameObject will be enabled (blue icon)
|
||||
|
||||
3. **Watch State-Owned Visuals**
|
||||
- Expand state GameObjects in hierarchy
|
||||
- Watch child visuals enable/disable with state
|
||||
|
||||
4. **Test State Transitions Manually**
|
||||
- In Play mode, select Card
|
||||
- In Card component, use ChangeState() in inspector
|
||||
- Or call via Console: `FindObjectOfType<Card>().ChangeState("IdleState")`
|
||||
|
||||
## Performance Notes
|
||||
|
||||
- **State transitions are cheap** - just GameObject activation
|
||||
- **Animations use Pixelplacement Tween** - already optimized
|
||||
- **No duplicate animation code** - all shared via CardAnimator
|
||||
- **State-owned visuals** only exist when needed (inactive otherwise)
|
||||
|
||||
## Migration Path
|
||||
|
||||
1. **Phase 1:** Create new Card prefab alongside old system ✅
|
||||
2. **Phase 2:** Test in isolated scene
|
||||
3. **Phase 3:** Replace one use case at a time (booster opening first)
|
||||
4. **Phase 4:** Replace album interactions
|
||||
5. **Phase 5:** Deprecate old wrapper scripts
|
||||
6. **Phase 6:** Celebrate! 🎉
|
||||
|
||||
@@ -1,343 +0,0 @@
|
||||
# Card System Architecture Audit
|
||||
|
||||
**Date:** November 11, 2025
|
||||
**Author:** Senior Software Engineer
|
||||
**Status:** Critical Review
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
The current card UI system suffers from **excessive wrapper nesting**, **duplicated animation logic**, and **unclear separation of concerns**. While functional, it violates DRY principles and creates maintenance overhead. A refactor using composition and state machines is recommended.
|
||||
|
||||
---
|
||||
|
||||
## Current Architecture
|
||||
|
||||
### Component Hierarchy
|
||||
```
|
||||
CardDisplay (core visual renderer)
|
||||
└─ AlbumCard (album-specific wrapper)
|
||||
└─ FlippableCard (flip animation wrapper)
|
||||
└─ AlbumCardPlacementDraggable (drag/placement wrapper)
|
||||
└─ CardDraggable (generic drag wrapper)
|
||||
└─ CardDraggableVisual (visual for dragging)
|
||||
```
|
||||
|
||||
### Critical Issues
|
||||
|
||||
#### 1. **Wrapper Hell**
|
||||
- **5 layers of wrappers** around a single card display
|
||||
- Each wrapper duplicates transform/animation state management
|
||||
- Example: `FlippableCard`, `AlbumCard`, and `CardDraggable` all manage scales, positions, and parent tracking
|
||||
- **Code smell**: `AlbumCard.OnPointerClick()` forwards clicks to parent `FlippableCard` during reveal flow
|
||||
|
||||
#### 2. **Duplicated Animation Logic**
|
||||
Animation behaviors repeated across multiple components:
|
||||
|
||||
| Animation | FlippableCard | AlbumCard | CardDraggable | AlbumCardPlacementDraggable |
|
||||
|-----------|---------------|-----------|---------------|------------------------------|
|
||||
| Scale tweens | ✓ (hover, flip punch) | ✓ (enlarge/shrink) | - | - |
|
||||
| Position tweens | ✓ (idle hover) | - | ✓ (drag) | ✓ (snap to slot) |
|
||||
| Rotation tweens | ✓ (flip) | - | - | - |
|
||||
| Transform state tracking | ✓ (_originalPosition, _originalScale) | ✓ (_originalParent, _originalLocalPosition, _originalLocalRotation) | - | - |
|
||||
|
||||
**Impact**: ~150 lines of redundant tween/transform code across 4 files.
|
||||
|
||||
#### 3. **State Management Chaos**
|
||||
Multiple boolean flags tracking overlapping states:
|
||||
- `FlippableCard`: `_isFlipped`, `_isFlipping`, `_isWaitingForTap`, `_isClickable`, `_isNew`
|
||||
- `AlbumCard`: `_isEnlarged`, `_parentSlot != null` (implicit state)
|
||||
- `AlbumCardPlacementDraggable`: `_isRevealed`, `_isDragRevealing`, `_waitingForPlacementTap`, `_isHolding`
|
||||
|
||||
**Problems**:
|
||||
- No single source of truth for card state
|
||||
- Complex conditional logic: `if (_parentSlot == null) { forward to FlippableCard }`
|
||||
- State transitions scattered across 3+ classes
|
||||
|
||||
#### 4. **Unclear Responsibilities**
|
||||
- `CardDisplay`: Pure renderer ✓ (well-designed)
|
||||
- `AlbumCard`: Handles enlargement + slot parenting + click forwarding
|
||||
- `FlippableCard`: Handles flipping + hover animations + new/repeat UI + waiting for taps
|
||||
- `AlbumCardPlacementDraggable`: Handles drag + flip triggering + slot snapping
|
||||
|
||||
Each wrapper blurs the line between "what" (state) and "how" (presentation).
|
||||
|
||||
#### 5. **Event Callback Spaghetti**
|
||||
- 12+ events across components (`OnEnlargeRequested`, `OnShrinkRequested`, `OnCardRevealed`, `OnCardTappedAfterReveal`, `OnFlipStarted`, `OnClickedWhileInactive`, etc.)
|
||||
- Events chained: `AlbumCard.OnEnlargeRequested` → `AlbumViewPage` → reparent → `AlbumCard.EnlargeCard()`
|
||||
- Brittle: Changing card flow requires updating 3-4 components + page controllers
|
||||
|
||||
---
|
||||
|
||||
## Recommended Architecture
|
||||
|
||||
### Principles
|
||||
1. **Composition over inheritance/wrapping**
|
||||
2. **Single Responsibility**: Card visuals ≠ card behavior ≠ card state
|
||||
3. **State machines** for clear state transitions
|
||||
4. **Reusable animation system** instead of per-component tweens
|
||||
|
||||
### Proposed Design
|
||||
|
||||
Using **Pixelplacement StateMachine** (already in project) with **isolated state-owned visuals**:
|
||||
|
||||
```
|
||||
Card (root GameObject with RectTransform)
|
||||
├─ CardDisplay (always visible core visual)
|
||||
├─ CardContext (component - shared data/references)
|
||||
├─ CardAnimator (component - reusable animations)
|
||||
└─ CardStateMachine (AppleMachine component)
|
||||
├─ IdleState (GameObject + CardIdleState component)
|
||||
├─ FlippingState (GameObject + CardFlippingState component)
|
||||
│ └─ CardBackVisual (child GameObject - owned by this state)
|
||||
├─ RevealedState (GameObject + CardRevealedState component)
|
||||
├─ EnlargedNewState (GameObject + CardEnlargedNewState component)
|
||||
│ └─ NewCardBadge (child GameObject - owned by this state)
|
||||
├─ EnlargedRepeatState (GameObject + CardEnlargedRepeatState component)
|
||||
│ └─ ProgressBarUI (child GameObject - owned by this state)
|
||||
├─ DraggingState (GameObject + CardDraggingState component)
|
||||
└─ PlacedInSlotState (GameObject + CardPlacedInSlotState component)
|
||||
```
|
||||
|
||||
**Key Architecture Decisions:**
|
||||
|
||||
1. **State Isolation**: Each state is a **GameObject child** of the StateMachine. State-specific visual elements (CardBackVisual, NewCardBadge, ProgressBarUI) are **children of their state GameObject**. When a state activates, its children activate automatically.
|
||||
|
||||
2. **Transform Animation Target**: The root **Card.transform** is the primary animation target. All position/scale animations affect the root, and children inherit transforms naturally. States can also animate their own child visuals independently (e.g., rotating CardBackVisual during flip).
|
||||
|
||||
3. **Shared Resources via CardContext**: States access common components (CardDisplay, CardAnimator, StateMachine, CardData) through `CardContext`, avoiding tight coupling.
|
||||
|
||||
4. **Reusable Animations**: `CardAnimator` provides animation methods (PlayFlip, PlayEnlarge, etc.) that states invoke. No duplicate tween code across states.
|
||||
|
||||
5. **State Transitions**: States call `context.StateMachine.ChangeState("NextState")` to transition. Example flow:
|
||||
```
|
||||
IdleState [click] → FlippingState [flip complete] → EnlargedNewState [tap] → RevealedState
|
||||
```
|
||||
|
||||
#### Benefits
|
||||
- **60% less code**: Shared animation system, no wrapper components
|
||||
- **True state isolation**: Each state owns its visuals, no global visibility management
|
||||
- **Clear state transitions**: Explicit state machine flow instead of boolean flag soup
|
||||
- **Extensible**: Add new states without touching existing ones (e.g., `TradingState`, `BattleState`)
|
||||
- **Designer-friendly**: States are visible GameObjects in hierarchy, easy to understand
|
||||
- **No prefab nesting**: Single Card prefab with state children, not 5 nested prefabs
|
||||
|
||||
---
|
||||
|
||||
## Concrete Refactor Plan
|
||||
|
||||
### Phase 1: Implement State Machine Architecture ✅ COMPLETE
|
||||
|
||||
**Created Files:**
|
||||
- `CardContext.cs` - Shared context component
|
||||
- `CardAnimator.cs` - Reusable animation controller
|
||||
- `CardAnimationConfig.cs` - ScriptableObject for animation settings
|
||||
- `States/CardIdleState.cs` - Idle state with hover
|
||||
- `States/CardFlippingState.cs` - Flip animation state (owns CardBackVisual)
|
||||
- `States/CardRevealedState.cs` - Revealed/interactable state
|
||||
- `States/CardEnlargedNewState.cs` - Enlarged new card state (owns NewCardBadge)
|
||||
- `States/CardEnlargedRepeatState.cs` - Enlarged repeat state (owns ProgressBarUI)
|
||||
|
||||
**Example State Implementation:**
|
||||
```csharp
|
||||
public class CardFlippingState : AppleState
|
||||
{
|
||||
[SerializeField] private GameObject cardBackVisual; // State owns this visual
|
||||
private CardContext _context;
|
||||
|
||||
void Awake() => _context = GetComponentInParent<CardContext>();
|
||||
|
||||
public override void OnEnterState()
|
||||
{
|
||||
// Show card back (owned by this state)
|
||||
cardBackVisual.SetActive(true);
|
||||
_context.CardDisplay.gameObject.SetActive(false);
|
||||
|
||||
// Use shared animator
|
||||
_context.Animator.PlayFlip(
|
||||
cardBackVisual.transform,
|
||||
_context.CardDisplay.transform,
|
||||
onComplete: () => {
|
||||
// Transition to next state
|
||||
string nextState = _context.IsNewCard ? "EnlargedNewState" : "RevealedState";
|
||||
_context.StateMachine.ChangeState(nextState);
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
void OnDisable()
|
||||
{
|
||||
// Hide card back when leaving state
|
||||
cardBackVisual.SetActive(false);
|
||||
_context.CardDisplay.gameObject.SetActive(true);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Prefab Structure:**
|
||||
```
|
||||
Card.prefab
|
||||
├─ CardDisplay
|
||||
├─ CardContext (component)
|
||||
├─ CardAnimator (component)
|
||||
└─ CardStateMachine (AppleMachine)
|
||||
├─ IdleState/
|
||||
├─ FlippingState/
|
||||
│ └─ CardBackVisual (Image)
|
||||
├─ RevealedState/
|
||||
├─ EnlargedNewState/
|
||||
│ └─ NewCardBadge (GameObject)
|
||||
└─ EnlargedRepeatState/
|
||||
└─ ProgressBarUI (GameObject with Image/Text)
|
||||
```
|
||||
|
||||
**Impact**: Foundation complete. States are isolated, visuals are state-owned, animations are shared.
|
||||
|
||||
### Phase 2: Create Remaining States (Low Risk)
|
||||
|
||||
**Additional states needed:**
|
||||
- `CardDraggingState.cs` - Handles drag interaction for album placement
|
||||
- `CardPlacedInSlotState.cs` - Card placed in album slot, handles enlarge on click
|
||||
- `CardAlbumEnlargedState.cs` - Enlarged view when clicking card in album
|
||||
|
||||
**Example - Album Placed State:**
|
||||
```csharp
|
||||
public class CardPlacedInSlotState : AppleState, IPointerClickHandler
|
||||
{
|
||||
private CardContext _context;
|
||||
private AlbumCardSlot _parentSlot;
|
||||
|
||||
public void SetParentSlot(AlbumCardSlot slot) => _parentSlot = slot;
|
||||
|
||||
public void OnPointerClick(PointerEventData eventData)
|
||||
{
|
||||
_context.StateMachine.ChangeState("AlbumEnlargedState");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Time**: 2-3 days
|
||||
|
||||
### Phase 3: Migrate Existing Prefabs (Medium Risk)
|
||||
|
||||
**Steps:**
|
||||
1. Create new `Card.prefab` with state machine structure
|
||||
2. Build migration tool to convert old prefabs → new structure:
|
||||
- Copy CardDisplay references
|
||||
- Setup CardContext with data
|
||||
- Create state GameObjects
|
||||
3. Update scenes one at a time:
|
||||
- Replace `FlippableCard` spawns with `Card` spawns
|
||||
- Update `BoosterOpeningPage` to use new Card system
|
||||
- Update `AlbumViewPage` to use new Card system
|
||||
4. Remove old wrapper scripts once migration complete
|
||||
|
||||
**Migration Helper Script:**
|
||||
```csharp
|
||||
// Editor tool to convert old card prefabs
|
||||
[MenuItem("AppleHills/Convert Old Card to New Card")]
|
||||
static void ConvertCard()
|
||||
{
|
||||
// Find old FlippableCard
|
||||
var oldCard = Selection.activeGameObject.GetComponent<FlippableCard>();
|
||||
// Extract data, create new Card with states
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**Time**: 1-2 weeks (includes testing)
|
||||
|
||||
---
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
### Option A: Incremental (Recommended)
|
||||
1. Create `CardAnimator` alongside existing code (2-3 days)
|
||||
2. Refactor one wrapper at a time to use `CardAnimator` (1 week)
|
||||
3. Test each step with existing scenes
|
||||
4. Introduce state machine once animations are consolidated (3-5 days)
|
||||
5. Collapse wrappers last, update prefabs (2-3 days)
|
||||
|
||||
**Total**: ~3 weeks, low risk
|
||||
|
||||
### Option B: Parallel Track
|
||||
1. Build new `Card` system in separate namespace (1 week)
|
||||
2. Create migration tools to convert old prefabs → new prefabs (2-3 days)
|
||||
3. Switch one scene at a time (1 week)
|
||||
4. Delete old system once migration complete
|
||||
|
||||
**Total**: ~3 weeks, higher risk but cleaner result
|
||||
|
||||
---
|
||||
|
||||
## Immediate Wins (Low-Hanging Fruit)
|
||||
|
||||
Even without full refactor, these changes reduce pain:
|
||||
|
||||
### 1. Extract Common Transform Tracking
|
||||
```csharp
|
||||
// Assets/Scripts/UI/CardSystem/TransformMemento.cs
|
||||
public class TransformMemento {
|
||||
public Vector3 LocalPosition;
|
||||
public Quaternion LocalRotation;
|
||||
public Vector3 LocalScale;
|
||||
public Transform Parent;
|
||||
|
||||
public static TransformMemento Capture(Transform t) { ... }
|
||||
public void Restore(Transform t) { ... }
|
||||
}
|
||||
```
|
||||
|
||||
**Usage**: Replace 8+ `_originalX` fields across components with single `TransformMemento`.
|
||||
|
||||
### 2. Shared Animation Config ScriptableObject
|
||||
```csharp
|
||||
// Assets/Scripts/UI/CardSystem/CardAnimationConfig.asset
|
||||
[CreateAssetMenu]
|
||||
public class CardAnimationConfig : ScriptableObject {
|
||||
public float flipDuration = 0.6f;
|
||||
public float enlargedScale = 2.5f;
|
||||
public float hoverHeight = 10f;
|
||||
// etc.
|
||||
}
|
||||
```
|
||||
|
||||
**Impact**: Tweak all card animations from one asset instead of searching 5 prefabs.
|
||||
|
||||
### 3. Document State Transitions
|
||||
Add state diagram to `FlippableCard.cs`:
|
||||
```csharp
|
||||
/// State Flow:
|
||||
/// Unflipped → [Click] → Flipping → Revealed → [IsNew] → EnlargedNew → [Tap] → Revealed
|
||||
/// → [IsRepeat] → ShowingProgress → Revealed
|
||||
/// → [Tap during drag] → PlacementMode → PlacedInSlot
|
||||
```
|
||||
|
||||
**Impact**: Future devs understand flow without debugging.
|
||||
|
||||
---
|
||||
|
||||
## Metrics
|
||||
|
||||
| Metric | Current | After Refactor |
|
||||
|--------|---------|----------------|
|
||||
| Lines of code (card UI) | ~1,200 | ~500 |
|
||||
| Animation logic locations | 4 files | 1 file |
|
||||
| State tracking booleans | 12+ | 0 (enum-based) |
|
||||
| Prefab nesting depth | 5 layers | 1 layer |
|
||||
| Event callback chains | 12 events | ~3-4 events |
|
||||
| Time to add new card state | 4-6 hours | ~30 min |
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
The current system works but is **expensive to maintain and extend**. The root cause is **wrapping components instead of composing behavior**.
|
||||
|
||||
**Recommendation**: Approve **Phase 1 (Animation System)** immediately as it has zero breaking changes and reduces code by 20%. Schedule **Phase 2-3 (State Machine + Wrapper Collapse)** for next sprint based on team bandwidth.
|
||||
|
||||
**Risk Assessment**: Medium. Prefab changes require thorough testing, but state machine pattern is battle-tested.
|
||||
|
||||
**ROI**: High. Estimated 70% reduction in time to add new card interactions (e.g., trading, upgrading, battling).
|
||||
|
||||
@@ -1,408 +0,0 @@
|
||||
# Card State Machine Implementation Summary
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
**Isolated State Pattern** using Pixelplacement StateMachine:
|
||||
|
||||
```
|
||||
Card (RectTransform - primary animation target)
|
||||
├─ CardDisplay (always visible - shows card front)
|
||||
├─ CardContext (shared references + events)
|
||||
├─ CardAnimator (reusable animations)
|
||||
└─ CardStateMachine (AppleMachine)
|
||||
├─ IdleState/
|
||||
│ └─ CardBackVisual ← State owns this
|
||||
├─ FlippingState/
|
||||
│ └─ CardBackVisual ← State owns this
|
||||
├─ RevealedState/
|
||||
│ ├─ NewCardIdleBadge ← State owns this
|
||||
│ └─ RepeatCardIdleBadge ← State owns this
|
||||
├─ EnlargedNewState/
|
||||
│ └─ NewCardBadge ← State owns this
|
||||
├─ EnlargedRepeatState/
|
||||
│ ├─ RepeatText ← State owns this
|
||||
│ └─ ProgressBarContainer/
|
||||
│ └─ ProgressBarUI (prefab with ProgressBarController)
|
||||
├─ DraggingState/ (no child visuals)
|
||||
├─ PlacedInSlotState/ (no child visuals)
|
||||
└─ AlbumEnlargedState/ (no child visuals)
|
||||
```
|
||||
|
||||
## State Flow Diagrams
|
||||
|
||||
### **Booster Opening Flow:**
|
||||
↓ [player clicks]
|
||||
2. FlippingState (flip animation + scale punch)
|
||||
1. IdleState (card back in assigned slot, hover enabled)
|
||||
↓ [player clicks - flip animation plays within IdleState]
|
||||
3a. IF NEW CARD:
|
||||
↓ [determine path based on card status]
|
||||
|
||||
2a. IF NEW CARD:
|
||||
3b. IF LEGENDARY REPEAT:
|
||||
→ [tap] → Fires OnCardDismissed
|
||||
→ Shrink → RevealedState
|
||||
3c. IF REPEAT (won't upgrade, e.g., 2/5):
|
||||
2b. IF LEGENDARY REPEAT:
|
||||
→ Skip enlarge → RevealedState (can't upgrade)
|
||||
|
||||
2c. IF REPEAT (won't upgrade, e.g., 2/5):
|
||||
→ EnlargedRepeatState
|
||||
3d. IF REPEAT (WILL upgrade, e.g., 5/5):
|
||||
→ [tap] → Fires OnCardDismissed
|
||||
→ Shrink → RevealedState
|
||||
|
||||
2d. IF REPEAT (WILL upgrade, e.g., 5/5):
|
||||
→ EnlargedRepeatState
|
||||
→ Show progress bar (5/5) + blink
|
||||
→ AUTO-UPGRADE (no tap needed)
|
||||
→ Fires OnUpgradeTriggered
|
||||
→ Update inventory
|
||||
→ Check if new/repeat at higher rarity:
|
||||
IF NEW at higher: → EnlargedNewState (higher rarity)
|
||||
4. RevealedState (normal size, waiting)
|
||||
→ [tap] → Fires OnCardDismissed
|
||||
→ Shrink → RevealedState
|
||||
|
||||
5. [When all cards complete]
|
||||
→ Fires OnCardInteractionComplete
|
||||
→ Waits for all 3 cards to finish
|
||||
|
||||
4. [When all cards complete]
|
||||
→ BoosterOpeningPage animates cards to album → Destroy
|
||||
```
|
||||
|
||||
### **Album Placement Flow:**
|
||||
```
|
||||
1. IdleState (card back in corner, hover enabled)
|
||||
↓ [player clicks]
|
||||
2. FlippingState (reveals which card it is)
|
||||
→ OnFlipComplete
|
||||
↓
|
||||
3. RevealedState
|
||||
→ OnCardInteractionComplete
|
||||
↓ [player drags]
|
||||
4. DraggingState (scaled up during drag)
|
||||
↓ [drop in slot]
|
||||
5. PlacedInSlotState (in album permanently)
|
||||
↓ [player clicks]
|
||||
6. AlbumEnlargedState
|
||||
→ Fires OnEnlargeRequested (page shows backdrop, reparents)
|
||||
↓ [player taps]
|
||||
→ Fires OnShrinkRequested (page prepares)
|
||||
→ Shrink animation
|
||||
↓
|
||||
5. PlacedInSlotState (back in slot)
|
||||
```
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
### 1. State-Owned Visuals
|
||||
- State-specific GameObjects (CardBackVisual, NewCardBadge, etc.) are **children of their state GameObject**
|
||||
- When state activates → children activate automatically
|
||||
- When state deactivates → children deactivate automatically
|
||||
- **No manual visibility management needed!**
|
||||
|
||||
### 2. Transform Animation
|
||||
- **Root Card.transform** is animated for position/scale (affects all children via Unity hierarchy)
|
||||
- **State child visuals** can be animated independently (e.g., rotating CardBackVisual during flip)
|
||||
- States decide WHAT to animate, CardAnimator provides HOW
|
||||
|
||||
### 3. Shared Resources via CardContext
|
||||
```csharp
|
||||
public class CardContext : MonoBehaviour
|
||||
{
|
||||
// Component references
|
||||
public CardDisplay CardDisplay { get; }
|
||||
public CardAnimator Animator { get; }
|
||||
public AppleMachine StateMachine { get; }
|
||||
public Transform RootTransform { get; }
|
||||
|
||||
// Card data
|
||||
public CardData CardData { get; }
|
||||
public bool IsNewCard { get; set; }
|
||||
public int RepeatCardCount { get; set; }
|
||||
public bool IsClickable { get; set; } // Prevents multi-flip in booster opening
|
||||
|
||||
// Events for external coordination (BoosterOpeningPage)
|
||||
public event Action<CardContext> OnFlipComplete;
|
||||
public event Action<CardContext> OnCardDismissed;
|
||||
public event Action<CardContext> OnCardInteractionComplete;
|
||||
public event Action<CardContext> OnUpgradeTriggered;
|
||||
|
||||
// Helper methods
|
||||
public void FireFlipComplete();
|
||||
public void FireCardDismissed();
|
||||
public void FireCardInteractionComplete();
|
||||
public void FireUpgradeTriggered();
|
||||
}
|
||||
```
|
||||
|
||||
### 4. State Transitions
|
||||
States explicitly transition via `_context.StateMachine.ChangeState("StateName")`
|
||||
|
||||
Example:
|
||||
```csharp
|
||||
// In CardFlippingState.OnFlipComplete():
|
||||
if (_context.IsNewCard)
|
||||
_context.StateMachine.ChangeState("EnlargedNewState");
|
||||
else if (_context.RepeatCardCount > 0)
|
||||
_context.StateMachine.ChangeState("EnlargedRepeatState");
|
||||
```
|
||||
|
||||
### 5. Progress Bar Architecture
|
||||
**ProgressBarController Component:**
|
||||
- Auto-detects child Image elements (5 images in GridLayout)
|
||||
- Fills from bottom to top (element[0] = bottom)
|
||||
- Blinks newest element with configurable timing
|
||||
- Callback when animation completes
|
||||
|
||||
**Usage:**
|
||||
```csharp
|
||||
progressBar.ShowProgress(currentCount, maxCount, OnProgressComplete);
|
||||
```
|
||||
|
||||
## Files Created
|
||||
|
||||
### **Core Components:**
|
||||
- `StateMachine/CardContext.cs` - Shared context + events
|
||||
- `StateMachine/CardAnimator.cs` - Reusable animation methods (enlarge, shrink, flip, idle hover, etc.)
|
||||
- `ProgressBarController.cs` - Progress bar UI controller with blink animation
|
||||
|
||||
### **Settings:**
|
||||
- `Core/Settings/CardSystemSettings.cs` - ScriptableObject for all card animation timings
|
||||
- `Core/Settings/ICardSystemSettings.cs` - Interface for settings access
|
||||
|
||||
### **State Implementations:**
|
||||
- `States/CardIdleState.cs` - Owns CardBackVisual, idle hover, click to flip (with click blocking)
|
||||
- `States/CardFlippingState.cs` - Owns CardBackVisual, flip animation, Legendary shortcut
|
||||
- `States/CardRevealedState.cs` - Owns NewCardIdleBadge + RepeatCardIdleBadge, fires OnCardInteractionComplete
|
||||
- `States/CardEnlargedNewState.cs` - Owns NewCardBadge, tap to shrink
|
||||
- `States/CardEnlargedRepeatState.cs` - Owns RepeatText + ProgressBarUI, auto-upgrade logic
|
||||
- `States/CardDraggingState.cs` - Drag handling for album placement
|
||||
- `States/CardPlacedInSlotState.cs` - In album slot, click to enlarge
|
||||
- `States/CardAlbumEnlargedState.cs` - Enlarged from album, tap to shrink
|
||||
|
||||
## Prefab Assembly Instructions
|
||||
|
||||
### **Card Prefab Hierarchy:**
|
||||
```
|
||||
Card (RectTransform)
|
||||
├─ CardDisplay (existing prefab)
|
||||
├─ CardContext (component)
|
||||
├─ FlippingState (CardFlippingState component)
|
||||
│ └─ CardBackVisual (Image)
|
||||
├─ CardAnimator (component)
|
||||
└─ CardStateMachine (AppleMachine)
|
||||
├─ IdleState (CardIdleState component)
|
||||
│ └─ CardBackVisual (Image)
|
||||
├─ RevealedState (CardRevealedState component)
|
||||
│ ├─ NewCardIdleBadge (Image/Text - "NEW!")
|
||||
│ └─ RepeatCardIdleBadge (Image/Text - "REPEAT")
|
||||
│ └─ ProgressBarContainer (GameObject)
|
||||
│ └─ ProgressBarUI (prefab instance)
|
||||
│ └─ NewCardBadge (Image/Text - "NEW CARD")
|
||||
├─ EnlargedRepeatState (CardEnlargedRepeatState component)
|
||||
│ ├─ RepeatText (Image/Text - "REPEAT CARD")
|
||||
│ └─ ProgressBarUI (ProgressBarController component + 5 Image children)
|
||||
├─ DraggingState (CardDraggingState component)
|
||||
ProgressBarUI
|
||||
├─ GridLayoutGroup (1 column, 5 rows, "Lower Right" corner start)
|
||||
├─ ProgressElement1 (Image)
|
||||
|
||||
### **ProgressBarUI Prefab:**
|
||||
```
|
||||
ProgressBarUI (GameObject with ProgressBarController component)
|
||||
└─ ProgressElement5 (Image)
|
||||
├─ VerticalLayoutGroup (Reverse Arrangement enabled)
|
||||
└─ Children (5 Images, auto-detected):
|
||||
├─ ProgressElement1 (Image) - First child = 1/5
|
||||
├─ ProgressElement2 (Image)
|
||||
├─ ProgressElement3 (Image)
|
||||
├─ ProgressElement4 (Image)
|
||||
└─ ProgressElement5 (Image) - Last child = 5/5
|
||||
```
|
||||
|
||||
### **Component References to Assign:**
|
||||
**CardContext:**
|
||||
- cardDisplay → CardDisplay component
|
||||
- cardAnimator → CardAnimator component
|
||||
|
||||
**CardIdleState:**
|
||||
- cardBackVisual → CardBackVisual child GameObject
|
||||
|
||||
**CardFlippingState:**
|
||||
- cardBackVisual → CardBackVisual child GameObject
|
||||
|
||||
**CardRevealedState:**
|
||||
- progressBarContainer → ProgressBarContainer child GameObject
|
||||
- progressBar → ProgressBarController component (on ProgressBarUI prefab)
|
||||
- repeatCardIdleBadge → RepeatCardIdleBadge child GameObject
|
||||
|
||||
**CardEnlargedNewState:**
|
||||
- newCardBadge → NewCardBadge child GameObject
|
||||
|
||||
**CardEnlargedRepeatState:**
|
||||
- progressBar → ProgressBarController component (on ProgressBarUI child GameObject)
|
||||
- repeatText → RepeatText child GameObject
|
||||
|
||||
## Integration with BoosterOpeningPage
|
||||
|
||||
```csharp
|
||||
// When spawning cards:
|
||||
Card card = Instantiate(cardPrefab);
|
||||
CardContext context = card.GetComponent<CardContext>();
|
||||
|
||||
// Setup card data
|
||||
context.SetupCard(cardData, isNew: isNewCard, repeatCount: ownedCount);
|
||||
|
||||
// All cards start clickable
|
||||
context.IsClickable = true;
|
||||
|
||||
// Subscribe to events
|
||||
context.OnFlipComplete += OnCardFlipComplete;
|
||||
context.OnCardDismissed += OnCardDismissed;
|
||||
context.OnCardInteractionComplete += OnCardInteractionComplete;
|
||||
context.OnUpgradeTriggered += OnCardUpgraded;
|
||||
|
||||
// Start in IdleState
|
||||
context.StateMachine.ChangeState("IdleState");
|
||||
|
||||
// When a card starts flipping, block all others
|
||||
private void OnCardFlipComplete(CardContext flippingCard)
|
||||
{
|
||||
// Disable all cards to prevent multi-flip
|
||||
foreach (CardContext card in _allCards)
|
||||
{
|
||||
card.IsClickable = false;
|
||||
}
|
||||
}
|
||||
|
||||
// Track completion
|
||||
private void OnCardInteractionComplete(CardContext card)
|
||||
{
|
||||
_cardsCompletedInteraction++;
|
||||
|
||||
if (_cardsCompletedInteraction == 3)
|
||||
{
|
||||
AnimateCardsToAlbum(); // All cards revealed, animate to album
|
||||
}
|
||||
else
|
||||
{
|
||||
// Re-enable unflipped cards
|
||||
foreach (CardContext c in _allCards)
|
||||
{
|
||||
if (c.StateMachine.CurrentState.name == "IdleState")
|
||||
{
|
||||
c.IsClickable = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Benefits vs Old System
|
||||
|
||||
| Aspect | Old System | New System |
|
||||
|--------|-----------|------------|
|
||||
| Components per card | FlippableCard + AlbumCard + wrappers | 1 Card + states |
|
||||
| Animation code duplication | ~200 lines across 5 files | 0 (shared CardAnimator) |
|
||||
| State tracking | 12+ boolean flags (_isFlipped, _isFlipping, _isWaitingForTap, etc.) | 1 active state name |
|
||||
| Visual element management | Manual SetActive() in 8+ places | Automatic via state activation |
|
||||
| Adding new behaviors | Modify 3-4 components + events | Add 1 new state GameObject |
|
||||
| Prefab nesting | FlippableCard → AlbumCard → CardDisplay (5 layers) | Card → States (flat hierarchy) |
|
||||
| Debugging state | Check 12 booleans across files | Look at active state name in inspector |
|
||||
| Progress bar logic | 50 lines in FlippableCard.ShowProgressBar() | Isolated in ProgressBarController |
|
||||
| Upgrade logic | TriggerUpgradeTransition (80 lines in FlippableCard) | TriggerUpgrade (isolated in CardEnlargedRepeatState) |
|
||||
| Event coordination | 4 events on FlippableCard, 2 on AlbumCard | 4 events on CardContext (centralized) |
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] Booster opening: NEW card shows badge → tap → shrinks → shows NEW idle badge
|
||||
- [ ] Booster opening: REPEAT card (2/5) shows REPEAT text + progress → blink → tap → shrinks → shows REPEAT idle badge
|
||||
- [ ] Booster opening: REPEAT card (5/5) auto-upgrades → shows NEW at higher rarity
|
||||
- [ ] Booster opening: Legendary repeat skips enlarge
|
||||
- [ ] Booster opening: Click blocking prevents multi-flip
|
||||
- [ ] Booster opening: All 3 cards complete → animate to album
|
||||
- [ ] Album placement: Card in corner → click → reveals → drag → place in slot
|
||||
- [ ] Album placement: Card in slot → click → enlarges → tap → shrinks back
|
||||
- [ ] Cascading upgrades (Common → Uncommon → Rare in one reveal)
|
||||
- [ ] Progress bar shows correctly (1/5, 2/5, 3/5, 4/5, 5/5)
|
||||
- [ ] Progress bar blinks newest element
|
||||
- [ ] Idle hover animation works in both flows
|
||||
- [ ] Hover scale works on pointer enter/exit
|
||||
|
||||
## Integration Work Remaining
|
||||
|
||||
1. Update BoosterOpeningPage to use new Card prefab instead of FlippableCard
|
||||
2. Update AlbumViewPage to use new Card prefab instead of AlbumCard
|
||||
3. Migrate album placement drag/drop to use DraggingState
|
||||
4. Remove old FlippableCard.cs and AlbumCard.cs after migration
|
||||
5. **(Optional)** Add Jiggle() animation to CardAnimator for clicking inactive cards
|
||||
|
||||
## Migration Path
|
||||
|
||||
**Phase 1: Side-by-side (Current)**
|
||||
- New state machine exists alongside old FlippableCard/AlbumCard
|
||||
- Can test new system without breaking existing functionality
|
||||
|
||||
**Phase 2: Booster Opening Migration**
|
||||
- Update BoosterOpeningPage to spawn new Card prefab
|
||||
- Remove FlippableCard references
|
||||
- Test all booster flows
|
||||
|
||||
**Phase 3: Album Migration**
|
||||
- Update AlbumViewPage to spawn new Card prefab
|
||||
- Remove AlbumCard references
|
||||
- Test album placement and enlarge
|
||||
|
||||
**Phase 4: Cleanup**
|
||||
- Delete FlippableCard.cs
|
||||
- Delete AlbumCard.cs
|
||||
- Delete old wrapper components
|
||||
- Clean up unused prefab variants
|
||||
|
||||
## Example: Adding New Card Behavior
|
||||
|
||||
**Scenario:** Add a "Trading" state where card shows trade UI?
|
||||
|
||||
**Old system:**
|
||||
1. Modify FlippableCard.cs (add boolean, methods, events)
|
||||
2. Modify AlbumCard.cs (add pass-through logic)
|
||||
3. Update 3-4 wrapper components
|
||||
4. Add new events and subscriptions
|
||||
5. Manually manage trade UI visibility
|
||||
|
||||
**New system:**
|
||||
1. Create `CardTradingState.cs`:
|
||||
```csharp
|
||||
public class CardTradingState : AppleState
|
||||
{
|
||||
[SerializeField] private GameObject tradeUI;
|
||||
|
||||
public override void OnEnterState()
|
||||
{
|
||||
// tradeUI automatically activates with state!
|
||||
}
|
||||
}
|
||||
```
|
||||
2. Add TradingState GameObject under CardStateMachine
|
||||
3. Add trade UI as child of TradingState
|
||||
4. Call `ChangeState("TradingState")` from wherever needed
|
||||
|
||||
**Done! Zero other files modified.**
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
The new state machine implementation successfully replicates all core FlippableCard/AlbumCard functionality with:
|
||||
- ✅ Cleaner architecture (state pattern vs boolean soup)
|
||||
- ✅ Less code duplication (shared CardAnimator)
|
||||
- ✅ Easier debugging (visible state names)
|
||||
- ✅ Simpler extension (add states vs modify monoliths)
|
||||
- ✅ Better separation of concerns (each state owns its visuals)
|
||||
|
||||
**Status: Core implementation complete, ready for prefab assembly and integration testing.**
|
||||
|
||||
|
||||
@@ -1,303 +0,0 @@
|
||||
# Card Test Scene Quick Reference
|
||||
|
||||
**Quick lookup for card test scene usage - no slot functionality**
|
||||
|
||||
**Last Updated**: November 12, 2025
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
Test scene for card effects and dragging. Cards snap back to spawn point when released - **NO SLOTTING**.
|
||||
|
||||
---
|
||||
|
||||
## Quick Setup Checklist
|
||||
|
||||
- [ ] Create scene with Canvas + EventSystem
|
||||
- [ ] Add CardTestController GameObject
|
||||
- [ ] Add Card prefab to scene
|
||||
- [ ] Create UI buttons panel
|
||||
- [ ] Wire up all button onClick events
|
||||
- [ ] Assign all inspector references
|
||||
- [ ] Create test CardData ScriptableObject
|
||||
|
||||
---
|
||||
|
||||
## Button Quick Reference
|
||||
|
||||
### Flow Simulation (Most Used)
|
||||
```
|
||||
New Card Flow → SimulateNewCardFlow()
|
||||
Repeat Card Flow → SimulateRepeatCardFlow()
|
||||
Upgrade Flow → SimulateUpgradeFlow()
|
||||
Test Drag & Snap → TestDragAndSnap() ← NEW: Test dragging
|
||||
```
|
||||
|
||||
### State Transitions
|
||||
```
|
||||
To Idle State → TransitionToIdleState()
|
||||
To Revealed State → TransitionToRevealedState()
|
||||
To Enlarged New → TransitionToEnlargedNewState()
|
||||
To Enlarged Repeat → TransitionToEnlargedRepeatState()
|
||||
To Dragging State → TransitionToDraggingState()
|
||||
To Album Enlarged → TransitionToAlbumEnlargedState()
|
||||
```
|
||||
|
||||
### Animation Tests
|
||||
```
|
||||
Play Flip → PlayFlipAnimation()
|
||||
Play Enlarge → PlayEnlargeAnimation()
|
||||
Play Shrink → PlayShrinkAnimation()
|
||||
Start Idle Hover → StartIdleHoverAnimation()
|
||||
Stop Idle Hover → StopIdleHoverAnimation()
|
||||
```
|
||||
|
||||
### Utilities
|
||||
```
|
||||
Reset Card Position → ResetCardPosition()
|
||||
Clear Event Log → ClearEventLog()
|
||||
Apply Setup → ApplyCardSetup()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Inspector Fields
|
||||
|
||||
### Required References
|
||||
```
|
||||
Test Card → Card prefab instance
|
||||
Test Card Data → CardData ScriptableObject
|
||||
```
|
||||
|
||||
### UI References
|
||||
```
|
||||
eventLogText → TextMeshProUGUI (scrollable)
|
||||
currentStateText → TextMeshProUGUI
|
||||
isNewToggle → Toggle
|
||||
repeatCountSlider → Slider (0-5)
|
||||
repeatCountLabel → TextMeshProUGUI
|
||||
rarityDropdown → TMP_Dropdown
|
||||
isClickableToggle → Toggle
|
||||
```
|
||||
|
||||
### REMOVED References (No Longer Used)
|
||||
```
|
||||
❌ slot1 → REMOVED
|
||||
❌ slot2 → REMOVED
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Test Flows
|
||||
|
||||
### 1. Test New Card Reveal
|
||||
```
|
||||
1. Click "New Card Flow"
|
||||
2. Click the card
|
||||
3. Watch flip → enlarge → idle
|
||||
4. Check event log
|
||||
```
|
||||
|
||||
### 2. Test Repeat Card (3/5)
|
||||
```
|
||||
1. Set slider to 3
|
||||
2. Click "Repeat Card Flow"
|
||||
3. Click the card
|
||||
4. See "3/5" indicator
|
||||
```
|
||||
|
||||
### 3. Test Drag Behavior ⭐ NEW
|
||||
```
|
||||
1. Click "Test Drag & Snap"
|
||||
2. Drag card anywhere
|
||||
3. Release mouse/touch
|
||||
4. Card snaps back to spawn
|
||||
5. Card returns to Idle state
|
||||
```
|
||||
|
||||
### 4. Test Upgrade
|
||||
```
|
||||
1. Click "Upgrade Flow"
|
||||
2. Click the card
|
||||
3. Watch upgrade effect
|
||||
4. Check event log for upgrade triggered
|
||||
```
|
||||
|
||||
### 5. Manual State Testing
|
||||
```
|
||||
1. Click "To [State]" button
|
||||
2. Observe card behavior
|
||||
3. Check current state display
|
||||
4. Review event log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Expected Drag Behavior
|
||||
|
||||
### ✅ What Happens
|
||||
- Card scales up during drag
|
||||
- Card follows cursor smoothly
|
||||
- Card snaps back to spawn on release
|
||||
- Event log shows drag start/end
|
||||
- Card returns to Idle state
|
||||
|
||||
### ❌ What Does NOT Happen
|
||||
- Card does NOT snap to slots
|
||||
- Card does NOT stay where dropped
|
||||
- Card does NOT interact with album
|
||||
- No slot validation occurs
|
||||
|
||||
---
|
||||
|
||||
## Event Log Messages
|
||||
|
||||
Common messages you'll see:
|
||||
```
|
||||
[0.00s] Card Test Scene Initialized
|
||||
[1.23s] Simulating NEW CARD flow - click card to flip
|
||||
[2.45s] Event: OnFlipComplete - IsNew=True, RepeatCount=0
|
||||
[3.67s] Transitioned to IdleState
|
||||
[4.89s] Event: OnDragStarted - Card is being dragged
|
||||
[5.10s] Event: OnDragEnded - Snapping card back to spawn point
|
||||
[5.11s] Transitioned to IdleState
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## State Machine States
|
||||
|
||||
Available states (use "To [State]" buttons):
|
||||
1. **IdleState** - Face down, clickable, can start drag
|
||||
2. **RevealedState** - Face up, can be dragged
|
||||
3. **EnlargedNewState** - Enlarged, showing new card
|
||||
4. **EnlargedRepeatState** - Enlarged, showing repeat count
|
||||
5. **DraggingState** - Being dragged (scaled up)
|
||||
6. **AlbumEnlargedState** - Enlarged in album view
|
||||
7. ~~PlacedInSlotState~~ - **NOT USED IN TEST SCENE**
|
||||
|
||||
---
|
||||
|
||||
## Configuration Controls
|
||||
|
||||
### Is New Toggle
|
||||
- ON = Card is new (first time seen)
|
||||
- OFF = Card is repeat
|
||||
|
||||
### Repeat Count Slider
|
||||
- Range: 0-5
|
||||
- 5 triggers upgrade automatically
|
||||
|
||||
### Rarity Dropdown
|
||||
- Common, Uncommon, Rare, Epic, Legendary
|
||||
- Changes test card's rarity
|
||||
|
||||
### Is Clickable Toggle
|
||||
- ON = Card responds to clicks
|
||||
- OFF = Card ignores clicks
|
||||
|
||||
**Click "Apply Setup" after changing these values**
|
||||
|
||||
---
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
None implemented yet - use buttons for all actions.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Quick Fixes
|
||||
|
||||
### Card Won't Drag
|
||||
```
|
||||
1. Click "Test Drag & Snap" button
|
||||
2. Verify EventSystem in scene
|
||||
3. Check Canvas has GraphicRaycaster
|
||||
```
|
||||
|
||||
### Card Won't Snap Back
|
||||
```
|
||||
1. Check CardTestController is in scene
|
||||
2. Verify Awake() subscribed to OnDragEnded
|
||||
3. Check _originalCardPosition is set
|
||||
```
|
||||
|
||||
### Buttons Don't Work
|
||||
```
|
||||
1. Verify onClick events are wired
|
||||
2. Check method names (case-sensitive)
|
||||
3. Ensure CardTestController reference assigned
|
||||
```
|
||||
|
||||
### No Event Log
|
||||
```
|
||||
1. Assign eventLogText field
|
||||
2. Check TextMeshProUGUI component exists
|
||||
3. Look in Unity Console for [CardTest] logs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What Changed (Nov 12, 2025)
|
||||
|
||||
### Removed
|
||||
- ❌ `slot1` and `slot2` fields
|
||||
- ❌ `TransitionToPlacedInSlotState()` method
|
||||
- ❌ `SimulateAlbumPlacementFlow()` method
|
||||
- ❌ All slot-related logic
|
||||
|
||||
### Added
|
||||
- ✅ `TestDragAndSnap()` method
|
||||
- ✅ `OnCardDragStarted()` handler
|
||||
- ✅ `OnCardDragEnded()` handler with snap-back logic
|
||||
- ✅ Drag event subscription in `Awake()`
|
||||
- ✅ Drag event unsubscription in `OnDestroy()`
|
||||
|
||||
### Behavior Changes
|
||||
- Cards **always** snap back to spawn point when drag ends
|
||||
- No slot validation or placement
|
||||
- Automatic return to Idle state after drag
|
||||
- Event logging for drag start/end
|
||||
|
||||
---
|
||||
|
||||
## Performance Notes
|
||||
|
||||
- Event log keeps last 20 messages only
|
||||
- State display updates every 0.5 seconds
|
||||
- No performance concerns for single card testing
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Full Setup Guide**: `docs/cards_wip/card_test_scene_setup_guide.md`
|
||||
- **State Machine Reference**: `docs/cards_wip/card_state_machine_quick_reference.md`
|
||||
- **Card System Overview**: `docs/cards_wip/README_CARD_SYSTEM.md`
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
Before moving to production:
|
||||
- [ ] New card flow works (flip animation)
|
||||
- [ ] Repeat card flow shows correct count
|
||||
- [ ] Upgrade flow triggers at 5/5
|
||||
- [ ] Drag & snap works smoothly
|
||||
- [ ] Card scales during drag
|
||||
- [ ] Card returns to spawn on release
|
||||
- [ ] Event log shows all events
|
||||
- [ ] Current state updates correctly
|
||||
- [ ] All buttons respond
|
||||
- [ ] Configuration controls work
|
||||
|
||||
---
|
||||
|
||||
## Key Reminder
|
||||
|
||||
🎯 **This test scene is for EFFECTS ONLY, not placement logic!**
|
||||
|
||||
Cards will ALWAYS snap back to spawn point. Test slot placement in album integration scenes.
|
||||
|
||||
|
||||
@@ -1,247 +0,0 @@
|
||||
# Card Test Scene Setup Guide
|
||||
|
||||
**Purpose**: Test card state machine, animations, and drag behavior WITHOUT slot placement functionality.
|
||||
|
||||
**Last Updated**: November 12, 2025
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This test scene provides a controlled environment to test individual card effects, state transitions, and dragging behavior. Cards can be dragged with appropriate visual effects, but will **always snap back to their spawn point** when released - no slotting logic is implemented in this test environment.
|
||||
|
||||
---
|
||||
|
||||
## What This Scene Tests
|
||||
|
||||
✅ **Card State Transitions**
|
||||
- Idle → Revealed (flip animation)
|
||||
- Revealed → Enlarged (new/repeat card display)
|
||||
- Dragging state (visual feedback during drag)
|
||||
- Return to Idle after interactions
|
||||
|
||||
✅ **Card Animations**
|
||||
- Flip animations
|
||||
- Enlarge/shrink animations
|
||||
- Drag scale effects
|
||||
- Idle hover animations
|
||||
|
||||
✅ **Card Flows**
|
||||
- New card reveal flow
|
||||
- Repeat card flow (with count display)
|
||||
- Upgrade flow (5/5 repeats)
|
||||
|
||||
✅ **Drag Behavior**
|
||||
- Card can be dragged
|
||||
- Visual scale feedback during drag
|
||||
- **Automatic snap back to spawn point on release**
|
||||
|
||||
❌ **Not Tested (Out of Scope)**
|
||||
- Slot placement logic
|
||||
- Album integration
|
||||
- Multi-card scenarios
|
||||
- Booster pack opening
|
||||
|
||||
---
|
||||
|
||||
## Scene Setup Instructions
|
||||
|
||||
### 1. Create Test Scene
|
||||
- Create new scene: `Assets/Scenes/CardTestScene.unity`
|
||||
- Add Canvas with CanvasScaler configured for your target resolution
|
||||
- Add EventSystem
|
||||
|
||||
### 2. Create Card Test GameObject
|
||||
- Create empty GameObject: "CardTestController"
|
||||
- Add `CardTestController.cs` component
|
||||
- Position in hierarchy under Canvas or as scene root
|
||||
|
||||
### 3. Setup Test Card
|
||||
- Add Card prefab to scene as child of Canvas
|
||||
- Position card at desired spawn location (center of screen recommended)
|
||||
- Assign to CardTestController → Test Card field
|
||||
- Create or assign CardData ScriptableObject → Test Card Data field
|
||||
|
||||
### 4. UI Panel Setup
|
||||
Create a panel with the following buttons and controls:
|
||||
|
||||
#### State Transition Buttons
|
||||
- "To Idle State" → `TransitionToIdleState()`
|
||||
- "To Revealed State" → `TransitionToRevealedState()`
|
||||
- "To Enlarged New" → `TransitionToEnlargedNewState()`
|
||||
- "To Enlarged Repeat" → `TransitionToEnlargedRepeatState()`
|
||||
- "To Dragging State" → `TransitionToDraggingState()`
|
||||
- "To Album Enlarged" → `TransitionToAlbumEnlargedState()`
|
||||
|
||||
#### Flow Simulation Buttons
|
||||
- "New Card Flow" → `SimulateNewCardFlow()`
|
||||
- "Repeat Card Flow" → `SimulateRepeatCardFlow()`
|
||||
- "Upgrade Flow" → `SimulateUpgradeFlow()`
|
||||
- "Test Drag & Snap" → `TestDragAndSnap()`
|
||||
|
||||
#### Animation Test Buttons
|
||||
- "Play Flip" → `PlayFlipAnimation()`
|
||||
- "Play Enlarge" → `PlayEnlargeAnimation()`
|
||||
- "Play Shrink" → `PlayShrinkAnimation()`
|
||||
- "Start Idle Hover" → `StartIdleHoverAnimation()`
|
||||
- "Stop Idle Hover" → `StopIdleHoverAnimation()`
|
||||
|
||||
#### Utility Buttons
|
||||
- "Reset Card Position" → `ResetCardPosition()`
|
||||
- "Clear Event Log" → `ClearEventLog()`
|
||||
|
||||
### 5. Configuration Controls
|
||||
Add these UI elements and wire them up:
|
||||
|
||||
- **Toggle**: "Is New Card" → `isNewToggle`
|
||||
- **Slider**: "Repeat Count (0-5)" → `repeatCountSlider`
|
||||
- Min: 0, Max: 5, Whole Numbers: true
|
||||
- **TextMeshProUGUI**: Repeat count label → `repeatCountLabel`
|
||||
- **Dropdown**: "Rarity" → `rarityDropdown`
|
||||
- Options: Common, Uncommon, Rare, Epic, Legendary
|
||||
- **Toggle**: "Is Clickable" → `isClickableToggle`
|
||||
- **Button**: "Apply Setup" → `ApplyCardSetup()`
|
||||
|
||||
### 6. Status Display
|
||||
Add these UI text fields:
|
||||
|
||||
- **TextMeshProUGUI**: "Current State: [state]" → `currentStateText`
|
||||
- **TextMeshProUGUI**: Event log (scrollable) → `eventLogText`
|
||||
|
||||
### 7. Assign All References
|
||||
In CardTestController inspector, assign all serialized fields:
|
||||
- Test Card
|
||||
- Test Card Data
|
||||
- All UI references (toggles, sliders, text fields, etc.)
|
||||
|
||||
---
|
||||
|
||||
## How to Use the Test Scene
|
||||
|
||||
### Testing New Card Flow
|
||||
1. Click "New Card Flow" button
|
||||
2. Card starts in Idle state (face down)
|
||||
3. Click the card to flip it
|
||||
4. Card transitions through reveal → enlarged new → idle
|
||||
|
||||
### Testing Repeat Card Flow
|
||||
1. Set repeat count slider (0-4)
|
||||
2. Click "Repeat Card Flow" button
|
||||
3. Click card to flip
|
||||
4. Observe repeat count display
|
||||
5. Card shows "x/5" indicator
|
||||
|
||||
### Testing Upgrade Flow
|
||||
1. Click "Upgrade Flow" button (auto-sets to 5/5)
|
||||
2. Click card to flip
|
||||
3. Card automatically triggers upgrade effect
|
||||
4. Event log shows upgrade triggered
|
||||
|
||||
### Testing Drag Behavior
|
||||
1. Click "Test Drag & Snap" button
|
||||
2. Card enters Revealed state with dragging enabled
|
||||
3. **Drag the card anywhere on screen**
|
||||
4. Card scales up during drag (visual feedback)
|
||||
5. **Release the card**
|
||||
6. Card snaps back to spawn point
|
||||
7. Card returns to Idle state
|
||||
|
||||
### Testing Individual States
|
||||
- Click any "To [State]" button to jump directly to that state
|
||||
- Useful for testing specific state behavior
|
||||
- Watch event log for state transitions
|
||||
|
||||
### Testing Animations
|
||||
- Use animation test buttons to trigger individual animations
|
||||
- Combine with state transitions for complex testing
|
||||
|
||||
---
|
||||
|
||||
## Expected Behavior
|
||||
|
||||
### Dragging
|
||||
- ✅ Card can be dragged when in appropriate states
|
||||
- ✅ Card scales to 1.2x (or configured DragScale) while dragging
|
||||
- ✅ Card follows cursor/touch smoothly
|
||||
- ✅ Card **always snaps back to original spawn position** when released
|
||||
- ❌ Card does NOT interact with slots
|
||||
- ❌ Card does NOT stay where you drop it
|
||||
|
||||
### Event Log
|
||||
All card events are logged with timestamps:
|
||||
- State transitions
|
||||
- Drag start/end
|
||||
- Flip complete
|
||||
- Upgrade triggered
|
||||
- Interaction complete
|
||||
- Card dismissed
|
||||
|
||||
### State Display
|
||||
Current state updates in real-time (refreshes every 0.5 seconds)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Card Not Dragging
|
||||
- Ensure "Test Drag & Snap" button was clicked
|
||||
- Check that card has DraggableObject component
|
||||
- Verify EventSystem exists in scene
|
||||
- Check Canvas has GraphicRaycaster
|
||||
|
||||
### Card Not Snapping Back
|
||||
- CardTestController should handle OnDragEnded event
|
||||
- Check event subscriptions in Awake()
|
||||
- Verify _originalCardPosition is set correctly
|
||||
|
||||
### Buttons Not Working
|
||||
- Verify all Button components have onClick events wired
|
||||
- Check CardTestController reference is assigned
|
||||
- Ensure method names match exactly (case-sensitive)
|
||||
|
||||
### Event Log Empty
|
||||
- Assign eventLogText TextMeshProUGUI field
|
||||
- Check console for [CardTest] debug logs
|
||||
- Verify CardContext events are firing
|
||||
|
||||
---
|
||||
|
||||
## Key Differences from Production
|
||||
|
||||
| Feature | Test Scene | Production |
|
||||
|---------|-----------|------------|
|
||||
| **Drag Target** | Snap back to spawn | Place in album slots |
|
||||
| **Slot Logic** | None | Full slot validation |
|
||||
| **Card Count** | Single card only | Multiple cards/deck |
|
||||
| **Context** | Isolated testing | Full game integration |
|
||||
| **Purpose** | Test effects/animations | Actual gameplay |
|
||||
|
||||
---
|
||||
|
||||
## Files Involved
|
||||
|
||||
- **Script**: `Assets/Scripts/UI/CardSystem/Testing/CardTestController.cs`
|
||||
- **Scene**: `Assets/Scenes/CardTestScene.unity` (you create this)
|
||||
- **Card Prefab**: `Assets/Prefabs/UI/Card.prefab`
|
||||
- **Documentation**: This file
|
||||
|
||||
---
|
||||
|
||||
## Next Steps After Testing
|
||||
|
||||
Once individual card effects work in this test scene:
|
||||
1. Move to album integration testing
|
||||
2. Test slot placement logic separately
|
||||
3. Combine card + slot in production scenes
|
||||
4. Test booster pack opening flows
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **No slot references**: The test controller no longer has slot1/slot2 fields
|
||||
- **Simplified focus**: Test ONLY card behavior, not placement logic
|
||||
- **Snap-back is intentional**: This ensures clean, repeatable testing
|
||||
- **Event logging**: Use the event log to debug timing issues
|
||||
|
||||
|
||||
Reference in New Issue
Block a user