# Baccarat - Casino Card Game

A feature-rich Baccarat (Punto Banco) app for iOS built with SwiftUI. Experience authentic casino gameplay with side bets, road map history, and detailed statistics — all without risking real money.

![Platform](https://img.shields.io/badge/platform-iOS%2026%2B-blue)
![Swift](https://img.shields.io/badge/Swift-6.2-orange)
![SwiftUI](https://img.shields.io/badge/SwiftUI-✓-green)

## Features

### 🎓 First-Time User Experience
- **Welcome Sheet** — Interactive introduction on first launch
- **Spotlight Walkthrough** — Guided tour with spotlight focus on key UI elements
- **Sherpa Framework** — Modern walkthrough with progress indicators and haptic feedback
- **Never Intrusive** — All onboarding is skippable and shown only once

### 🎰 Authentic Punto Banco Gameplay
- Complete Baccarat rules with automatic third card logic
- Natural detection (8 or 9 on initial deal)
- Multi-deck shoe support (1, 6, or 8 decks)
- Animated card dealing with sound effects and haptics
- Automatic shoe reshuffling with burn card

### ⚙️ Settings & Customization
- Dealing animations toggle and adjustable dealing speed
- Card reveal style: Auto (instant flip), Tap (per-card), Squeeze (peek/drag reveal)
- Persistent preferences via iCloud sync

### 💰 Betting Options

#### Main Bets
| Bet Type | Payout | House Edge |
|----------|--------|------------|
| Player | 1:1 | 1.24% |
| Banker | 0.95:1 (5% commission) | 1.06% |
| Tie | 8:1 | 14.4% |

#### Side Bets
| Bet Type | Payout |
|----------|--------|
| Player Pair | 11:1 |
| Banker Pair | 11:1 |
| Dragon Bonus (Natural) | 1:1 |
| Dragon Bonus (Win by 4) | 1:1 |
| Dragon Bonus (Win by 5) | 2:1 |
| Dragon Bonus (Win by 6) | 4:1 |
| Dragon Bonus (Win by 7) | 6:1 |
| Dragon Bonus (Win by 8) | 10:1 |
| Dragon Bonus (Win by 9) | 30:1 |

### 📊 Road Map History
- Visual "Big Road" style result display
- Color-coded outcomes (Blue=Player, Red=Banker, Green=Tie)
- Pair markers (yellow dot)
- Natural markers (star)
- Scrollable session history

### 🎚️ Table Limits
| Level | Min Bet | Max Bet |
|-------|---------|---------|
| Casual | $5 | $500 |
| Low Stakes | $10 | $1,000 |
| Medium Stakes | $25 | $5,000 |
| High Stakes | $100 | $10,000 |
| VIP | $500 | $50,000 |

### ☁️ iCloud Sync
- Balance and statistics sync across devices
- Settings persist via iCloud
- Automatic conflict resolution

## Architecture

```
Baccarat/
├── BaccaratApp.swift          # App entry point
├── ContentView.swift          # Root view
├── Engine/
│   ├── BaccaratEngine.swift   # Core game logic, third card rules, payouts
│   └── GameState.swift        # Observable state machine
├── Models/
│   ├── BetType.swift          # Bet types, payouts, Dragon Bonus table
│   ├── GameResult.swift       # Round outcomes
│   ├── GameSettings.swift     # User preferences, table limits
│   ├── Hand.swift             # Baccarat hand model
│   └── Shoe.swift             # Multi-deck shoe with shuffle/burn
├── Storage/
│   └── BaccaratGameData.swift # Persistence models
├── Theme/
│   └── DesignConstants.swift  # Design system tokens
├── Views/
│   ├── Development/           # Dev-only views (branding, icons)
│   ├── Game/                  # Main game UI components
│   ├── Sheets/                # Modal views (settings, stats, rules)
│   └── Table/                 # Table layout, betting zones, road map
└── Resources/
    └── Localizable.xcstrings  # Localization strings
```

## Game Rules

### Card Values
- **Ace**: 1 point
- **2-9**: Face value
- **10, J, Q, K**: 0 points
- Hand value = sum mod 10 (e.g., 7+8=15 → 5)

### Third Card Rules

#### Player
- 0-5: Draws third card
- 6-7: Stands
- 8-9: Natural (no third card)

#### Banker (when Player draws)
| Banker Total | Draws if Player's 3rd is... |
|--------------|----------------------------|
| 0-2 | Always draws |
| 3 | 0-7, 9 (not 8) |
| 4 | 2-7 |
| 5 | 4-7 |
| 6 | 6-7 |
| 7 | Never draws |

## Tech Stack

- **iOS 26.0+** target
- **Swift 6.2** with strict concurrency
- **SwiftUI** with `@Observable` for state management
- **CasinoKit** — Shared package for cards, chips, sounds, and common UI
- **CloudKit** — iCloud sync for game data and settings

## Requirements

- Xcode 16.0+
- iOS 26.0+ deployment target
- Swift 6.2+

## Getting Started

1. Open `CasinoGames.xcworkspace` in Xcode
2. Select the **Baccarat** scheme
3. Build and run on a simulator or device

## Localization

The app supports:
- English (en)
- Spanish - Mexico (es-MX)
- French - Canada (fr-CA)

Strings are managed via String Catalogs (`Localizable.xcstrings`).

## Design System

All UI values are centralized in `DesignConstants.swift`:
- Spacing, corner radii, font sizes
- Opacity and shadow values
- Animation durations
- Semantic color definitions

## Accessibility

- Full VoiceOver support with meaningful labels
- Dynamic Type for scalable text
- High-contrast visuals
- Accessibility summaries for road map history

## Why Baccarat?

- **Lowest house edge** in the casino (1.06% on Banker bet)
- **No skill required** — pure chance with simple rules
- **Fast-paced** gameplay
- **Elegant** and sophisticated atmosphere
- **James Bond's favorite** casino game

## License

This project is proprietary software. All rights reserved.

---

*Built with ❤️ using SwiftUI*