Minesweeper in clojure

Minesweeper in clojure

I have been working my way through the Coding Train Coding Challenges videos on YouTube. So far they have been quite informative and entertaining. There is something about combining math and graphics that has grabbed my attention and I have started to play around with building drawings and games using p5.js and clojurescript. Daniel Shiffman does an excellent job in presenting and producing these videos and I suggest you go and check them out.

Daniel typically does these challenges in a javascript object oriented style. I have been keen for a while to replicate these challenges using Functional Programming (via Clojure/Clojurescript) and this is the first attempt. In doing this I hope to 1. have fun and 2. get people excited about Clojure. Clojure has turned everything I believed about software on its head and I am a better developer because of it. I am also having lots of fun.

I'll be building a minesweeper clone. You should go and watch the minesweeper coding challenge as this will give you a nice idea of how the OO and FP paradigm differ. Below is a tiny demo of the game (shift click to flag) and you can go and play the full version here.

Update: This post made it to the front page of hackernews. Head there for some nice conversation in the comments section.

Let's build!

Clojure is a dynamic functional hosted lisp. The lisp syntax might be trippy if you come from curly bracket land, but in essence it is always(my-function arg1 arg2 ...) ... for everything ... ever. Clojure is functional and its core data structures are persistant, so we will be focusing on building the core minesweeper functionality using pure functions that operate on immutable data. Once this is done we will add a state handling mechanism and finally the drawing of the game on the screen. This is typically how we build functional applications. We have a stateful outer layer that calls into a functional inner layer. Like a metaphorical functional sandwich. Yummy!

Before I start writing any code I first want to talk about what I want my data to look like. Minesweeper is essencially just rows and columns of cells. Although I can identify each cell by its row and column, I would prefer to give each cell an index and have my entire board represented as a hash-map of indexes to cells. This allows me to easily do value lookups and updates. Because the basic board state does not change during the game, I can initialize the cells with all the information about their neighboring cells so I can avoid having to iterate the cells when I need to check bomb locations etc. My core grid data structure then ends up looking like this:

{0 {:i 0 :row 0 :col 0
    :type :empty
    :flagged? false
    :opened? false
    :neighbors [1 5 6]
    :bombs-touching 0
 1 {:i 1 :row 0 :col 1 :type ..}
 2 {:i 2 :row 0 :col 2 :type ..}}

Now that I have an idea of what the data is going to look like, I can start creating and combining functions to build up the board state. The first thing I want to be able to do is to convert an index to a row and column and vice versa.

(defn position
  "given the grid width and index, returns a vector containing column and row"
  [col-count i]
  (let [col (mod i col-count)
        row (/ (- i col) col-count)]
    [col row]))

(defn index
  "given the grid width and the row and column, returns the index"
  [col-count row col]
  (+ col (* row col-count)))

With that out of the way we can write a simple function that, given a grid width and an index, will create an empty cell.

(defn cell [col-count i]
  (let [[col row] (position col-count i)]
    {:i        i :row row :col col
     :type     :empty
     :flagged? false
     :opened?  false}))

Creating the board

At the start of each game we want to initialize a new board. This is done in three simple steps.

  1. Initialize the grid with empty cells
  2. Randomly place some bombs
  3. Calculate the number of bombs each cell is touching

Initializing the grid is fairly simple. We simply calculate the number of cells, create a list of indexes from 0 to size-1 using range, map over this list and create an empty cell for each index and finally, using juxt and into, create the hash-map structure we defined above. The threading macro ->> helps us keep the code nice and readable.

(defn init-cells [row-count col-count]
  (let [size (* row-count col-count)]
    (->> (range size) ; => (0 1 2 ... size-1)
         (map #(cell col-count %)) ; => ({:i 0 :row ..} {:i 1 :row ..} ...)
         (map (juxt :i identity))
         (into {}) ; => {0 {:i 0 :row ..} 1 {:i 1 :row ..} ...})))

To randomly place bombs on the existing grid, we will create a loop that counts down from the number of bombs to zero. For every iteration we will randomly pick one of the empty cells and set its type to :bomb. That cell gets removed from the set of empty cells and we go back to the start of the loop until all bombs are placed. Recursion is the functional/immutable worlds answer to for loops that update state as part of their body. We use recur for non-stack-consuming looping.

(defn place-bombs [bomb-count cells-map]
  (loop [bomb-count  bomb-count
         empty-cells (set (keys cells-map))
         result      cells-map]
    (if (<= bomb-count 0)
      (let [random-index (rand-int (count empty-cells))
            bomb-index   (nth (vec empty-cells) random-index)]
         (dec bomb-count) ; bomb-count - 1
         (disj empty-cells bomb-index) ; remove index from empty cells
         (assoc-in result [bomb-index :type] :bomb) ; update cell at index

For each cell, we want to know how many of their adjacent cells contains bombs. We will do this using two functions. The first function, neighbors, is a helper function that, given a cell, returns all the indexes of that cell's neighbors. The set-neighbors function will map over our cells and for each cell set its neighbors, count its adjacent bomb cells and change the type of the cell if it is bomb adjacent.

(defn neighbors
  "Calculates the indexes of a cell' neighbors"
  [row-count col-count cell]
  (let [{:keys [i row col]} cell
        row- (dec row)
        row+ (inc row)
        col- (dec col)
        col+ (inc col)
        neighbors [[col- row-] [col row-] [col+ row-]
                   [col- row]             [col+ row]
                   [col- row+] [col row+] [col+ row+]]]
    (->> neighbors
         (filter (fn [[col row]] ; remove out of bounds cells
                   (and (>= row 0) (>= col 0)
                        (< row row-count) (< col col-count))))
         (map (fn [[col row]] ; get the neighbor cell index
                (index col-count row col))))))

(defn set-neighbors
  "Calculates bomb adjacent cell totals and updates cell types if bomb adjacent"
  [row-count col-count cells-map]
  (->> cells-map
       (map (fn [[i cell]]
              (let [neighbors (neighbors row-count col-count cell)
                    bombs-touching (->> neighbors ; count adjacent bombs
                                        (filter #(= :bomb (get-in cells-map [% :type])))
                 (assoc cell
                        :neighbors neighbors
                        :bombs-touching bombs-touching
                        :type (cond
                                (= :bomb (:type cell)) :bomb
                                (> bombs-touching 0)   :bomb-adjacent
                                :else                  (:type cell)))])))
       (into {})))

Finally we can compose our above functions into a single, board generating, function.

(defn board [row-count col-count bomb-count]
  (->> (init-cells row-count col-count)
       (place-bombs bomb-count)
       (set-neighbors row-count col-count)))

Handling game actions

Now that we have a board we want to be change the board state in a number of ways. We want to be able to:

  • toggle a cell as flagged
  • open a cell, which in turn will either
    • detonate a bomb, causing us to lose the game
    • open a cell that is bomb adjacent
    • open an empty cell and recursively open all other non bomb cells that are adjacent
  • check if we won the game

Let's start with the latter. We have won the game if all non-bomb cells have been opened:

(defn not-opened-non-bomb-cell? [cell]
  (and (false? (:opened? cell)) (not= :bomb (:type cell))))

(defn win? [board]
  (->> board
       (filter not-opened-non-bomb-cell?)

Flagging a cell is pretty straight forward. We simply negate the flagged? field:

(defn toggle-cell-flag [board i]
  (update-in board [i :flagged?] not))

Opening a cell that is adjacent to a bomb is also easy mode

(defn open-adjacent-cell [board i]
  (assoc-in board [i :opened?] true))

As is detonating a bomb. Detonating a bomb opens all cells to reveal the entire board

(defn detonate [board {:keys [i] :as cell}]
  (->> board
       (map (fn [[i cell]]
              [i (assoc cell :opened? true)]))
       (into {})))

Opening a cell that is not touching a bomb cell is slightly less trivial. We want to recursively check the neighbors of this cell and the neighbors neighbors, and if they are not bombs, we want to open them. We use the adjacent-open-cells function to get all the cells we need to open and then we simply reduce that list over the board and open the cells. (I'm sure a better way to do this exists, but I only have so many hours in the day ¯\_(ツ)_/¯ )

(defn adjacent-open-cells
  [board i]
  (loop [cells-to-check #{i}
         cells-checked  #{}
         cells-to-open  []]
    (if (empty? cells-to-check)
      (let [i (first cells-to-check)
            {:keys [neighbors opened?] :as cell} (get board i)
            t (:type cell)
            should-open? (and (not= :bomb t) (not opened?))]
        (if-not should-open?
          (recur (disj cells-to-check i)
                 (conj cells-checked i)
          (let [cells-not-to-check (into cells-checked cells-to-check)
                neighbors-to-add  (when (= :empty t)
                                     (filter #(not (contains? cells-not-to-check %))  neighbors))]
            (recur (into (disj cells-to-check i) neighbors-to-add)
                   (conj cells-checked i)
                   (conj cells-to-open i))))))))

 (defn open-empty-cell [board i]
   (fn [b i] (open-adjacent-cell b i))
   (adjacent-open-cells board i)))

And finally we compose all these functions together into a single function that allows us to open any cell.

(defn open-cell [{:keys [board] :as game} i]
  (let [cell   (get board i)
        bomb?  (= :bomb (:type cell))
        empty? (= :empty (:type cell))
          bomb?  (detonate board cell)
          empty? (open-empty-cell board i)
          :else  (open-adjacent-cell board i))
        win?   (win? next-board)]
    (merge game
           {:board next-board
            :dead? bomb?
            :win?  win?})))

You will notice that the open-cell function does not take a board hash-map as the other functions does, but a game hash-map. This is simply to allow us to define some general fields around our board that can be used by the consumer to determine various things. We call this state the game and we initialize a game using:

(defn new-game [rows cols bombs]
  {:board (board rows cols bombs)
   :win?  false
   :dead? false
   :rows  rows
   :cols  cols
   :bombs bombs
   :size  35})

Taking a step back

At this point, there are a few observations that I would like to make.

  • The above code is enough to run a game of minesweeper. A very naive way would be to recursively open cells until a bomb is found:
(defn run-game
  "Recursively open cells from index 0 until a bomb is found"
  (loop [index 0
         game (new-game 10 10 10)]
    (if (:dead? game)
      (str "You died at index " index)
       (inc index)
       (open-cell game index)))))

(run-game) ; => You died at index 9
  • All of the code above is expressed using pure functions, meaning that given an input we can always expect the same output. Nowhere are we mutating any state. All of the clojure data types we have used are immutable and persistent. This makes our code very easy to reason about and writing tests trivial.

  • All the code is valid clojure and clojurescript, meaning it will run on the jvm, node and in the browser without us having to make any changes. Technically it will run on the clr too using clojureclr, but I have not tried it. This is the power of a hosted language.

Can haz side effects?

Ultimately, any useful program will end up having some side effects, whether this is writing to disk or reacting to user input. Our game will be rendered in the browser using p5.js and the game state will be kept in a clojure atom. Every time the user clicks we will call a function that will run the current state through our functions and then save the new state in our atom. Our view render code can then simply query the state atom for the latest state. You can see in the mouse-clicked function how easily we interop with javascript and p5 by simply using js/.

(defonce *state (atom nil))

(defn reset-game []
  (let [{:keys [rows cols bombs]} @*state]
    (reset! *state (new-game rows cols bombs))))

(defn mouse-clicked []
  (let [{:keys [rows cols size]} @*state
        mx                       js/mouseX
        my                       js/mouseY
        in-bounds?               (and (pos? mx) (pos? my) (< mx (* size cols)) (< my (* size rows)))
        col                      (js/Math.floor (/ mx size))
        row                      (js/Math.floor (/ my size))
        i                        (index cols row col)
        shift-pressed?           (= 16 (when (js/keyIsDown 16) js/keyCode))
        dead?                    (:dead? @*state)
        win?                     (:win? @*state)
        f                        (cond
                                   (or dead? win?)  #(reset-game)
                                   (not in-bounds?) identity
                                   shift-pressed?   #(update % :board toggle-cell-flag i)
                                   :else            #(open-cell % i))]
    (swap! *state f)))

(defn easy-game []
  (reset! *state (new-game 10 10 10)))


Finally we can render our game to the screen. We initialize the board inside of p5.js's draw function and then "save" it in the *state atom. Then in the p5 draw function we iterate the items in the grid and draw them to screen, we use multimethods to draw open cells based on the type of cell.

(defonce *canvas (atom nil))

(defn setup
  (let [{:keys [rows cols size]} @*state
        canvas (js/createCanvas (+ 1 (* cols size)) (+ 1 (* rows size)))]
    (.parent canvas "game")
    (js/rectMode "CENTER")
    (reset! *canvas canvas)
    (add-watch *state "redraw" #(js/redraw))))

(defn draw-initial-cell
  (if (:win? @*state) (js/fill 0 255 0) (js/fill 240))
  (let [{:keys [size]} @*state]
    (js/rect 0 0 size size)))

(defn draw-flagged-cell
  (js/fill 255 150 0)
  (let [{:keys [size]} @*state]
    (js/ellipse (/ size 2) (/ size 2) (/ size 3) (/ size 3))))

(defn draw-empty-cell
  (js/fill 150)
  (let [{:keys [size]} @*state]
    (js/rect 0 0 size size)))

(defmulti draw-cell :type)

(defmethod draw-cell :empty [_] (draw-empty-cell))

(defmethod draw-cell :bomb
  (js/fill 255 0 0)
  (let [{:keys [size]} @*state]
    (js/ellipse (/ size 2) (/ size 2) (/ size 2) (/ size 2))))

(defmethod draw-cell :bomb-adjacent
  (js/fill (* 50 (:bombs-touching cell)) 0 0)
  (js/textSize 15)
  (let [{:keys [size]} @*state]
    (js/text (str (:bombs-touching cell)) (/ size 2.2) (/ size 1.5))))

(defn draw
  (let [{:keys [size board cols rows]} @*state]
    (.resize @*canvas (inc (* cols size)) (inc (* rows size)))
    (doseq [[i {:keys [row col flagged? opened?] :as cell}] board]
      (js/stroke 180)
      (js/translate (* col size) (* row size))
      (cond opened? (draw-cell cell)
            flagged? (draw-flagged-cell)
            :else (draw-initial-cell))

(doto js/window
  (aset "setup" setup)
  (aset "draw" draw)
  (aset "touchStarted" mouse-clicked))

To see the full implementation in one place you can jump over to the minesweeper page.


Implementing minesweeper we have seen the simplicity of expressing code using a set of pure functions. We simply define some data and then transform that data. We are also free of weird side effects and bugs because we rely on immutable data structures. This results in a codebase that is clean, concise and easy to reason about and maintain. To make the code usable we wrap our functional code in a stateful shell, allowing us to easily run our code anywhere we like, whilst maintaining integrity.

I hope you have found my clojure ramblings useful and I hope that I have planted a small seed of interest/curiosity in your brain that will compel you to have a look at functional programming and at clojure. Personally I have fallen in love with clojure. It is such an elegant and thought through language. Since moving to clojure I have 10X more fun writing code as well as completed many more side projects than I ever manged before. I would encourage you to go and play with clojure. Simply trying out things that you are not familiar with (like lisp, FP and immutability) will make you a better programmer.

note: I am pretty sure that the code above is not perfect, and if you are reading this as an experienced clojure developer, feel free to point that out in the comments below.

The source code for this post is available on github