CasinoGames/CasinoKit/GAME_TEMPLATE.md

Casino Game Development Guide

This guide explains how to build a new casino card game (like Blackjack, Poker, etc.) using CasinoKit, following the patterns established in the Baccarat app.

Project Structure

YourGame/
├── YourGameApp.swift              # App entry point
├── ContentView.swift              # Root view (usually just GameTableView)
├── Engine/
│   ├── YourGameEngine.swift       # Game rules & logic
│   └── GameState.swift            # Game state machine
├── Models/
│   ├── BetType.swift              # Game-specific bet types
│   ├── GameResult.swift           # Win/loss/push outcomes
│   ├── GameSettings.swift         # User settings (can reuse pattern)
│   ├── Hand.swift                 # Hand representation (if needed)
│   └── Shoe.swift                 # Card shoe (if multi-deck)
├── Storage/
│   └── YourGameData.swift         # Persistence model (PersistableGameData)
├── Theme/
│   └── DesignConstants.swift      # Game-specific design tokens
├── Views/
│   ├── GameTableView.swift        # Main game screen
│   ├── YourTableLayoutView.swift  # Game-specific table layout
│   ├── ResultBannerView.swift     # Win/loss display
│   ├── RulesHelpView.swift        # Game rules explanation
│   ├── SettingsView.swift         # Settings screen
│   └── StatisticsSheetView.swift  # Stats display
└── Resources/
    └── Localizable.xcstrings      # Translations

What CasinoKit Provides

Core Components (Import CasinoKit)

Category	Components	Usage
Cards	Card, Suit, Rank, Deck	Card models
Card Views	CardView, CardPlaceholderView	Card display
Chips	ChipDenomination, ChipView, ChipStackView, ChipSelectorView	Betting chips
Table	TableBackgroundView, FeltPatternView	Casino felt background
Overlays	GameOverView, ConfettiView	Game over & celebrations
Top Bar	TopBarView	Balance, settings, stats buttons
Badges	ValueBadge	Numeric value display
Settings	SettingsToggle, SpeedPicker, VolumePicker, BalancePicker	Settings UI
Sheets	SheetContainerView, SheetSection	Modal sheets
Branding	AppIconView, LaunchScreenView	App icons & splash
Audio	SoundManager, GameSound	Sound effects & haptics
Storage	CloudSyncManager, PersistableGameData	iCloud persistence
Models	TableLimits	Betting limits presets
Design	CasinoDesign	Spacing, colors, animations

Using CasinoKit Components

import SwiftUI
import CasinoKit

struct GameTableView: View {
    @State private var settings = GameSettings()
    @State private var gameState: GameState?
    @State private var selectedChip: ChipDenomination = .hundred
    
    var body: some View {
        ZStack {
            // 1. Table Background (from CasinoKit)
            TableBackgroundView()
            
            VStack {
                // 2. Top Bar (from CasinoKit)
                TopBarView(
                    balance: state.balance,
                    secondaryInfo: "\(state.engine.shoe.cardsRemaining)",
                    secondaryIcon: "rectangle.portrait.on.rectangle.portrait.fill",
                    onReset: { state.resetGame() },
                    onSettings: { showSettings = true },
                    onHelp: { showRules = true },
                    onStats: { showStats = true }
                )
                
                // 3. Your Game-Specific Table Layout
                YourTableLayoutView(...)
                
                // 4. Chip Selector (from CasinoKit)
                ChipSelectorView(
                    selectedChip: $selectedChip,
                    availableChips: ChipDenomination.allCases
                )
                
                // 5. Action Buttons (game-specific)
                ActionButtonsView(...)
            }
            
            // 6. Result Banner (game-specific, but follows pattern)
            if state.showResultBanner {
                ResultBannerView(...)
            }
            
            // 7. Confetti for Wins (from CasinoKit)
            if state.lastWinnings > 0 {
                ConfettiView()
            }
            
            // 8. Game Over (from CasinoKit)
            if state.isGameOver {
                GameOverView(
                    roundsPlayed: state.roundsPlayed,
                    onPlayAgain: { state.resetGame() }
                )
            }
        }
        .sheet(isPresented: $showSettings) {
            SettingsView(settings: settings, gameState: state) { ... }
        }
    }
}

