In this series, we'll build a fully functional Minesweeper game from scratch, giving you hands-on experience with game development concepts and C++ programming.

We'll separate our project into two main parts:

An "Engine" module containing components that are generally useful across a wide range of projects, not specific to Minesweeper.
A Minesweeper-specific module that builds upon our engine to create the actual game.

For example, we'll create a general Button class in our engine that can be used across various projects. The cells of our Minesweeper grid will then inherit from this Button class, expanding it with Minesweeper-specific logic such as whether the cell contains a bomb and counting the number of bombs in adjacent cells.

This separation offers several benefits:

We can reuse the engine code across other projects, saving time and effort in future game development.
It provides a logical separation of concerns, allowing us to keep our classes smaller and more focused.
As we add new features to our project, that generally involves adding new methods and variables to our classes. By approaching this thoughtfully, we can add generally useful methods to the base engine classes rather than the specific Minesweeper classes.

Over time, this approach will make our generic engine code more powerful, which future projects can also benefit from. It's a great way to build a personal library of reusable game components.

In this lesson, we'll introduce all of the engine code. While it might seem like a lot of code at first, you'll find that it's all built on concepts we've covered in previous sections of the course. Don't worry if you feel overwhelmed - future lessons will slow down and take things step by step as we build the new, Minesweeper-specific functionality.

Let's dive in and explore our starting point

The `Globals.h` File

We'll start by creating a Globals.h header file to store variables and functionality that are useful across a wide variety of files in our project. This includes:

Custom SDL event types, which we'll store in the UserEvents namespace. This namespace is currently empty, but we'll add to it as needed in future parts of the tutorial.
General configuration options that we might want to change that are stored in the Config namespace. This includes settings like the game name, window dimensions, and color schemes.
Generally useful free functions that can be used across various files that are stored in the Utils (utilities) namespace.

An important feature to note is the SHOW_DEBUG_HELPERS definition. This definition enables extra functionality that will be useful when we're developing and debugging the project. For example, it allows us to use the Utils::CheckSDLError function to print detailed error messages during development.

By organizing our global definitions and utilities in this way, we create a central place for important constants and helper functions, making our code more organized and easier to maintain.

1#pragma once
2
3#define SHOW_DEBUG_HELPERS
4
5#include <iostream>
6#include <SDL.h>
7#include <string>
8
9namespace UserEvents{}
10
11namespace Config{
12  // Game Settings
13  inline const std::string GAME_NAME{
14    "Minesweeper"};
15
16  // Size and Positioning
17  inline constexpr int WINDOW_HEIGHT{200};
18  inline constexpr int WINDOW_WIDTH{400};
19
20  // Colors
21  inline constexpr SDL_Color BACKGROUND_COLOR{
22    170, 170, 170, 255};
23  inline constexpr SDL_Color BUTTON_COLOR{
24    200, 200, 200, 255};
25  inline constexpr SDL_Color BUTTON_HOVER_COLOR{
26    220, 220, 220, 255};
27
28  // Asset Paths
29  inline const std::string FONT{
30    "Rubik-SemiBold.ttf"};
31}
32
33namespace Utils{
34#ifdef SHOW_DEBUG_HELPERS
35  inline void CheckSDLError(
36    const std::string& Msg){
37    const char* error = SDL_GetError();
38    if (*error != '\0') {
39      std::cerr << Msg << " Error: " << error <<
40        '\n';
41      SDL_ClearError();
42    }
43  }
44#endif
45}

Note that the CheckSDLError() function in this file is something we created in our earlier lesson on error handling:

Detecting and Managing Errors

Discover techniques for detecting and responding to SDL runtime errors

View Related Lesson

The `Engine/Window.h` File

The first component of our engine is the Window class, which is responsible for creating and managing SDL_Window objects. This class, like all our engine components, is stored within the Engine namespace and located in the Engine/ directory of our project.

The Window class provides the following functionality:

