@zwolfrost/minesweeper.js NPM

minesweeper.js

An efficient Minesweeper class-based engine that can be used to easily create minefields and play without having to code any logic (UI-indipendent). Here's what you can do using it.

All versions are written in vanilla javascript (ES12) and have no dependencies.

Some of the most notable capabilities:

Lots of useful logic methods such as "openCell" and "getHint" (see below their use);
Minefield Auto-Solving Algorithm (useful when wanting to make no-guess minefields);
Current minefield state methods (it's going on, it's over etc.);
Possibility to switch from a 1D-Array Minefield to a 2D-Array one depending on your taste;

Versions

Version	Methods Available	JSDOC Documentation	Minification
minefield.js	All methods	:heavy_check_mark:	:x:
minefield.min.js	All methods	:x:	:heavy_check_mark:
minefield.slim.js	Only toMinefield2D and simplify (for both classes)	:x:	:heavy_check_mark:

How to install

You can just install it like any npm package, npm i @zwolfrost/minesweeper.js use a cdn or copy the file from the src directory.

Changelog and Breaking Changes (as of v2.0.0)

Watch out for this section if you wish to migrate to a different version. New patches are usually bugfixes and/or documentation clarifications and only meaningful ones are written.

v2.0.0: Added Minefield2D Object. The "rows" and "cols" parameters and properties were replaced with "width" and "height" for understanding purposes. (rows, cols, ...) ➜ (width, height, ...)
v2.1.0: Added "getSquareZone" method. The "x" and "y" parameters were changed to stay both in an array when passing them to methods. (x, y, ...) ➜ ([x, y], ...)
v2.2.0: Re-added "simplify" method and a slim version of the package.
v2.3.0: Changed behaviour of the "forEachCell" and "simplify" methods. See JSDOC documentation for details.
- v2.3.4: The imports' usage was finally corrected and the type of the package is specified in package.json (module).

How to use

Note that you can change the cdn version and/or package type of the library with whatever version you want. Template:

https://cdn.jsdelivr.net/npm/package@version/file.

Also note that you have to use an ES module to import as seen below, unless you want to use the CDN method

import Minefield from "@zwolfrost/minesweeper.js";
//OR
import Minefield from "https://cdn.jsdelivr.net/npm/@zwolfrost/minesweeper.js@2.3/src/minesweeper.js";

let minefield = new Minefield(2, 5, 3);

Creates a 2x5 minefield with 3 mines, which is an object containing:

width: The minefield width (n. of columns)
height: The minefield height (n. of rows)
cells: The minefield total cells number
mines: The minefield total mines number
[0...9]: Each minefield cell on its index (2x5 thus 0 to 9 in this case)
- [0...9].isOpen: Whether a cell is revealed
- [0...9].isMine: Whether a cell is a mine
- [0...9].isFlagged: Whether a cell is flagged
- [0...9].mines: Number of mines present around a cell

let minefield2d = minefield.toMinefield2D();

Creates a Minefield2D Object that is very similar to a Minefield one with the only difference being that, instead of having cells in the same array, the minefield is like a 2D Array.

[0][0...4].isOpen, isMine, ecc.
[1][0...4].isOpen, isMine, ecc.
width, height, ecc.

Minefield Object Methods

Note that the methods are fully documented in the JSDOC methods comments

Method	Description	Parameters
new Minefield	Creates a "Minefield" Object.	The width of the minefield (n. of columns).The height of the minefield (n. of rows).The mines number/placements.An optional randomizer that is useful in case you want to make a seed system (default: Math.random).
toMinefield2D	Returns a "Minefield2D" Object, based on your "Minefield" Object. Note that the two share the same addresses to the same cells, so a change on one will reflect on the other.
simplify	Returns a Number-Only array version of the minefield.
openCell	Opens a given cell and may open nearby ones following the minesweeper game rules. Returns the index of cells updated by this operation.	The index of the cell to open.A boolean value "firstclick" that indicates whether the method is executed on a new game or not (default: isNew()). If it's true, and a bomb is opened, it will be moved in another cell starting from 0.A boolean value "nearbyOpening" that enables the opening of nearby cells if the given cell is already open and its nearby mines number matches the number of nearby flagged cells (default: true).A boolean value "nearbyFlagging" that enables the flagging of nearby cells if the given cell is already open and its nearby mines number matches the number of nearby closed cells (default: true).
isSolvableFrom	Returns a Boolean value that indicates whether the game is solvable from a given cell (by not guessing).	The index of the cell where to start.A boolean value "restore". If true, the minefield will be fully re-closed after the method's execution (default: true).
getHint	Returns an Array of indexes of hint cells about a minefield's state.	A boolean value "accurateHint" that indicates whether the hint will be the exact cells or more "in the area" (default: false).Another optional boolean value "getOneHint" that indicates whether to return only an hint (1D array) or more (2D array) (default: true).
resetMines	Resets the nearby-mines number for each cell in the current minefield.
forEachCell	Executes a given function for every cell (passing them as parameters along with the corresponding index, like a forEach).	A function to execute for each cellA boolean value "returnValue". If true, the loop breaks whenever the given function returns a value that is not undefined and returns that value (default: false).A boolean value "giveIndex". If false, the method will replace the index of the cell with its corresponding coordinates (default: true).
getNearbyCells	Returns an Array containing the indexes of the cells directly around the given one.	The index of the desired cell.A boolean value "includeSelf". If true, the index of the given cell will also be included (default: false).
getEmptyZone	Returns an Array containing the indexes of the empty cells zone starting from the given one.	The index of the cell where to start.A boolean value "includeFlags". If true, the flagged cells will be included in the result (default: false).
getSquareZone	Returns an Array containing the indexes of all the square zone cells starting and ending at the specified indexes.	The starting index "begIndex" of the square zone.The ending index "endIndex" of the square zone.
getCellCords	Returns an Array that contains the X and Y cords of the desired cell.	The index of the desired cell.
getCellIndex	Returns a Number that indicates the index of the cell that is in the specified X and Y coordinates.	The x and y coordinate of the desired cell (in an array).
isNew	Returns a Boolean value that indicates whether the game is new (before the first move).
isGoingOn	Returns a Boolean value that indicates whether the game is going on (after the first move, before game over).
isOver	Returns a Boolean value that indicates whether the game is over (both cleared or lost).
isCleared	Returns a Boolean value that indicates whether the minefield has been cleared (no mines opened).
isLost	Returns a Boolean value that indicates whether a mine has been opened in the current minefield.
visualDebug	Console logs the minefield in a visual way.	A boolean value "allsee". If true, every cell will be showed as if they were open (default: false)
usedFlags	(getter) A Number that indicates the used flags in the current minefield.

Minefield2D Object Methods

The Minefield2D Methods are functionally the same as the Minefield ones.

Only differences:

Every index, that being parameter or result, is changed with X and Y coordinates in an array;
The "toMinefield2D" method is replaced with "toMinefield";
The "simplify" method returns a 2D Array instead of a 1D one.