Game-Specific Implementation

1. Game Engine (Required)

Create your game's rule engine. This handles:

• Card dealing logic
• Hand evaluation
• Win/loss determination
• Payout calculations

// Engine/YourGameEngine.swift
import CasinoKit

@Observable
@MainActor
final class YourGameEngine {
    var shoe: Shoe
    var playerHand: [Card] = []
    var dealerHand: [Card] = []
    
    init(deckCount: Int = 6) {
        self.shoe = Shoe(deckCount: deckCount)
    }
    
    func dealInitialCards() { ... }
    func evaluateHand(_ cards: [Card]) -> Int { ... }
    func determineWinner() -> GameResult { ... }
    func calculatePayout(bet: Int, result: GameResult) -> Int { ... }
}

2. Game State (Required)

Manages the state machine for your game:

// Engine/GameState.swift
import SwiftUI
import CasinoKit

enum GamePhase {
    case betting
    case dealing
    case playerTurn      // Blackjack-specific
    case dealerTurn      // Blackjack-specific
    case roundComplete
}

@Observable
@MainActor
final class GameState {
    // Core state
    var balance: Int
    var currentBets: [BetType: Int] = [:]
    var currentPhase: GamePhase = .betting
    var showResultBanner = false
    
    // Engine
    let engine: YourGameEngine
    
    // Persistence
    private let persistence: CloudSyncManager<YourGameData>
    
    // Sound
    private let sound = SoundManager.shared
    
    init(settings: GameSettings) {
        self.engine = YourGameEngine(deckCount: settings.deckCount.rawValue)
        self.balance = settings.startingBalance
        self.persistence = CloudSyncManager<YourGameData>()
        loadSavedGame()
    }
    
    func placeBet(type: BetType, amount: Int) {
        currentBets[type, default: 0] += amount
        balance -= amount
        sound.play(.chipPlace)
    }
    
    func deal() async {
        currentPhase = .dealing
        sound.play(.cardDeal)
        // Game-specific dealing logic
    }
    
    func newRound() {
        currentPhase = .betting
        showResultBanner = false
        sound.play(.newRound)
    }
}

3. Bet Types (Game-Specific)

// Models/BetType.swift

enum BetType: String, CaseIterable, Identifiable {
    // Blackjack example:
    case main = "main"
    case insurance = "insurance"
    case doubleDown = "double"
    case split = "split"
    
    // Baccarat example:
    // case player, banker, tie, playerPair, bankerPair, dragonBonusPlayer, dragonBonusBanker
    
    var id: String { rawValue }
    
    var displayName: String { ... }
    var payoutMultiplier: Double { ... }
}

4. Game Result (Game-Specific)

// Models/GameResult.swift

enum GameResult: Equatable {
    // Blackjack example:
    case playerWins
    case dealerWins
    case push
    case blackjack
    case bust
    
    var displayText: String { ... }
    var color: Color { ... }
}

5. Table Layout (Game-Specific)

This is the main visual difference between games:

// Views/YourTableLayoutView.swift

struct BlackjackTableView: View {
    // Shows dealer hand at top, player hand(s) below
    // Hit/Stand/Double/Split buttons
    // Insurance betting zone
}

struct BaccaratTableView: View {
    // Shows Player/Banker/Tie betting zones
    // Side bet zones (pairs, dragon bonus)
}

struct PokerTableView: View {
    // Community cards in center
    // Player positions around table
    // Pot display
}

6. Settings View (Mostly Reusable)

// Views/SettingsView.swift
import CasinoKit

struct SettingsView: View {
    @Bindable var settings: GameSettings
    let gameState: GameState
    