A constructor that creates an SDL window using the configurations defined in our Globals.h file.
A Render method that fills the window with the background color.
An Update method that refreshes the window surface.
A GetSurface method that returns the SDL surface associated with the window.

This class encapsulates all the basic window management functionality we'll need for our game, providing a clean interface for creating and manipulating our game window:

1#pragma once
2#include <SDL.h>
3#include "Globals.h"
4
5namespace Engine{
6class Window {
7public:
8  Window(){
9    SDLWindow = SDL_CreateWindow(
10      Config::GAME_NAME.c_str(),
11      SDL_WINDOWPOS_UNDEFINED,
12      SDL_WINDOWPOS_UNDEFINED,
13      Config::WINDOW_WIDTH,
14      Config::WINDOW_HEIGHT,
15      0
16    );
17  }
18
19  void Render(){
20    SDL_FillRect(
21      GetSurface(), nullptr,
22      SDL_MapRGB(GetSurface()->format,
23                 Config::BACKGROUND_COLOR.r,
24                 Config::BACKGROUND_COLOR.g,
25                 Config::BACKGROUND_COLOR.b));
26  }
27
28  void Update(){
29    SDL_UpdateWindowSurface(SDLWindow);
30  }
31
32  SDL_Surface* GetSurface(){
33    return SDL_GetWindowSurface(SDLWindow);
34  }
35  
36  ~Window() {
37    if (SDLWindow && SDL_WasInit(SDL_INIT_VIDEO)) {
38      SDL_DestroyWindow(SDLWindow);
39    }
40  }
41  
42  Window(const Window&) = delete;
43  Window& operator=(const Window&) = delete;
44
45private:
46  SDL_Window* SDLWindow;
47};
48}

This Window class is similar to what we created in our earlier lesson on SDL windows:

Creating a Window

Learn how to create and customize windows, covering initialization, window management, and rendering

View Related Lesson

The `Engine/Rectangle.h` File

The Rectangle class is a fundamental building block in our engine, used for drawing rectangles on the screen. It provides the following key features:

A constructor that takes position (x, y), dimensions (width, height), and an optional color.
A virtual Render method for drawing the rectangle on an SDL surface.
Methods for setting the color and checking if a point is within the rectangle's bounds.
A virtual destructor, allowing for proper cleanup in derived classes.

This class will serve as the base for more complex visual elements in our game, such as buttons and cells in the Minesweeper grid.

1#pragma once
2#include <SDL.h>
3
4namespace Engine{
5  class Rectangle {
6  public:
7    Rectangle(
8      int x, int y, int w, int h,
9      SDL_Color Color = {0, 0, 0, 255})
10      : Rect{x, y, w, h}, Color{Color}{}
11
12    virtual void Render(SDL_Surface* Surface){
13      SDL_FillRect(
14        Surface, &Rect, SDL_MapRGB(
15          Surface->format, Color.r, Color.g,
16          Color.b
17        )
18      );
19    }
20
21    void SetColor(SDL_Color C){ Color = C; }
22
23    bool IsWithinBounds(int x, int y) const{
24      // Too far left
25      if (x < Rect.x) return false;
26      // Too far right
27      if (x > Rect.x + Rect.w) return false;
28      // Too high
29      if (y < Rect.y) return false;
30      // Too low
31      if (y > Rect.y + Rect.h) return false;
32      // Within bounds
33      return true;
34    }
35
36    SDL_Rect* GetRect(){ return &Rect; }
37
38    virtual ~Rectangle() = default;
39
40  private:
41    SDL_Rect Rect{0, 0, 0, 0};
42    SDL_Color Color{0, 0, 0, 0};
43  };
44}

This Rectangle class is similar to what we created in our earlier lesson when we started creating UI elements for SDL:

Structuring SDL Programs

Discover how to organize SDL components using manager classes, inheritance, and polymorphism for cleaner code.

