468 lines
13 KiB
Markdown
468 lines
13 KiB
Markdown
# 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
|
|
|
|
```swift
|
|
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
|
|
|
|
```swift
|
|
// 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:
|
|
|
|
```swift
|
|
// 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)
|
|
|
|
```swift
|
|
// 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)
|
|
|
|
```swift
|
|
// 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:
|
|
|
|
```swift
|
|
// 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)
|
|
|
|
```swift
|
|
// 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
|
|
|
|
```swift
|
|
// 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
|
|
|
|
```swift
|
|
// 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:
|
|
|
|
```swift
|
|
// 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`):
|
|
|
|
```swift
|
|
// 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.*
|
|
|