To browse rules, visit the Minesweeper Variants Rule List For the front-end project, use Minesweeper Variants-Vue
Minesweeper Variants, also known as 14mv, is a puzzle generator and game server for Minesweeper variants. It supports multiple rule combinations and can generate paper-style puzzles with a unique solution.
Python 3.13 is recommended. Download the installer for your platform from https://www.python.org.
If you use a virtual environment such as venv/virtualenv or Poetry, install the package there instead. An isolated environment is recommended to avoid conflicts with system packages.
python -m pip install --upgrade pip
python -m pip install minesweepervariantsThere are two common entry points: the server and the generator CLI.
Start the server:
python -m minesweepervariants.server
# Keep it running, then open https://koolshow.github.io/MinesweeperVariants-Vue/ in your browser.Run the generator CLI:
python -m minesweepervariantsYou can add command-line options such as -s for size and -t for total mines. See the examples and options below.
Poetry is recommended for dependency management and environment setup.
On Windows, download the official installer from https://www.python.org.
Follow the official installation guide: https://python-poetry.org/docs/#installation
From the project root:
poetry installPoetry will create an isolated virtual environment and install all dependencies automatically.
You do not need to activate the virtual environment manually. Use Poetry to run scripts directly:
poetry run python run.py [arguments]You can use the same pattern for other commands: poetry run <command>.
Some dependencies may require compiled C extensions. Install:
- Visual C++ Build Tools
Download it from:
Make sure these components are selected:
- C++ build tools, including MSVC and the Windows SDK
- CMake
Restart the terminal after installation.
run [arguments]This invokes the main generator.
| Option | Type | Description |
|---|---|---|
-s, --size |
integer, required | Puzzle size |
-t, --total |
integer | Total mines |
-c, --rules |
string list | All rule names, such as 2F 1Q V 1K 1F; they are automatically grouped into left/middle/right rules |
-E, --early-rules |
string list | Extra left-rule names used only during the initial generation phase; multiple allowed |
-d, --dye |
string | Dye rule name, such as @c |
-m, --mask |
string | Mask dye rule name, such as @c |
-r, --used-r |
flag | Enable R deduction (disabled by default) |
-a, --attempts |
integer | Maximum number of generation attempts |
-q, --query |
string range | Clue-count filter, such as 5-8, -8, or 5 |
-e, --early-stop |
flag | Stop early when the query target is reached (may produce an incorrect clue board) |
-v, --vice-board |
flag | Allow removing vice-board information during generation |
-T, --test |
flag | Generate only one answer board using the rules |
-S, --seed |
integer | Random seed (setting it explicitly forces attempts to 1) |
-O, --onseed |
flag | Use a reproducible seed for generation; this is slower |
-L, --log-lv |
string | Log level, such as DEBUG, INFO, or WARNING |
-B, --board-class |
string | Board class / board name; the default is usually fine |
-I, --no-image |
flag | Do not generate images |
-F, --file-name |
string | Output file name prefix |
-D, --dynamic-dig-rounds |
integer | Dynamic clue-removal rounds (auto-detected when omitted) |
-M, --dynamic-dig-max-batch |
integer | Maximum number of cell changes per dynamic clue-removal round |
--output-path |
string | Output directory for generated images |
--log-path |
string | Output directory for logs |
--lang |
string | Output language code, for example en_US or zh_CN |
list |
Show all implemented rule documentation |
run -s 5 -c 2F 1k 1q V -d c -r -q 2-4 -I
# Example with extra left-rule names during initial generation only
run -s 5 -c 1Q V -E 2F 3L -IGenerate a 5x5 board with checkerboard dyeing, using 2F and 1Q as left rules, and V and 1K as right rules. Enable R deduction, keep only boards whose clue count is between 2 and 4, and disable image output. Note: rule names are case-insensitive.
Additional options for list:
| Option | Type | Description |
|---|---|---|
--json |
flag | Output rule documentation as JSON |
Successful runs create the following files under output/:
output/
├─ output.png (default image output from img)
├─ demo.txt (historical deduction text)
├─ demo.png (puzzle image)
└─ answer.png (solution image)
demo.txt contains:
- Generation time
- Clue table, when
-qis used - Time spent generating
- Total mines, formatted as total mines / total cells
- Seed / puzzle ID as an integer string
- Puzzle content
- Solution and non-question-mark content
- The generated command for the puzzle image, prefixed with
img - The generated command for the answer image
img [arguments]This invokes the image output subcommand.
| Option | Type | Description |
|---|---|---|
-c, --code |
string | Board bytecode representing fixed board content |
-r, --rule-text |
string | Rule string; quote it if it contains spaces |
-s, --size |
integer | Cell size |
-o, --output |
string | Output file name without extension |
-w, --white-base |
flag | Use a white background |
-b, --board-class |
string | Underlying board class; the default is usually fine |
img -c ... -r "[V]-R*/15-4395498" -o demo -s 100 -wGenerate an image using
[V]-R*/15-4395498as the bottom text and save it tooutput/demo.png. Each cell is 100x100 pixels on a white background.
Note: replace
...with the board code value, which is saved inoutput/demo.txt.
The full developer documentation lives in the doc/ directory:
| Document | Description |
|---|---|
| README.md | Entry point |
| dev/rule_mines.md | Left-rule interface documentation |
| dev/rule_clue_mines.md | Middle-rule interface documentation |
| dev/rule_clue.md | Right-rule interface documentation |
| dev/board_api.md | Board structure and coordinate system |
| dev/utils.md | Utility module interface |