View Related Lesson

The `Engine/Button.h` File

Building upon the Rectangle class, the Button class adds interactivity to our visual elements. It includes:

A constructor that sets up a button with a given position and size.
A virtual HandleEvent method for processing SDL events related to the button.
Protected virtual methods for handling left clicks, right clicks, and mouse motion.
A method to disable/enable the button.

The use of virtual methods here is crucial for extensibility. By declaring these methods as virtual, we enable derived classes to override them, allowing us to implement Minesweeper-specific behavior without modifying the base Button class. This adheres to the Open-Closed Principle of object-oriented design.

For example, we'll be able to create a custom cell class for our Minesweeper grid that inherits from Button and implements its own behavior for clicks and mouse movement.

1#pragma once
2#include "Globals.h"
3#include "Engine/Rectangle.h"
4
5namespace Engine{
6  class Button : public Rectangle {
7  public:
8    Button(int x, int y, int w, int h)
9      : Rectangle{x, y, w, h}{
10      SetColor(Config::BUTTON_COLOR);
11    }
12
13    virtual void
14    HandleEvent(const SDL_Event& E){
15      if (isDisabled) return;
16      if (E.type == SDL_MOUSEMOTION) {
17        HandleMouseMotion(E.motion);
18      } else if (E.type ==
19        SDL_MOUSEBUTTONDOWN) {
20        if (IsWithinBounds(E.button.x,
21                           E.button.y)) {
22          E.button.button == SDL_BUTTON_LEFT
23            ? HandleLeftClick()
24            : HandleRightClick();
25        }
26      }
27    }
28
29    void SetIsDisabled(bool NewValue){
30      isDisabled = NewValue;
31    }
32
33  protected:
34    virtual void HandleLeftClick(){}
35    virtual void HandleRightClick(){}
36
37    virtual void HandleMouseMotion(
38      const SDL_MouseMotionEvent& E){
39      if (IsWithinBounds(E.x, E.y)) {
40        SetColor(Config::BUTTON_HOVER_COLOR);
41      } else { SetColor(Config::BUTTON_COLOR); }
42    }
43
44  private:
45    bool isDisabled{false};
46  };
47}

This Button class is similar to what we created in our earlier lesson:

Creating SDL2 Buttons

Learn to create interactive buttons in SDL2 and manage communication between different UI components.

View Related Lesson

The `Engine/Image.h` File

The Image class allows us to display images in our game. This will be useful for showing icons like bombs and flags in our Minesweeper grid. Key features include:

A constructor that loads an image from a file and applies padding.
An Render method that draws the image on the given surface.
Proper resource management with a destructor that frees the image surface.

This class demonstrates how we can extend our basic Rectangle to create more specialized visual elements.

1#pragma once
2#include <SDL_image.h>
3
4namespace Engine{
5  class Image {
6  public:
7    Image(
8      int x, int y, int w, int h,
9      const std::string& Filename,
10      int Padding = 12
11    ): Destination{
12      x + Padding/2, y + Padding/2,
13      w-Padding, h-Padding
14    }{
15      ImageSurface = IMG_Load(Filename.c_str());
16#ifdef SHOW_DEBUG_HELPERS
17      Utils::CheckSDLError("IMG_Load");
18#endif
19    }
20
21    void Render(SDL_Surface* Surface) {
22      SDL_BlitScaled(
23        ImageSurface,nullptr,
24        Surface, &Destination
25      );
26    }
27
28    ~Image() {
29      if (ImageSurface) {
30        SDL_FreeSurface(ImageSurface);
31      }
32    }
33
34    Image(const Image&){}
35
36  private:
37    SDL_Surface* ImageSurface{nullptr};
38    SDL_Rect Destination{0, 0, 0, 0};
39  };
40}

This Image class uses the techniques we covered in our introduction to images, surface blitting, and SDL_Image:

Loading and Displaying Images

