Minesweeper

Customize the right-hand Minesweeper

Mine-clicks in the right-hand Minesweeper: 0

The what

Minesweeper is a JavaScript library that defines a Javascript object Minesweeper which can be easily embedded in any web page. It depends only on the (reasonably up-to-date) JavaScript engine; no APIs nor other libraries are required.

Minesweeper is a well know game and this one follows the well-known rules as much as possible: you can click on the tiles to “visit” them and you can flag the tiles by right-clicking them. If you double-click or right-click on a tile with the number x on it (meaning it has x mines among its 8 neighbor tiles) and exactly x of its neighbors are flagged, the non-flagged fields shall be automatically “visited”. The same happens if you “visit” a tile with no mines around it.

The only differences to the standard implementations of the game are nonexistent middle-click (as some browsers have trouble coping with it, so the right- and the double-click have taken this role) and the option “Easy start” which, when turned on, makes sure that the first clicked tile will have no mines among its neighbors.

Anyone really hooked up on the game might want to visit Authoritative Minesweeper.

The package

So, hours after getting here and playing the two Minesweepers above (yes, they are playable, not just screenshots), your curiosity probably got the best of you and you have clicked the above link. In other words, you have most likely downloaded the ZIP package and in it you will find the following marvelous things:

1. minesweeper.js – the JavaScript file with the Minesweeper object definition,
2. minesweeper.css – the CSS file with the default styles' definitions (including images),
3. index.html – a sample file that shows how is this used (or you can just view this page's source instead).

The how

“Installing” this script is easy. You just need to:

1. Unpack it.
2. Include it in your document's head:
   <script type="text/javascript" src="minesweeper.js"></script> <link rel="stylesheet" href="minesweeper.css" type="text/css" />
   (Syntax colored by Online syntax highlighting)
3. Add the container somewhere in the document's body:
   <div id="minesweeper"></div>
4. Invoke it when the document loads, providing the constructor with the container element:
   new Minesweeper("minesweeper");
   As the parameter, you can either use the element's name (like in the above example) or the JavaScript variable referring to the element.

And that's it! A completely functional JavaScript Minesweeper for your web page, no Flash, Java, big libraries, APIs,... no nothing! Of course, many customizations are available...

CSS

Just check the CSS file in your downloaded package and you should be fine. Also, “Inspect element” function in Firefox and Chrome might help you quite a bit (I recommend the one in Firefox, as it is visually easier and more intuitive for use).

Events

The game offers several events you might want to use. One of them, onOpenTiles(row, col), is used on this page to display the number of “Mine-clicks in the right-hand Minesweeper” in this page, so you may check the source code of this page to see how to use this. The currently supported events are:

• onGameEnd() – Kinda self descriptive, isn't it?
• onGameLost() – Invoked after the onGameEnd(), in case the player was not very successful.
• onGameWon() – Invoked after the onGameEnd(), in case the game was won.
• onNewGame() – Can you guess when is this one invoked?
• onOpenTile(row, col) – Invoked whenever a tile is uncovered (either through a click or via automatic opening around the tiles with no mines on the neighbor tiles).
• onOpenTiles(row, col) – Invoked whenever the player requests that the tile is opened (either by clicking on it, or by right-click or double-click on the numbered tile with all of its mines flagged). Even if this triggers an automatic opening of many tiles, the event is still invoked only once.
• onTileClick(row, col) – Invoked whenever a tile is clicked, no matter what state it is in.

If you need some more, feel free to drop me a line and I might add it.

An interesting methodology

Apart from the constructor itself, there are several methods you might want to call from somewhere in your page:

• attachPrefs(div) – use div as a container for the preferences dialog box.
• getScore() – Returns an object with the following properties: easy (true if the game was “easily” started; false otherwise), m (the number of the rows), mines (the number of the mines), n (the number of the columns) and time (the number of the seconds the game was played).
  This can be particularly useful for the implementation of the hall of fame (most likely with the use of JSON and some server side scripting).
• init(m, n, cnt, easyStart) – Initialize the board with m rows, n columns and cnt mines. The fourth parameter, easyStart, is a Boolean value (true or false). If it is true, the first clicked tile will have no mines among its neighbors.
  The default values are: init(9, 9, 10, true);.
  This was used with the non-default values for the initialization of the right-hand side Minseweeper above.
• prefs() – Open the preferences (“New game”) dialog box.
  This was used above as the part of the click-event listener for the “Customize the right-hand Minesweeper” option.

A special offer

Only the first seventeen billion unique visitors of this page can also get the ms-bg.zip file containing the minesweeper.pl – a PERL program which, using PerlMagick, creates random Minesweeper backgrounds (like the one used on this page).

In case you do not see this section, you're obviously not among the first seventeen billion unique visitors of this page and we wish you better luck on some less populated planet.

Why does this page look like... this?

I needed a page to provide the download link and the basic info on the Minesweeper class. I am not charging for this or anything like it, as the purpose of both the script and the page is educational. So, I thought I'd have a bit of fun with the CSS and the background image. It's unprofessional... deliberately. Or I just suck at the web page design and am only making excuses here. You'll never know.

By the way, when was the last time you've seen a horizontal rule at the end of a web page? And what about the <address> tag? Ah, the good ol' days...

Feel free to use the script on your non-commercial pages, but please attribute me properly, as described in the script file.
Vedran Šego <>