AppleHillsProduction/docs/cards_wip/card_prefab_visual_reference.md

# 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! 🎉