Learn how to load, display, and optimize image rendering in your applications

View Related Lesson

The `Engine/Text.h` File

The Text class enables us to render text in our game. We'll use this for displaying numbers and other information in our Minesweeper grid. It provides:

A constructor that sets up the Text member variables, including a rectangle to determine where the text should be rendered within the destination surface.
SetText() methods to change the text content and color. These methods also update a TextPosition rectangle to ensure the text is rendered in the middle of the destination rectangle.
A Render method that draws the text on the given surface.
Proper resource management for the font and text surface.

1#pragma once
2#include <SDL_ttf.h>
3#include "Globals.h"
4
5namespace Engine{
6  class Text {
7  public:
8    Text(
9      int x, int y, int w, int h,
10      const std::string& Content,
11      SDL_Color Color = {0, 0, 0, 255},
12      int FontSize = 30
13    ) : DestinationRect{x, y, w, h},
14        Color{Color}
15    {
16      Font = TTF_OpenFont(
17        Config::FONT.c_str(), FontSize);
18#ifdef SHOW_DEBUG_HELPERS
19      Utils::CheckSDLError("TTF_OpenFont");
20#endif
21      SetText(Content);
22    }
23
24    void SetText(const std::string& Text){
25      SetText(Text, Color);
26    }
27
28    void SetText(const std::string& Text,
29                 SDL_Color NewColor){
30      if (TextSurface) {
31        SDL_FreeSurface(TextSurface);
32      }
33      Color = NewColor;
34
35      TextSurface = TTF_RenderUTF8_Blended(
36        Font, Text.c_str(), Color
37      );
38
39      auto [x, y, w, h] = DestinationRect;
40      // Horizontally centering
41      const int WidthDifference{
42        w - TextSurface->w};
43      const int LeftOffset{WidthDifference / 2};
44
45      // Vertically centering
46      const int HeightDifference{
47        h - TextSurface->h};
48      const int TopOffset{HeightDifference / 2};
49
50      TextPosition = {
51        x + LeftOffset, y + TopOffset, w, h
52      };
53    }
54
55    void Render(SDL_Surface* Surface) {
56      SDL_BlitSurface(
57        TextSurface, nullptr,
58        Surface, &TextPosition
59      );
60    }
61
62    ~Text() {
63      if (Font) { TTF_CloseFont(Font); }
64      if (TextSurface) {
65        SDL_FreeSurface(TextSurface);
66      }
67    }
68
69  private:
70    SDL_Surface* TextSurface{nullptr};
71    TTF_Font* Font{nullptr};
72    SDL_Rect DestinationRect{0, 0, 0, 0};
73    SDL_Rect TextPosition{0, 0, 0, 0};
74    SDL_Color Color{0, 0, 0, 255};
75  };
76}

This Text class uses the techniques we covered in our introduction to SDL_ttf:

Rendering Text with `SDL_ttf`

Learn to render and manipulate text in SDL2 applications using the official SDL_ttf extension

View Related Lesson

The `Engine/Random.h` File

Randomness is a crucial element in Minesweeper for generating unique game boards. We use it primarily to randomly place bombs on the grid, ensuring each game is different and challenging. The Random namespace encapsulates our random number generation logic, providing a simple interface for generating random integers within a specified range.

It sets up a random number generator using std::random_device and std::mt19937.
It provides an Int function to generate random integers within a specified range.

This abstraction will make it easy to add randomness to our game in a controlled and reusable manner.

1#pragma once
2#include <random>
3
4namespace Engine::Random{
5  inline std::random_device SEEDER;
6  inline std::mt19937 ENGINE{SEEDER()};
7
8  inline size_t Int(size_t Min, size_t Max){
9    std::uniform_int_distribution Get{Min, Max};
10    return Get(ENGINE);
11  }
12}

This Engine::Random namespace uses the techniques we covered in our introduction to the randomness utilities in C++:

Random Number Generation

