# SETUP.md — SoliCards

## Prerequisites

- **Xcode 16.3+** (or latest stable)
- **macOS 14+** (Sonoma or later)
- **xcodegen** (for project generation from `project.yml`)

Install xcodegen:
```bash
brew install xcodegen
```

No other dependencies. The project has zero external packages.

## Getting Started

### 1. Generate the Xcode project

```bash
xcodegen generate
```

This reads `project.yml` and creates `SoliCards.xcodeproj`.

### 2. Open in Xcode

```bash
open SoliCards.xcodeproj
```

### 3. Select a target and run

| Target | Destination | Notes |
|--------|-------------|-------|
| SoliCards | iPhone/iPad Simulator | iOS 17+ |
| SoliCards | My Mac | macOS 14+ (native) |
| SoliCardsTests | iPhone Simulator | Unit tests |

## Build Commands (CLI)

### Debug build (iOS)
```bash
xcodebuild build \
  -project SoliCards.xcodeproj \
  -scheme SoliCards \
  -destination 'platform=iOS Simulator,name=iPhone 16'
```

### Debug build (macOS)
```bash
xcodebuild build \
  -project SoliCards.xcodeproj \
  -scheme SoliCards \
  -destination 'platform=macOS' \
  CODE_SIGN_IDENTITY=- CODE_SIGNING_REQUIRED=NO
```

### Release build
```bash
xcodebuild build \
  -project SoliCards.xcodeproj \
  -scheme SoliCards \
  -configuration Release \
  -destination 'platform=iOS Simulator,name=iPhone 16'
```

### Run tests
```bash
xcodebuild test \
  -project SoliCards.xcodeproj \
  -scheme SoliCardsTests \
  -destination 'platform=iOS Simulator,name=iPhone 16'
```

### Static analysis
```bash
xcodebuild analyze \
  -project SoliCards.xcodeproj \
  -scheme SoliCards \
  -destination 'platform=iOS Simulator,name=iPhone 16'
```

## Schemes

| Scheme | Purpose |
|--------|---------|
| SoliCards | Main app (iOS + macOS multiplatform) |
| SoliCardsTests | Unit test bundle (57 tests, 12 suites) |

## Project Structure

```
SoliCards/                      # 53 Swift source files
├── SoliCardsApp.swift          # @main entry point
├── ContentView.swift           # Root navigation, persistence wiring
├── Models/                     # Card, Suit, Rank, GameVariant, Difficulty, etc.
├── GameEngine/                 # GameRules protocol + 3 variant implementations
├── ViewModels/                 # GameViewModel, SettingsViewModel, StatsViewModel
├── Views/                      # SwiftUI views (Game, Menu, Settings, Statistics)
├── Services/                   # SoundManager, TimerService, HapticManager
├── Persistence/                # SwiftData models + PersistenceManager
├── Theme/                      # GameTheme, ThemeManager
├── Extensions/                 # CardLayout, Array+Card
└── Resources/                  # Assets.xcassets, Localizable.xcstrings, PrivacyInfo

SoliCardsTests/                 # 9 test files, 57 tests
├── Models/                     # CardTests, DeckTests, DifficultyTests
└── GameEngine/                 # KlondikeRulesTests, SpiderRulesTests, FreeCellRulesTests,
                                # MoveValidatorTests, AutoCompleterTests, GameStateTests
```

## Card Assets

- **52 card front PNGs** imported from `game-SoliCards/svg_playing_cards/fronts/`
- **12 card back PNGs** imported from `game-SoliCards/svg_playing_cards/backs/`
- All stored in `SoliCards/Resources/Assets.xcassets/` as imagesets

## Regenerating the Project

If you modify `project.yml` (add targets, change settings, etc.):

```bash
xcodegen generate
```

The `.xcodeproj` is generated — do not edit it by hand.