# Game Center Integration - CasinoKit (Shared Infrastructure)

This document outlines the shared Game Center infrastructure that will be used by all casino games in the workspace.

## Overview

Game Center will be integrated for **achievements only** (no leaderboards) to avoid cheating concerns with client-side casino games. All shared Game Center logic will live in CasinoKit to avoid code duplication.

## Shared Components to Add

### 1. GameCenterManager (Core Service)

**Location:** `CasinoKit/Sources/CasinoKit/GameCenter/GameCenterManager.swift`

**Purpose:** Centralized manager for all Game Center operations.

**Features:**
- Authentication with Game Center
- Achievement submission
- Achievement progress tracking
- Error handling and retry logic
- Availability checking
- Privacy-friendly (doesn't force sign-in)

**Key Methods:**
```swift
@MainActor
@Observable
class GameCenterManager {
    static let shared = GameCenterManager()
    
    var isAuthenticated: Bool = false
    var isAvailable: Bool = true
    var localPlayer: GKLocalPlayer?
    
    // Authentication
    func authenticate()
    
    // Achievement management
    func submitAchievement(_ identifier: String, percentComplete: Double)
    func incrementAchievement(_ identifier: String, by value: Double)
    func resetAchievements() // For testing only
    func loadAchievements() -> [GKAchievement]
    
    // UI presentation
    func showGameCenterDashboard()
}
```

**Implementation Notes:**
- Use async/await APIs (iOS 14+)
- Silent authentication (no blocking UI)
- Gracefully handle Game Center being disabled
- Cache authentication state
- Support offline mode (queue submissions for later)

### 2. Achievement Configuration Protocol

**Location:** `CasinoKit/Sources/CasinoKit/GameCenter/AchievementDefinition.swift`

**Purpose:** Type-safe achievement definitions per game.

```swift
protocol AchievementDefinition {
    var identifier: String { get }
    var title: String { get }
    var description: String { get }
    var maxProgress: Int { get }
    var iconName: String { get }
    var isIncremental: Bool { get }
}

// Example usage in game:
enum BlackjackAchievement: String, AchievementDefinition {
    case strategyStudent = "blackjack_strategy_50"
    case cardCounter = "blackjack_card_counting_25"
    // ...
    
    var identifier: String { 
        "com.yourdomain.blackjack.\(rawValue)" 
    }
    
    var title: String {
        switch self {
        case .strategyStudent: return String(localized: "Strategy Student")
        case .cardCounter: return String(localized: "Card Counter")
        }
    }
    
    // ... other properties
}
```

### 3. Game Center Access Point View

**Location:** `CasinoKit/Sources/CasinoKit/Views/GameCenter/GameCenterAccessPoint.swift`

**Purpose:** Standard UI component for showing Game Center status.

**Features:**
- Shows authentication state
- Displays achievement progress
- Links to Game Center dashboard
- Optional placement (top bar or settings)
- Respects user privacy preferences

```swift
struct GameCenterAccessPoint: View {
    @State private var manager = GameCenterManager.shared
    
    var body: some View {
        // Small floating button or status indicator
        // Shows GC icon when authenticated
        // Tapping opens achievement list
    }
}
```

### 4. Achievement Tracking Helper

**Location:** `CasinoKit/Sources/CasinoKit/GameCenter/AchievementTracker.swift`

**Purpose:** Helper for games to track achievement progress locally before submitting.

```swift
@MainActor
@Observable
class AchievementTracker<Achievement: AchievementDefinition> {
    private var progress: [String: Int] = [:]
    
    func increment(_ achievement: Achievement, by value: Int = 1)
    func getProgress(_ achievement: Achievement) -> Int
    func checkAndSubmit(_ achievement: Achievement)
    func reset() // For new game sessions
}
```

**Why This Helps:**
- Games can track progress locally (fast)
- Batch submissions to Game Center (efficient)
- Handles the "report once at 100%" logic for non-incremental achievements

### 5. Settings Integration

**Location:** `CasinoKit/Sources/CasinoKit/Views/Settings/GameCenterSettingsSection.swift`

**Purpose:** Standard settings UI for Game Center.

```swift
struct GameCenterSettingsSection: View {
    @State private var manager = GameCenterManager.shared
    
    var body: some View {
        SheetSection(title: "GAME CENTER", icon: "gamecontroller.fill") {
            if manager.isAvailable {
                HStack {
                    Text("Status")
                    Spacer()
                    Text(manager.isAuthenticated ? "Connected" : "Not Connected")
                        .foregroundStyle(.secondary)
                }
                
                if manager.isAuthenticated {
                    Button("View Achievements") {
                        manager.showGameCenterDashboard()
                    }
                    
                    Button("Sign Out") {
                        // Note: Can't actually sign out from app,
                        // just stop authenticating
                    }
                } else {
                    Button("Connect to Game Center") {
                        Task { await manager.authenticate() }
                    }
                }
            } else {
                Text("Game Center is not available")
                    .foregroundStyle(.secondary)
            }
        }
    }
}
```

### 6. Achievement Toast Notification

**Location:** `CasinoKit/Sources/CasinoKit/Views/GameCenter/AchievementToast.swift`

**Purpose:** Show celebratory notification when achievement is earned (optional enhancement).

**Features:**
- Brief animation when achievement unlocks
- Shows achievement icon and title
- Auto-dismisses after 3 seconds
- Doesn't block gameplay
- Similar to iOS system notifications

```swift
struct AchievementToast: View {
    let achievement: String
    let title: String
    @State private var isShowing = false
    
    var body: some View {
        // Slide-in notification from top
        // Shows achievement icon + title
        // Fades out after delay
    }
}
```

## File Structure

```
CasinoKit/Sources/CasinoKit/
├── GameCenter/
│   ├── GameCenterManager.swift          # Core manager (authentication, submission)
│   ├── AchievementDefinition.swift      # Protocol for type-safe achievements
│   ├── AchievementTracker.swift         # Local progress tracking helper
│   └── GameCenterError.swift            # Custom error types
├── Views/
│   └── GameCenter/
│       ├── GameCenterAccessPoint.swift  # Status indicator/button
│       ├── GameCenterSettingsSection.swift  # Settings UI component
│       └── AchievementToast.swift       # Achievement unlock notification
└── Resources/
    └── Localizable.xcstrings            # Add GC-related strings
```

## Localization Strings to Add

Add to `CasinoKit/Resources/Localizable.xcstrings`:

```
Game Center
Connected
Not Connected
Sign Out
View Achievements
Game Center is not available
Achievement Unlocked!
Connect to Game Center
```

## App Store Connect Configuration

**Note:** Each game will need its own achievements configured in App Store Connect.

### Achievement Naming Convention

Use consistent identifier format:
```
com.yourdomain.{game}.{achievement_key}

Examples:
com.yourdomain.blackjack.strategy_student
com.yourdomain.blackjack.card_counter
com.yourdomain.baccarat.dragon_master
com.yourdomain.baccarat.natural_high
```

### Achievement Assets

Each achievement needs:
- 512x512px icon (1x)
- 1024x1024px icon (2x)

**Design Guidelines:**
- Use SF Symbols where appropriate (consistent with app design)
- Match app color scheme
- Clear, recognizable icons
- Consider accessibility (high contrast)

## Implementation Order

1. **GameCenterManager** - Core authentication and submission logic
2. **AchievementDefinition protocol** - Type system
3. **AchievementTracker** - Helper for games to use
4. **GameCenterSettingsSection** - UI integration
5. **GameCenterAccessPoint** - Optional status indicator
6. **AchievementToast** - Optional enhancement

## Testing Strategy

### Local Testing
- Test with Game Center sandbox account
- Verify authentication flow
- Test achievement submission
- Test offline behavior
- Test achievement progress tracking

### TestFlight Testing
- Required for full Game Center integration testing
- Verify achievements appear correctly
- Test achievement notifications
- Verify localization

### Debug Features to Add
```swift
#if DEBUG
extension GameCenterManager {
    func resetAllAchievements() {
        // Only available in debug builds
    }
    
    func logAchievementStatus() {
        // Print all achievement progress
    }
}
#endif
```

## Privacy Considerations

- **No forced sign-in** - Game Center is entirely optional
- **Graceful degradation** - App works fully without Game Center
- **No data collection** - Only submit achievement progress, nothing else
- **User control** - Easy to see status and disconnect

## Performance Considerations

- **Authenticate once** - On app launch, silent background auth
- **Batch submissions** - Don't submit every increment immediately
- **Cache state** - Remember authentication status
- **Async operations** - Never block UI on Game Center calls
- **Offline queue** - Store failed submissions, retry later

## Future Enhancements (Optional)

- **Challenge Mode** - Separate game mode with fixed rules and leaderboards
- **Friend Comparison** - Show achievement progress vs friends
- **Weekly Challenges** - Time-limited achievement variants
- **Leaderboards** - Only if Challenge Mode is added with anti-cheat

## Dependencies

- **GameKit framework** - Apple's Game Center SDK
- **No third-party dependencies** - Pure Apple APIs

## Estimated Effort

- **CasinoKit infrastructure**: 4-6 hours
- **Per-game integration**: 2-3 hours each
- **App Store Connect setup**: 1-2 hours
- **Testing & polish**: 2-3 hours

**Total: ~12-16 hours** for complete implementation across both games.

---

## Next Steps

1. Review this plan
2. See game-specific plans in `Blackjack/GAME_CENTER_PLAN.md` and `Baccarat/GAME_CENTER_PLAN.md`
3. Configure achievements in App Store Connect
4. Implement CasinoKit infrastructure first
5. Integrate into games second
6. Test with TestFlight

---

*This shared infrastructure approach ensures consistency across all casino games while avoiding code duplication.*