Waterdrop game, the third version¶

We are going to study how to use Qt to implement a graphical user interface for the waterdrop game. The game logic is nearly the same as in the previous version.

Before studying the program code located in the directory examples/12/waterdrop_game_v3 closer, it is a good idea to first execute the program at least once. If you see only a grid without water drops, do as follows. On the left in Qt, select Projects and uncheck the choice Shadow build.

Responsibilities¶

The program consists of eight classes and the main program. First, we will explain the purpose of each class on a general level.

Data content and game logic¶

The data content and game logic are located in the class GameEngine. An attribute of this class is vector< vector< shared_ptr<Drop> > > board_, which is the exact replica of the data structure implemented in the previous version of the game.

So, the class GameEngine stores the data using the classes Drop and Splash. This combination of three classes works similarly to the previous version of this program. Therefore, a Drop object contains the information on the water amount in the drop, and you can add water to it. When the amount of water reaches its maximum, the drop will pop and create four Splash objects. The Splash objects know their location and direction, and they are able to move one square in the right direction.

The most relevant difference to the previous version is that the GameEngine object also includes the pointer to the object GameBoard, which is included in the subject coming up next, i.e. the graphical representation of the game board.

Graphical representation¶

In the previous version, the drop and splash objects stored their own print characters, which means they took care of the representation. The print characters are in Drop and Splash objects also in this version. The board of ascii characters from the previous version has been used in debug printing of this version. If you wish to view the debug prints, you can do it by removing the comment character on line 125 of the method GameEngine::addWater. This line calls the method print to the object itself. See what happens in the console when you execute the program with the debug prints.

In graphical user interfaces, the stored data is often separate from the representation. For example, on the previous programming course, we talked about the separation of data from its representation when we tried to find new ways to represent the points of a player in a graphical user interface instead of using a label object that contains the amount of points as a number.

The graphical representations of the objects Drop and Splash are in the classes DropItem and SplashItem. Both of these classes have been inherited from the class QGraphicsPixmapItem. Using the class QGraphicsPixmapItem, you can show a picture in the user interface and then, for example, easily move it around. The moving properties are implemented in the base class. The inherited class has all the properties of the base class. This way, you can move SplashItem objects on the screen when splashes fly around the game board.

The DropItem object including the graphical representation has a pointer to the object Drop, which contains similar data. The Drop object contains the information on the state of the drop, which means, for example, the amount of water in the drop. The DropItem object is able to show a picture of a correct-sized drop because it asks the object Drop for its amount of water through a pointer. SplashItem objects work similarly.

The drawing area that represents the game board is implemented in the class GameBoard. This is, therefore, a graphical representation of the data stored in GameEngine. The class GameBoard has been inherited from the class QGraphicsScene, where you can show graphical drawing elements, such as objects of the type QGraphicsPixmapItem.

The objects DropItem and SplashItem have no knowledge of the drawing area or the game board, which means they only show themselves in the user interface and do nothing else.

The class SplashAnimation is tightly connected with the classes Splash and SplashItem. We will get back to this later when we study the animation closer.

Big picture¶

As mentioned, the class GameEngine contains the game logic. In addition to that, GameEngine contains the state of the program as a whole. The GameEngine object tells all the other objects what to do during the execution of the program.

First, the main program creates the GameBoard object, which is a drawing area representing the game board. Then, it creates the GameEngine object and the main window, and gives them the drawing area as a parameter.

The main program also contains the line

QObject::connect(&scene, SIGNAL(mouseClick(int, int)), &engine, SLOT(addWater(int, int)));

This line connects the signal mouseClick from the drawing area to the slot addWater of the game engine. This means that when you click (x, y) in the graphical user interface, the drawing area object sends a signal that is received by the game engine.

After all, the idea of the signal was that its sender does not need to know who or what receives it. The drawing area object does not know anything about the game engine object.

Communication between objects¶

In the Plussa material of the previous waterdrop game version, we explained how the program works with the seed value 7 of the random number generator when we want to pop a drop located in the coordinates (4, 11). We will not go through the communication between the Drop and Splash objects here because it is exactly the same as their communication in the previous version. If you wish, you can now revise the materials of the previous version. If you want to set the seed number in a program with a graphical user interface, edit line 20 of the file gameengine.hh to set the desired seed number.

