Skip to content

Tutorial.01 Motivation & Specification

Wim van Gool edited this page Jul 16, 2019 · 1 revision

In order to get started with the Kingo framework, we're going to build a simple game. The game I chose to implement is MasterMind - or least a variation of it.

MasterMind Game

Source: Wikipedia

Picking a good use case for this tutorial

I chose to implement a game for this tutorial, because I wanted to pick something other than the average web shop product-ordering system. Although most tutorials and samples that use these kinds of systems as a reference case often get their point across, the challenge with these domains as sample-cases is that you have to make up arbitrary business rules to built something realistic. This involves the risk of the reader spending too much time getting his head around understanding and possibly questioning the system you are trying to build instead of focusing on the benefits and trade-offs of the technology or design you are demonstrating.

Games, on the other hand, have a very clear, limited and specific set of rules. This allows me to just define the rules of the game and let you focus on the tutorial and code-samples at hand. Of course, I have to pick a game that is neither too simple nor too complex. A game that is too simple won't allow me to demonstrate how to build something that resembles a real Domain Model with some non-trivial complexity. A game that is too complex may cause you to spent too much mental capacity on the game and the business rules, whereas the goal of this tutorial is to learn how to design MicroServices and how to use the Kingo framework to implement one.

All things considered, I feel that MasterMind is a nice fit for this tutorial. It is a non-trivial game with simple yet complex enough business rules that will allow for a fun and interesting tutorial. As you will see, I have managed to touch upon almost all features of the framework with this case study. Additionaly, since MasterMind is a codebreaking game, I thought it would appeal to the average software engineer. :) So let's get to it and dive right in.

Rules of the MasterMind Game

MasterMind is a two-player board game game where one player becomes the code_maker_ and the other becomes the code_breaker_. The code-maker devises a code, consisting of a set of colors in a specific order, and the code-breaker then has to guess that code in a limited amount of attempts or turns.

When the code-breaker starts guessing the code, he simply enters the code on his turn (in the form of colored pegs on the board), and the code-maker provides feedback by showing...

  • how many colors are correct both in color and in position (represented by black pins in the board-game) and
  • how many colors are correct only in color but not in position (represented by white pins the board-game).

Note that the code-maker won't specify to which pegs or pins this feedback refers. Using this feedback, the code-breaker must gradually deduce the entire code.

In the original board-game, the two players first decide how many games they are going to play, alternating the role of code-breaker and code-maker. This amount of games must be an even number to even out the odds of winning or losing each game. The code-maker earns one point for each guess of the code-breaker. He earns an extra point when the code-breaker doesn't manage to guess the code within the limited set of turns he has. The player who has earned the most points in the end ultimately wins.

For a more detailed explanation of the game we, we refer to Wikipedia.

Functional Specification of the MasterMind Game Service

To keep things simple for this tutorial, we are going to turn the MasterMind game into a single-player game, where the player always takes on the role of the code-breaker. The computer will take on the role of the code-maker. When you start a new game, you will have to enter your name and can then just start guessing the code that the computer has generated. The goal is to guess the code in as little turns and as fast as possible. Since the focus of our tutorial will be on MicroService design & implementation, not about fancy UI design, we will stick to the console as the primary interface for the players.

Considering players will always be the code-breaker, our MasterMind Game will not be about beating the computer but about obtaining high scores. Each time you correctly guess the code the computer has generated, the total number of guesses and the total time it took you to guess the code are stored in a high score table. The player who manages to guess the code with the least amount of guesses acquires the top spot in the table. When two players crack the code in an equal amount of turns, the fastest players wins. In the unlikely event that both the amount of turns and time match exactly, the comparison is decided in favor of the player who got the result first.

Furthermore, the following rules apply:

  • Instead of colors, the computer will generate a code that consists of 5 numbers (e.g. 25347), to make entry of the code a bit easier.
  • Duplicates (numbers that appear more than once in the code) are not allowed.
  • Each game, the player (code-breaker) gets a total of 30 turns to guess the code. If the code is still not guessed correctly after 30 turns, the game is ended and the player earns no spot in the high score table.
  • The player may choose to forfeit (stop) an active game at any point.

Next up is a description of the solution architecture that we will be using for our tutorial.

Clone this wiki locally