de0da01f25
Complete native rewrite of the web-based SoliCards game as a SwiftUI multiplatform app targeting iOS 17+, iPadOS 17+, and macOS 14+. Three solitaire variants (Klondike, Spider, FreeCell) with full game rules, drag & drop, smart zoom layout, 6 themes, 4 difficulty levels, SwiftData persistence, VoiceOver accessibility, and 57 unit tests. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
128 lines
3.4 KiB
Markdown
128 lines
3.4 KiB
Markdown
# 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.
|