💣 CandyMines
Minesweeper on the SugarCraft stack
Customisable board (width / height / mine count), recursive zero-flood-fill, win / lose detection. Pure-state Board class so every reveal is unit-testable without touching the runtime.
Install
composer require sugarcraft/candy-minesQuickstart
./bin/candy-mines # 10×10, 12 mines (defaults)
./bin/candy-mines 16 16 40 # custom board
// Programmatic:
use SugarCraft\Core\Program;
use SugarCraft\Core\ProgramOptions;
use SugarCraft\Mines\Game;
(new Program(Game::start(width: 16, height: 16, mines: 40),
new ProgramOptions(useAltScreen: true)))->run();What's in the box
First-click safetyMines aren't placed until the first reveal, with the clicked cell's 3×3 neighbourhood excluded — every game gets a non-trivial flood-fill on click 1.
Recursive flood fillZero-adjacency cells reveal their neighbours transitively, exactly like the original.
Vim-style movement
hjkl alongside arrows; cursor clamps at board edges.Flag toggle
f flags / unflags the cursor cell; flagged cells can't be revealed by accident.Chord click
c or middle-click on a satisfied number reveals all unflagged neighbours — mirrors classic left+right chord behaviour.Sub-second timerGame timer uses
microtime(true) for millisecond precision; frozen on win/lose and stored in stats.Best-time persistence
DifficultyStats persists games/wins/best time per difficulty to JSON atomically (tmp+rename) so crashes never corrupt the record.Win + lose detection
isWon = every non-mine revealed; exploded = at least one mine was clicked. O(1) via revealedCount — no grid scan on each move.Restart key
r reseeds with a fresh layout, preserving the chosen board size.Save / restore mid-game
Board::serialize() emits versioned JSON; Board::unserialize() reconstructs the exact board state for mid-game suspend/resume.Custom difficulty
Ui\CustomDifficulty validates rows (2–50), cols (2–50), mines (1 to rows×cols−9) with i18n-aware error messages.Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Port of go-sweep (Go upstream)
API
| Class | Method | Description |
|---|---|---|
| Game | start(width, height, mines) | Start a new game |
| Game | withDifficulty(d) | Start with a preset difficulty |
| Game | elapsed() | Elapsed time in seconds (sub-second precision) |
| Game | recordResult(elapsed) | Record win/loss and update stats |
| Board | new(width, height, mines) | Create game board |
| Board | cell(x, y) | Get cell at position |
| Board | chord(x, y) | Chord-click — reveal safe neighbours of a satisfied number |
| Board | serialize() | Emit versioned JSON string ({v:1, w, h, m, p, e, r, c}) for mid-game save |
| Board | unserialize(data) | Reconstruct a Board from a serialize() payload |
| Ui\CustomDifficulty | fromInput(rows, cols, mines) | Validate custom board dimensions; throws with i18n key on violation |
| Ui\CustomDifficulty | defaults() | Factory — 9×9, 10 mines |
| DifficultyStats | load(path) | Load stats from atomic JSON file (null if absent) |
| DifficultyStats | save(path) | Persist stats atomically (tmp+rename) |
| DifficultyStats | withGame(d, won, time) | Return new DifficultyStats with the game recorded |