This lesson covers the basics of using randomness, with practical applications

View Related Lesson

The `Minesweeper/UI.h` File

While most of the code we've looked at is part of our general-purpose engine, the MinesweeperUI class is our first Minesweeper-specific component. We're storing it in the Minesweeper/ directory to keep it separate from our engine code.

The MinesweeperUI class serves as the central point for managing all user interface elements specific to our Minesweeper game. It will be responsible for rendering the game board, handling user interactions, and updating the game state. For now, it contains placeholder Render and HandleEvent methods, which we'll implement in subsequent lessons to bring our Minesweeper game to life.

1#pragma once
2
3class MinesweeperUI {
4public:
5  void Render(SDL_Surface* Surface){
6    // ...
7  }
8
9  void HandleEvent(const SDL_Event& E){
10    // ...
11  };
12};

The `main.cpp` File

Finally, we have our main.cpp file, which sets up the main loop of our application. It initializes SDL and its subsystems (SDL_image and SDL_ttf), and creates our game window and UI objects.

It also contains the main game loop, which forms the core of our game's execution:

It continuously processes SDL events, allowing the game to respond to user inputs and other events we'll add in future lessons.
It calls the Render methods to draw the current game state.
It updates the display to show the newly rendered frame.

This loop runs repeatedly until we receive an SDL_QUIT event:

1#include <SDL_image.h>
2#include <SDL_ttf.h>
3
4#include "Globals.h"
5#include "Engine/Window.h"
6#include "Minesweeper/UI.h"
7
8int main(int argc, char** argv){
9  SDL_Init(SDL_INIT_VIDEO);
10#ifdef SHOW_DEBUG_HELPERS
11  Utils::CheckSDLError("SDL_Init");
12#endif
13
14  IMG_Init(IMG_INIT_PNG);
15#ifdef SHOW_DEBUG_HELPERS
16  Utils::CheckSDLError("IMG_Init");
17#endif
18
19  TTF_Init();
20#ifdef SHOW_DEBUG_HELPERS
21  Utils::CheckSDLError("TTF_Init");
22#endif
23
24  Engine::Window GameWindow;
25  MinesweeperUI UI;
26
27  SDL_Event Event;
28  bool shouldQuit{false};
29
30  while (!shouldQuit) {
31    while (SDL_PollEvent(&Event)) {
32      if (Event.type == SDL_QUIT) {
33        shouldQuit = true;
34      } else { UI.HandleEvent(Event); }
35    }
36    GameWindow.Render();
37    UI.Render(GameWindow.GetSurface());
38    GameWindow.Update();
39  }
40
41  SDL_Quit();
42  return 0;
43}

If the code in our main.cpp is unclear, reviewing the lesson on application loops is recommended:

Implementing an Application Loop

Step-by-step guide on creating the SDL2 application and event loops for interactive games

View Related Lesson

Assets

Our game will require some assets to function properly:

SDL libraries, which we covered in our earlier installation guides.
A font file for rendering text.
Images for our bomb and flag icons.

Feel free to use any assets you prefer. The assets used in our screenshots are:

Rubik-SemiBold.tff font from Google Fonts
Bomb image from IconFinder
Flag image from IconsDB

Remember, these assets should be located in the same directory as your compiled executable for the game to find them.

The `CMakeLists.txt` File

For those using CMake to manage their project, the following CMakeLists.txt file may be helpful.

This file sets up the project, adds the necessary source files, and links against the required SDL libraries. It also includes a command to copy the SDL DLLs and asset files to the output directory, ensuring that everything the game needs is in the right place when you run it.