    var body: some View {
        SheetContainerView(title: "Settings") {
            // Table Limits (from CasinoKit pattern)
            SheetSection(title: "TABLE LIMITS", icon: "banknote") {
                // Use TableLimits enum from CasinoKit
            }
            
            // Deck Settings (game-specific)
            SheetSection(title: "DECK SETTINGS", icon: "rectangle.portrait.on.rectangle.portrait") {
                // DeckCount options
            }
            
            // Display Settings (reusable)
            SheetSection(title: "DISPLAY", icon: "eye") {
                SettingsToggle(title: "...", subtitle: "...", isOn: $settings.showX)
            }
            
            // Sound (from CasinoKit)
            SheetSection(title: "SOUND & HAPTICS", icon: "speaker.wave.2") {
                SettingsToggle(...)
                VolumePicker(volume: $settings.soundVolume)
            }
            
            // iCloud Sync (pattern from Baccarat)
            SheetSection(title: "CLOUD SYNC", icon: "icloud") { ... }
        }
    }
}

Sound Integration

// In your GameState
let sound = SoundManager.shared

// Play sounds at appropriate moments:
sound.play(.chipPlace)    // When placing a bet
sound.play(.cardDeal)     // When dealing cards
sound.play(.cardFlip)     // When flipping cards
sound.play(.win)          // On player win
sound.play(.lose)         // On player loss
sound.play(.push)         // On tie/push
sound.play(.newRound)     // Starting new round
sound.play(.gameOver)     // When out of chips

Persistence

// Storage/YourGameData.swift
import CasinoKit

struct BlackjackGameData: PersistableGameData {
    static let gameIdentifier = "blackjack"
    
    var roundsPlayed: Int { roundHistory.count }
    var lastModified: Date
    
    static var empty: BlackjackGameData {
        BlackjackGameData(
            lastModified: Date(),
            balance: 10_000,
            roundHistory: [],
            totalWinnings: 0,
            blackjackCount: 0,  // Game-specific stat
            bustCount: 0        // Game-specific stat
        )
    }
    
    var balance: Int
    var roundHistory: [SavedRoundResult]
    var totalWinnings: Int
    var blackjackCount: Int
    var bustCount: Int
}

Design Constants

Extend CasinoDesign for game-specific values:

// Theme/DesignConstants.swift

enum Design {
    // Reuse CasinoDesign values
    typealias Spacing = CasinoDesign.Spacing
    typealias CornerRadius = CasinoDesign.CornerRadius
    typealias Animation = CasinoDesign.Animation
    
    // Game-specific sizes
    enum Size {
        static let playerCardWidth: CGFloat = 55
        static let dealerCardWidth: CGFloat = 50
        // ... game-specific dimensions
    }
    
    // Game-specific colors (extend Color)
}

extension Color {
    enum BettingZone {
        static let main = Color.blue.opacity(0.3)
        static let insurance = Color.yellow.opacity(0.3)
        // ... game-specific colors
    }
}

Localization

Use String Catalogs (.xcstrings):

// Game-specific strings
Text(String(localized: "Hit"))
Text(String(localized: "Stand"))
Text(String(localized: "Double Down"))
Text(String(localized: "Split"))
Text(String(localized: "Blackjack!"))
Text(String(localized: "Bust!"))

Checklist for New Game

Setup

• Create new target in Xcode
• Add CasinoKit as dependency
• Copy DesignConstants.swift and customize
• Create Localizable.xcstrings

Models

• Define BetType enum
• Define GameResult enum
• Create YourGameData for persistence
• Create GameSettings (or reuse pattern)

Engine

• Implement game rules in YourGameEngine
• Implement GameState with phases

Views

• Create GameTableView (main container)
• Create game-specific table layout
• Create ResultBannerView (follow pattern)
• Create RulesHelpView (game rules)
• Customize SettingsView
• Create StatisticsSheetView

Integration

• Wire up SoundManager for game events
• Implement CloudSyncManager for persistence
• Add accessibility labels
• Add localization for all strings

Polish

• Test Dynamic Type scaling
• Test VoiceOver
• Test iPad layout
• Create app icon using AppIconView

What Could Be Added to CasinoKit

The following patterns from Baccarat could be abstracted:

1. Generic ResultBannerView - Win/loss display with bet breakdown
2. BettingZone protocol - Common betting zone behavior
3. GameStateProtocol - Common state machine patterns
4. HandDisplayView - Generic card hand display
5. ActionButtonsView - Deal/Clear/New Round pattern
6. StatisticsView - Generic stats display

---

This guide is based on the Baccarat implementation. For reference, see the Baccarat app structure and CasinoKit source code.