When the user clicks mouse somewhere in the graphical user interface, the object GameBoard sends the signal mouseClick. The signal activates the slot addWater of the object GameEngine. Let us now look at the program code and see how the program works in this situation. (Open the file gameengine.cpp and look at the function addWater.)

First, the game engine decreases the amount of water in the tank. Depending on whether the water was added into an empty square or into a square already containing a drop, the game engine either creates a new drop object or adds water into an existing drop object. The game engine asks the object GameBoard to complete a corresponding change in the drawing area, i.e. to execute either the method removeDrop or addDrop.

Next, there is a do-while loop that contains the most essential functionalities of the graphical user interface. The loop structure calls in turn the method moveSplashes of the game engine itself and the method animate of GameBoard. This is very similar to the moving of splashes and printing of the game board in the previous version of the game. In the graphical user interface, the flight of splashes has been implemented so that even though a splash can fly through several squares, its flight is implemented as several one-square-long animations presented after one another.

The method moveSplashes returned pointers to the drops that grew as a consequence of the splash movement. The same do-while loop also goes through all of the drops that are growing. This can cause new pops, which will create new splashes, and so on.

Two separate coordinate systems¶

As an attribute of the class GameEngine, board_ is a similar data structure to what it was in the previous versions of the game. Here, each coordinate (x, y) corresponds to exactly one element of vector, i.e. one square on the game board. In other words, the smallest unit to be pointed to on the board is one square. The game always uses the square coordinates when you edit the data content of the game.

The smallest possible unit of the graphical representation is a pixel you see on the screen. Showing one square as one pixel is not reasonable, which is why we chose to show one square as a 50x50 pixel area. For example, the square (0,0) is represented here as the area marked as px=[0,50], py=[0,50].

The square (5,4) is represented as the area marked as px=[200,250], py=[150,200]

Since the graphical representation will be done by the object GameBoard, it must be able to convert the square coordinates (x, y) into pixel coordinates of the screen (px, py) and back. In the GameBoard object, the values of the pixel coordinate system are always handled by objects of the type QPoint that represent a single pixel coordinate (px, py).

The calculations use the definition const int GRID_SIDE = 50. For example, the function mousePressEvent in the file gameboard.cpp handles such a situation that the user has clicked the mouse on the graphical representation of the game board on the screen, and the coordinates of that action – which we can access with the method calls clickPosition.x() and clickPosition.y() – are given in pixel coordinates (px, py). The GameBoard object makes the division clickPosition.x() / GRID_SIDE. In C++, its result is an integer (integer division) that gives the X coordinate of the clicked square.

The calculations are not difficult, but the only way to place all the elements in the right place on the screen is to draw a picture and calculate the locations of each of them. Therefore, a programmer needs mathematics. Especially discrete mathematics is useful.

Animation¶

Animation is started in the method GameEngine::moveSplashes when the object GameEngine uses the method addSplash to ask the object GameBoard to add an animation from point x to point y. The GameEngine object does not know how to do this, but it is the graphical presentation’s job alone.

One attribute of the GameBoard object is a group of animations called animations_, of the type QParallelAnimationGroup. It is a group of animations that are executed parallel to each other, i.e. at the same time. This could be compared to the previous version of the program, where all existing splash objects were stored in a vector, and each of them was moved forward by one step, all at the same time.

The method GameBoard::addSplash creates a new SplashAnimation object that we add into the group animations_. The method GameBoard::animate then starts all the animations at the same time. After that, there is the while loop, which waits for the animations to finish. The animations proceed as a series of events handled by QEventLoop. (We discussed the event handlers shortly on the previous programming course in connection with event-based programming, which was introduced after sequential programming.)

Summary¶

We did not get into all the parts of the program code in this material, and some Qt-themed parts of the program cannot be fully understood with the knowledge you have after this course. Nevertheless, we can see similarities between the implementation of the graphical user interface and the earlier waterdrop game versions. The functionality of the program has many features familiar from them.

Qt is a very large library that enables even complicated programs to be implemented efficiently. We will get into it in more detail on the next programming course, but using only the learning material of these courses, you can only get a superficial understanding of Qt. This course has offered you the foundation for starting to use Qt independently. You already know the waterdrop game from the earlier versions. We hope this makes examining it with Qt a little easier.

Implementing the waterdrop game in three stages also gave you an example of how to develop programs in stages. You have now the possibility to develop the even better fourth version yourself.