1cmake_minimum_required(VERSION 3.16)
2
3set(CMAKE_CXX_STANDARD 20)
4
5project(Minesweeper VERSION 1.0.0)
6add_executable(Minesweeper
7  "main.cpp"
8  "Globals.h"
9  "Engine/Button.h"
10  "Engine/Rectangle.h"
11  "Engine/Image.h"
12  "Engine/Text.h"
13  "Engine/Window.h"
14  "Engine/Random.h"
15  "Minesweeper/UI.h"
16
17  # Files that will be added later:
18  # "Minesweeper/Grid.h"
19  # "Minesweeper/UI.h"
20  # "Minesweeper/Cell.h"
21  # "Minesweeper/Cell.cpp"
22  # "Minesweeper/NewGameButton.h"
23)
24
25target_include_directories(
26  Minesweeper PUBLIC ${PROJECT_SOURCE_DIR}
27)
28
29add_subdirectory(external/SDL)
30add_subdirectory(external/SDL_image)
31add_subdirectory(external/SDL_ttf)
32
33target_link_libraries(Minesweeper PRIVATE
34  SDL2
35  SDL2_image
36  SDL2_ttf
37)
38
39if (WIN32)
40  target_link_libraries(
41    Minesweeper PRIVATE SDL2main
42  )
43endif()
44
45# Copy DLLs and Assets to output directory
46set(AssetDirectory "${PROJECT_SOURCE_DIR}/Assets")
47add_custom_command(
48  TARGET Minesweeper POST_BUILD COMMAND
49  ${CMAKE_COMMAND} -E copy_if_different
50    "$<TARGET_FILE:SDL2>"
51    "$<TARGET_FILE:SDL2_image>"
52    "$<TARGET_FILE:SDL2_ttf>"
53    "${AssetDirectory}/bomb.png"
54    "${AssetDirectory}/Rubik-SemiBold.ttf"
55    "${AssetDirectory}/flag.png"
56    "$<TARGET_FILE_DIR:Minesweeper>"
57  VERBATIM
58)

Building SDL2 from a Subdirectory (CMake)

A step-by-step guide on setting up SDL2 and useful extensions in a project that uses CMake as its build system

View Related Lesson

Running the Application

At this point, you should be able to compile and run the application. When you do, you should see an empty window appear. This might not look like much, but it's the foundation upon which we'll build our game!

In the next part of this tutorial, we'll start adding Minesweeper-specific functionality to our program, bringing our game to life step by step.

Engine Overview

The `Globals.h` File

Detecting and Managing Errors

The `Engine/Window.h` File

Creating a Window

The `Engine/Rectangle.h` File

Structuring SDL Programs

The `Engine/Button.h` File

Creating SDL2 Buttons

The `Engine/Image.h` File

Loading and Displaying Images

The `Engine/Text.h` File

Rendering Text with `SDL_ttf`

The `Engine/Random.h` File

Random Number Generation

The `Minesweeper/UI.h` File

The `main.cpp` File

Implementing an Application Loop

Assets

The `CMakeLists.txt` File

Building SDL2 from a Subdirectory (CMake)

Running the Application

Creating the Grid

Game Development with SDL2

Questions & Answers

Engine Overview

The Globals.h File

Detecting and Managing Errors

The Engine/Window.h File

Creating a Window

The Engine/Rectangle.h File

Structuring SDL Programs

The Engine/Button.h File

Creating SDL2 Buttons

The Engine/Image.h File

Loading and Displaying Images

The Engine/Text.h File

Rendering Text with SDL_ttf

The Engine/Random.h File

Random Number Generation

The Minesweeper/UI.h File

The main.cpp File

Implementing an Application Loop

Assets

The CMakeLists.txt File

Building SDL2 from a Subdirectory (CMake)

Running the Application

Creating the Grid

Questions & Answers

The `Globals.h` File

The `Engine/Window.h` File

The `Engine/Rectangle.h` File

The `Engine/Button.h` File

The `Engine/Image.h` File

The `Engine/Text.h` File

Rendering Text with `SDL_ttf`

The `Engine/Random.h` File

The `Minesweeper/UI.h` File

The `main.cpp` File

The `CMakeLists.txt` File