MinesweeperVariants

简体中文

To browse rules, visit the Minesweeper Variants Rule List For the front-end project, use Minesweeper Variants-Vue

Version 1.3

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.

Installation

Requirements

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.

Install with pip

python -m pip install --upgrade pip
python -m pip install minesweepervariants

Running

There 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 minesweepervariants

You can add command-line options such as -s for size and -t for total mines. See the examples and options below.

Development Setup

Poetry is recommended for dependency management and environment setup.

1. Install Python 3.13

On Windows, download the official installer from https://www.python.org.

2. Install Poetry

Follow the official installation guide: https://python-poetry.org/docs/#installation

3. Install dependencies and create a virtual environment

From the project root:

poetry install

Poetry will create an isolated virtual environment and install all dependencies automatically.

4. Run the project

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>.

5. C extension build tools on Windows

Some dependencies may require compiled C extensions. Install:

• Visual C++ Build Tools

Download it from:

https://visualstudio.microsoft.com/visual-cpp-build-tools/

Make sure these components are selected:

• C++ build tools, including MSVC and the Windows SDK
• CMake

Restart the terminal after installation.

Usage

Run command

run [arguments]

This invokes the main generator.

Common run options

Example runs

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 -I

Generate 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:

Output files

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 -q is 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

Image output command

img [arguments]

This invokes the image output subcommand.

img options

Example image command

img -c ... -r "[V]-R*/15-4395498" -o demo -s 100 -w

Generate an image using [V]-R*/15-4395498 as the bottom text and save it to output/demo.png. Each cell is 100x100 pixels on a white background.

Note: replace ... with the board code value, which is saved in output/demo.txt.

Developer documentation

The full developer documentation lives in the doc/ directory: