Clue-Solver

Clue Solver

A native iOS deduction assistant for the board game Clue (Cluedo). Use it alongside a physical game to automatically track suggestions, eliminate possibilities, and solve the mystery faster than manual note-taking ever could.

Features

Automated constraint propagation — Every suggestion, no-show, and card reveal cascades through the entire game state, deducing card ownership and envelope contents automatically.
Exact probability engine — Enumerates all feasible envelope combinations and computes frequency-based probabilities using a backtracking solver with memoization, rather than heuristic guesses.
Failed accusation tracking — Wrong accusations permanently eliminate that suspect-weapon-room triple, shifting probabilities across all three categories.
Five-tab game dashboard — Cards view with probability heatmap, per-player card breakdown, turn history timeline, deduction insights with natural-language explanations, and an interactive detective notepad (grid + freehand drawing).
24 built-in editions — Classic Clue, Master Detective, and 22 themed variants, plus support for custom user-created editions.
Full undo/redo — Mistakes are corrected by rebuilding the entire engine state from the remaining turn history.
Persistent save/resume — Games are saved automatically via SwiftData and can be resumed across app launches.

Tech Stack

Swift 6 / SwiftUI / SwiftData
iOS 17+ with @Observable macro and @MainActor isolation
XcodeGen for project generation

Building

# Generate Xcode project (if using XcodeGen)
xcodegen generate --spec ClueSolver/project.yml

# Or open directly
open ClueSolver/ClueSolver.xcodeproj

Build and run on an iOS 17+ simulator or device from Xcode.

Testing

# Logic + integration tests (fast, no simulator UI)
xcodebuild test \
  -project ClueSolver/ClueSolver.xcodeproj \
  -scheme ClueSolver \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
  -skip-testing:ClueSolverUITests

# Full suite including UI tests
xcodebuild test \
  -project ClueSolver/ClueSolver.xcodeproj \
  -scheme ClueSolver \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro'

The test suite includes oracle-verified solver correctness, replay equivalence checks, seeded random transcript testing, invariance tests (seat rotation, card renaming), edition validation, persistence integration, performance benchmarks, and end-to-end UI automation.

How It Works

Setup — Pick an edition, set the number of players, enter names, distribute card counts, and select your dealt cards.
Record turns — As each suggestion happens at the table, record who suggested what, and whether anyone showed a card (and which card, if you saw it).
Watch the deductions roll in — The engine propagates constraints, resolves disjunctions (“Player showed one of Knife/Rope/Hall” → later narrows to just one), and identifies envelope cards by elimination.
Check probabilities — The Cards tab shows real-time probability that each card is in the envelope, computed from exact triple enumeration.
Make your accusation — When the engine has narrowed down the suspect, weapon, and room, you’ll know.

Project Structure

ClueSolver/
├── App/          Entry point and app state management
├── Models/       SwiftData models (Game, Player, Card, Turn, CardMarker, GameEdition)
├── Engine/       Constraint propagation solver, state validator, snapshots
├── Views/        SwiftUI screens (Home, Setup, Dashboard, Turn recording, Custom editions)
├── Editions/     Edition registry + 24 bundled JSON edition definitions
├── Theme/        Design system, haptics, sound, animations
├── Utilities/    Undo/redo manager, export manager
└── Extensions/   Navigation styling helpers

Documentation

Docs/project-overview.md — Comprehensive project description for onboarding and LLM context
Docs/edition-support-audit.md — Detailed audit of which editions the solver can and cannot model
Docs/testing-suite.md — Test coverage strategy, commands, and CI recommendations
Docs/dashboard-accessibility-issues.md — Known accessibility issues on the game dashboard

Edition Support

Status	Count	Examples
Fully supported	3	Classic Clue, Clue 2016, Master Detective
Likely compatible (needs verification)	11	Stranger Things, The Office, Scooby-Doo, D&D, etc.
Not supported (extra mechanics)	10	Harry Potter, Game of Thrones, Star Wars, etc.

See the edition support audit for details on each edition.