PHPackages                             sugarcraft/candy-mines - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. sugarcraft/candy-mines

ActiveProject[CLI & Console](/categories/cli)

sugarcraft/candy-mines
======================

Minesweeper TUI — port of maxpaulus43/go-sweep on the SugarCraft stack.

00PHP

Since Jun 29Pushed 1mo agoCompare

[ Source](https://github.com/sugarcraft/candy-mines)[ Packagist](https://packagist.org/packages/sugarcraft/candy-mines)[ RSS](/packages/sugarcraft-candy-mines/feed)WikiDiscussions master Synced 3w ago

READMEChangelogDependenciesVersions (1)Used By (0)

[![candy-mines](.assets/icon.png)](.assets/icon.png)

CandyMines
==========

[](#candymines)

[![CI](https://github.com/detain/sugarcraft/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/detain/sugarcraft/actions/workflows/ci.yml)[![codecov](https://camo.githubusercontent.com/34b4f97ee334767a4d047b2b50d23eee2170cb1fa28b422fce143b101bc5c9ae/68747470733a2f2f636f6465636f762e696f2f67682f64657461696e2f737567617263726166742f6272616e63682f6d61737465722f67726170682f62616467652e7376673f666c61673d63616e64792d6d696e6573)](https://app.codecov.io/gh/detain/sugarcraft?flags%5B0%5D=candy-mines)[![Packagist Version](https://camo.githubusercontent.com/ea3342d1d989de9c97d0104d2bf7ed8e9b6ee28a554b19945f2c57b8fb88c4b1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f737567617263726166742f63616e64792d6d696e65733f6c6162656c3d7061636b6167697374)](https://packagist.org/packages/sugarcraft/candy-mines)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP](https://camo.githubusercontent.com/e78ffc83837c0d12647811a7fd1910c3cbeae04988de94bb4fd5b67e0874696a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d254532253839254135382e312d3838393262662e737667)](https://www.php.net/)

[![demo](.vhs/play.gif)](.vhs/play.gif)

Minesweeper on the SugarCraft stack — port of [`maxpaulus43/go-sweep`](https://github.com/maxpaulus43/go-sweep). Customisable board, recursive flood-fill, win / lose detection, vim-style movement.

Difficulty presets are available via `Game::withDifficulty(Difficulty::$LEVEL)` — `EASY` (9×9, 10 mines), `MEDIUM` (16×16, 40 mines), `EXPERT` (30×16, 99 mines).

Run it
------

[](#run-it)

```
composer install
./bin/candy-mines [width] [height] [mines]   # defaults: 10 10 12
```

Keys
----

[](#keys)

KeyAction`↑/↓/←/→` or `hjkl`Move cursor`Space` / `Enter`Reveal cell`f`Toggle flag`c` / middle-clickChord — reveal safe neighbors`r`Restart with new mines`q` / `Esc`QuitArchitecture
------------

[](#architecture)

Five pure-state classes plus the runtime Model, renderer, UI helper, and persistence:

FileRole`Cell`Value object — mine / revealed / flagged / adjacent count`Board`The grid + every transition (reveal, flag, flood-fill, chord). Win detection is O(1) via `revealedCount` counter. Serialises to versioned JSON for mid-game save/load.`Game` (Model)Cursor + key routing + restart + win/lose gate + sub-second timer (`microtime(true)`)`Stats`Immutable difficulty stats — games, wins, best time per preset`DifficultyStats`Atomic JSON persistence wrapper (tmp+rename, Homestead pattern)`Ui/CustomDifficulty`Validated custom board dimensions — rows (2–50), cols (2–50), mines (1 to rows×cols−9). Throws i18n-aware `InvalidArgumentException` on constraint violation.`Renderer`Pure view function. CandySprinkles `Style` + `Border::rounded()`The first reveal is always safe — mines are placed only after click 1, with the clicked cell's 3×3 neighbourhood excluded so the player gets a non-trivial flood-fill on every game.

**Chord click** (`c` / middle-click): when a revealed number has exactly the right number of flagged neighbours, chord-clicking it safely reveals all remaining neighbours. This mirrors the standard left+right simultaneous press in classic minesweeper.

**O(1) win detection**: `Board::isWon()` compares `revealedCount` (the number of non-mine cells revealed) against `width × height − mineCount`. Win detection is constant-time regardless of board size — no full-grid scan on every move.

**Save / restore mid-game**: `Board::serialize()` produces a versioned JSON payload (`{v:1, w, h, m, p, e, r, c}`) covering every cell and board state. `Board::unserialize()` reconstructs an identical `Board` instance so sessions can be suspended and resumed.

Demos
-----

[](#demos)

### Gameplay

[](#gameplay)

[![play](.vhs/play.gif)](.vhs/play.gif)

### Flagging

[](#flagging)

[![flagging](.vhs/flagging.gif)](.vhs/flagging.gif)

Shared foundations
------------------

[](#shared-foundations)

The minefield renderer builds output via [candy-buffer](https://github.com/detain/sugarcraft/tree/master/candy-buffer) — each cell is zone-tagged via `Mark::zone("cell:$row:$col", $glyph)` so `Scanner::hit($x, $y)` maps directly to a cell address. `Renderer::resolveClick()` bridges mouse coordinates to row/col. Snapshot tests via [candy-testing](https://github.com/detain/sugarcraft/tree/master/candy-testing) pin canonical game states (first-click safe area, cascade reveal, win overlay).

Test
----

[](#test)

```
composer install
vendor/bin/phpunit
```

###  Health Score

19

—

LowBetter than 9% of packages

Maintenance59

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/b1036e0717211b8030b83cbe729e8ba6ba442fdbd5285fb97a39d7dcfe339342?d=identicon)[detain](/maintainers/detain)

---

Top Contributors

[![detain](https://avatars.githubusercontent.com/u/1364504?v=4)](https://github.com/detain "detain (81 commits)")

---

Tags

candycorecomposerphpsugarcraftterminaltui

### Embed Badge

![Health badge](/badges/sugarcraft-candy-mines/health.svg)

```
[![Health](https://phpackages.com/badges/sugarcraft-candy-mines/health.svg)](https://phpackages.com/packages/sugarcraft-candy-mines)
```

###  Alternatives

[illuminate/console

The Illuminate Console package.

13046.0M6.8k](/packages/illuminate-console)[styleci/cli

The CLI tool for StyleCI

71470.5k9](/packages/styleci-cli)[winbox/args

Windows command-line formatter

20720.9k21](/packages/winbox-args)[mallardduck/laravel-traits

A collection of useful Laravel snippets in the form of easy to use traits.

136.2k2](/packages/mallardduck-laravel-traits)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)