Today we are going to create board game Ithaka for Android. It will be game with ads exchange system added as splash screen. One of the options to monetize your free open source applications is exactly by selling advertisement space inside the applications.

If you like this tutorial please donate:

Company name:		Velbazhd Software LLC
Company email:		velbazhd.software@gmail.com
Company IBAN:	BG68FINV91502016122465

---

Each project should have place where to host. We will use Github, because it is the most popular repository at the moment.

---

After repository creation Eclipse Android project should be created.

---

Eclipse project should be filled with the information from the Github repository.  We will do this by cloning the Github project in different directory than the directory created by Eclipse wizard. After that we will merge both directories.

---

After directories merge initial Git commit should be done. This time it is possible to be done inside Eclipse. 

---

The way in which we are going to monetize our work is by showing banners inside the game. In order this goal to be achieved we are going to register new application in our open source ad server.

---

Revive Ad Server is one of the easiest and most efficient banner exchange servers at the time of this writing. Its free version supports only website integration. For the mobile advertising there is paid alternative. Of course we are going to use only the free functionality by loading pure HTML banners in our Android application. 

---

Android applications do not have real URL address that is why we are going to use URL address, which the application will have after Google Play Store publishing. The URL field is required by Revive Ad Server and it is better we to write there something accurate. 

---

After addition of a new website in Revive Ad Server, banner zone should be created. The idea of banner zones is that you can have many different spots with commercials in your website. In our case we are going to have only single banner zone in the splash screen of our application. The best fitted size of our banner zone is 320x320 pixels. That is why we are going to create just zone like this. 

---


After the zone creation available banners should be liked to the ad zone. 

---

The charming part of using remote ad server is that you will not need to recompile your Android applications in order to visualize new ads or to include new advertiser's campaigns. 

---

When the zone is created and the banners are liked it is time to generate HTML invocation code, which we are going to use inside of our Android application. In our case we are going to use invocation code with JavaScript calls. 

---

Inside Android HTML file will be in assets folder and we are going to name it banner.html. By this way local HTML file will be loaded in Android WebView control and it will run banner loading. 

---

Local HTML file has the minimum needed web page code before Revive Ad Server invocation code to be injected. 

---

We are ready to create our splash screen Activity. It will be the first window, which Android will load when our application is activated. We will call it SplashActivity and its main goal will be to visualize commercials, loaded from Revive Ad Server. It will have second goal, after certain amount of time, to activate game screen Activity. 

---

Our splash Activity will have only one visual component and it will be WebView (full web browser in fact). It will fill entire screen and it will have id by which we are going to used inside our Java code. 

---

The user interface is described in XML format, but the real code, which is used to work with the user interface, should be written in Java and there is Java class especially prepared by the New Activity Wizard for us. 

---

There are few things which should happen in our splash activity. First of all we should obtain reference to our webView visual component. Of course, JavaScript should be activated in order our banner exchange to work. As you can remember we did generate JavaScript based invocation code. The second step is to load our local HTML file. Timeout for ad visualization is sent by Activity parameter. Game Activity is also sent as parameter. Finally we want our banner to show only once (at application lunch). That is why we will rewrite onResume event. 

---

To serve banners from Internet some additional permissions will be needed. Manifest file is the place where Activity parameters are described. In our case we have two parameters - ad timeout and game Activity redirection. The other thing which we would like to have is splash screen not to be included in the Activities Stack. 

---
At this moment we are ready to run our application for the first time. It is done by pressing the green play button above the text editor. The only thing which we see is our splash screen with the banner loaded inside. We still do not have our GameActivity created and that is why redirection is not working. 

---

The game is so simple that we are going to have only three additional screens - game, about and help. For each screen we are going to create separate Activity. 

---

The simplest way to create help and about screens is just by placing scrollable edit text visual component which is forbidden for focusing or editing. Text used for help and about is placed as string resource in strings.xml. It is done like this in order internationalization to be done in an easy way. For help information we are going to copy the game rules. As about very simple text will be added as description of who is the inventor of the game and why it was created as Android application. 

---

On a regular basis it is very good approach Git commits to be done in order code to be stored and available in the remote repository. This can be done in Eclipse by selecting the project with right hand mouse button click. After that Team->Commit. All new created files should be selected for commit and commit message should be written. Commit and push commands can be done together.

---

After the addition of game screen redirection from the splash screen is working, but help and about screens are not reachable from any place in the application. Because of this we will add menu options in the game screen. Android menus are organized as resources and first step in menu creation is to create XML resource in the menu folder of the Eclipse project. The second step is menu description. We are going to have only three options in our menu - new game, help and about. To describe the menu is not enough and we should add some Java source code in our GameActivity, which will call the other Activities. First of all menu should be loaded from its XML description. The opposite of the creation is the destruction. And the most important part is option selection event handling. 

---

Once again our game is ready for testing.

---

From art point of view, the game Ithaka is a very simple game. There is a grid 4x4 and playing pieces in four colors. We can escape from drawing a grid by placing 16 white peaces on the screen arranged 4x4. During the game play we will replace white pieces with colored pieces. For now it will be enough if we use art of 5 circles as PNG images. 

---

There are five common raster resolutions in Android - hdpi, ldpi, mdpi, xhdpi and xxhdpi. Each of them is represented as folder in the Eclipse project and content PNG images proper for the resolution. We are going to supply image only for hdpi. 

---

Nowadays it is very popular software to be develop in three tiers - user interface, object model and database. I Android user interface is presented as group of XML files, object model is presented as Java objects and for database the most popular is SQLite. In our game we are not going to use relational database, because the game is very simple. SQLite can be used for score persistence and user profile, but it is outside of the scope in this tutorial. 

---

Depending on which component you are going to develop first there are two common ways to build software - bottom-up (build the database first) and top-down (build the interface first). In this tutorial we started from the interface first and now it is the time we to start building objects model. In the big software projects formal object-oriented analysis (OOA) and object-oriented design (OOD) is done, but in our case we are going to do very simple intuitive OOA and OOD. The simplest way to do this is by reading the rules and finding all nouns and all verbs. For nouns we will create objects (represented by classes) and for verbs we will create methods (behavior). Of course not all nouns will be represented as Java objects and not all verbs will be implemented as Java functions. 

---

By reading the rules we see that there are 12 pieces in 4 different colors. We have added one extra piece (an empty cell piece). There are different ways to represent the noun piece in Java program, but we will use enumerated type called Piece.

--- 

Second very obvious noun is board. The board has cells and in this cells pieces can be placed. Also some cells on the board are empty. It is very logical that the next data structure which we are going to create will be the Board class. As it is in the real world Java objects have some properties. In the case of the board most important property is its size. We are going to model board size with two static integer class members. At first view some people will say that it is non sense to use constants in this case, but those people will be wrong, because after some time we can decide that the game should be 8x8 for example. 

---

The next interesting property is how long should be the wining line. In the rules it is clear that wining line length (at the moment) is 3. 

---

We will model the pieces on the board by two-dimensional array. As it is seen all model classes are package access. All Activities classes are public, because Android system needs to access them. Our static final members are also with package access. But internal structures of the object should be private in order good OOD to be applied. 

---

The game goes in turns and that is why we should keep information which turn is at each moment. Also it is a good idea we to have information when the game is over. 

---

According to the game rules, win situation can appear if there is orthogonal or diagonal line of the same color. Because of this it is very useful we to create fore helping functions to check this condition. 

---

The four helping functions can be used very efficiently to determine the end of the game by meeting the line end condition (there is one another rule for game end). 

---

The board of the game has an initial state. The pieces are grouped by colors in the four corners. We are going to initialize the pieces array with the proper configuration. 

---

It is very useful we to be able to reset the game board. 

---

We should be able to mark next move in the object model of the board. 

---

Object-oriented programming is based on data encapsulation. We can see this approach in our private class data members (pieces, turn and gameOver). In order hidden data to be used, we will need getters. In the case of turn and gameOver getters just return the values, because integer and boolean types are Java primitive types. It is not the case with pieces array. Java arrays are objects in their internal nature. Regular return will take outside of the class internal data. The correct approach would be a deep copy of the pieces array, but our project is so small that we are going to break this OOP rule. 

---

According to the game rules, piece moved by the last move can not be moved. Because of this in our board object we should keep track of the last move. There is a second rule for game end and it sounds like this - the game is lost with third move repetition. It seams that we will need to keep track of the moves history. The best way to do this will be by collection of objects. Vector is one of the most used collections. For the objects we will crate class called Move and we will break the OOP's encapsulation rule once again. 

---

It is very important we to model our game as better as possible, because wrong or insufficient data structures will result on wrong or complex algorithms. Writing good OOP programs has it base in doing good OOA and OOD. A lot of programmers are lazy during data structures modeling and after that they have a lot of problems with algorithmic part of the software. Because we will need to store and compare moves, it is very good idea our Move class to has some constructors and its own equals method. 

---

The game rules are not clear enough what is third move repetition. It is very usual case in the software production some details to be unclear. In the world of the commercial software usually you are going to contact your customer and he/she will give you the missing information. In the world of open-source software usually it is very difficult to find answers to your questions. Because we are in the world of OSS we are not going to ask questions, but instead we are going to implement what we think is written in the game rules. In this case we will check for last three moves, played by player who turn is. If three of them are equal we will accept that this will meet second end of the game condition. 

---

Moves are restricted by two rules - last moved piece can not be moved and alone (piece without neighbors of its own color) piece can not be moved. And there is a third condition (also not very clear from the game rules) that there should be empty cells between start and end position. We will create helper function for checking is particular move valid. 

---

In order the move to be valid between start and end position only empty cells should be positioned. In order to check this condition we are going to create a private helper function called hasEmptyPath. 

---

At this stage most of the objects in our model are ready. The next step is connection between user interface and the model. It is a milestone in our project and because of this we will push our changes into the remote repository once again. 

---


















The next step will be creation of game screen interface. For now game screen has white background, which is not very proper. We would like to change it to black. It is good practice colors to be stored as XML resources. We will create colors.xml file where to put color values. 

---

Game screen background is adjusted by property in user XML file. 

---

The game interface will consists of 4x4 grid. First it will be only by white pieces. We will describe game user interface by XML tags. We are using very smart way for ImageView ids such as we will represent gird in two-dimensional array. After building the project we see game screen full with white circles. 

---

Having the interface described as XML is not enough. XML description should be connected with Java program. It will be very convenient if keep all references as two-dimensional array. We will connect model objects with the user interface inside the GameActivity. Communication between the UI and the object model will be done from GameActivity to Board and voice versa. 

---

After game screen creation it is very useful to reset the board object. The truth is that UI should be updated according model objects. That is why we are going to create private helper function called updateViews(). The most important is to draw game pieces. All pieces should be with the maximum alpha value of 1. We are going to use 0.5 alpha value when we are doing selection ot the board. Each piece will be drawn according its color. 

---

After we build the game we see the initial game screen with startup configuration as it is described in the game rules. 

---

Except visual resources logical games is nice to have sounds. In this project sound can be played on piece click and game over. Wave files are very proper for sounds and should be placed in raw folder of the Android project. For sounds handling some additional variables will be used. Sounds should be loaded in order to be used in the game play. Also sound pool should be released at the end of the application life cycle. 

---

The user will interact with the game by clicking the pieces on the board. Generally the user will try to move particular piece on the particular empty cell. We will achieve this interaction by attaching on click listener to each ImageView on the board. There are different approaches for this purpose. The common way is to attach single on click listener to each View. For us it will be much more efficient to attach only one listener to all 16 cells. When there is only one listener inside the on click event handler all views should be inspected to find which one was clicked. If the game is over nothing left to be done. It is the best place to play the click sound. On piece click will not work if the listener is not attached to all 16 ImageViews. After finding which piece was clicked it should be reported in the Board object. For this reporting new method will be created. 

---

On each move the player should do two things - select piece on the board and select empty cell. It means that when there is a click on the board it can be a click for piece selection or click for empty cell selection. In this situation at specific moment in time one piece may be selected. It is not possible more than one piece to be selected, but we will model selected pieces with two-dimensional boolean array (just in case if the rules will be changed). Selection of the piece should be visible for the player and because of this getter function will be very useful. Selected piece will be drawn with 0.5 alpha property. Private helper function will check if the selection is already done. 

--- 

First click situation which board will handle is situation without selection and the clicked cell has piece in it. The piece will be selected. In most of the cases this selection will be valid with one exception (the last moved piece). We will handle the situation with the last moved piece on later stage. Another private helper function will help us to unselect all the pieces. It will be very useful if all visual controls are updated after the user click. 

---

Second click situation is with selected piece and the clicked cell also has piece in it. First thing which can be done is removing the selection done before that. By this way the user will have a chance to select another piece. 

---

The third common situation is when there is no selection on the board and empty cell is clicked. It is relatively easy situation, because nothing special should be done. 

---

The most complicated click situation is with piece selected on the board and empty cell is clicked. In this situation the player is ready to finish his move. But again there are two cases. It can be a valid move in which case the player's turn is over or it can be an invalid move in which case selection will be removed and the player will have the chance to select once again. In order move to be validated a move object will be crated by private helper function. 

---

Even that a lot of functionality is missing a simple game can be played at this stage of development. 

---

At each moment in time we should be able to start a new game. It is not the best approach to interrupt current game, but it is fine for initial solution. 

---

When the game is over it is good winning line to be visually marked. Public helper function in the Board class will help by providing two-dimensional array with cells participating in the win combination. 

---

We are going to limit human player to be first in the game play. In such games it is common case players to switch for the first turn, but it is a complication which we will leave for more mature version of the product. 

---

It is time to write some code for the computer opponent. We will implement the simplest possible artificial intelligence. Computer opponent decision making will be done in separate thread. At the end of each human move AI will be activated by using thread handler. First of all AI will not play if the game is over. AI will not play if it is not its turn. At the end of computer opponent move visual information should be updated. The simplest possible AI strategy is just to select random valid move. Small children usually play by this way. There is a risk in this approach for move generation and the risk is that the board can be blocked with no valid move available. In such situation do-while loop will be infinite and it will cause problems to the Android OS. 

---

Some objects are so often used everywhere in the project that it is convenient to present them as static fields of a common class. In our case the name of the class is Util and the name of the static field is PRNG. PRNG comes from pseudo-random number generator. AI move ends by two clicks - stat position and end position. 

---

Because the turn has two stages - piece selection and empty cell selection, it will be very useful end of the turn to be stored in some way (boolean variable, for example). Also it is good to stop for a moment computer move in order human to see what is going on. 

---

When the game is over it is good approach to inform the user for this. Also the game can over after each turn. Board public helper function will help to find game over conditions. The most complicated game over condition is the presence of valid move. Additional public helper function will try all possible moves with the hope that at least one will be valid. 

---

With this final source code the basic game play is ready. Also the first version of the product can be published. There are some bugs in the game, but bug fixing process will be done outside of this presentation. 

---

Almost final step of the software development life cycle is product publishing (there is testing, debugging and maintenance but in the OSS world every interested user can do this for us). We are going to publish in two places. The common publishing store is Google Play and the secondary store is F-Droid, which is only for OSS applications. 

---

Google Play publishing starts from Developer Console. Application should have language selected and product name written. Application description should be added. The most important part of the application publishing is to provide digitally signed APK file. By right click on the project folder Android Tools ->  Export Signed Application Package. Publishing of APK will unlock most of the fields which should be entered during publishing process. Price and distribution countries should be selected. Because there are ads in the game we will mark this in our application form. Main description should be filled with some images in order publishing process to be finished. 

---

Screen shots of the application are required for the publishing. The best way to get them is by Eclipse ADT plug-in. 

---

The final step for Google Play publishing is just to hit Publish button and to wait application to appear in the store. 

---

F-Droid publishing is a little bit more different, because F-Droid is OSS store. It starts by fork of F-Droid / Data repository in GitLab. After the fork cloning should be done. For the publishing meta data file we will need a new git branch. After the branch is switched a new meta file should be created with the application package as name and txt as extension. Text file should describe the application. The only tricky part is the commit hash code, which can be found in GitHub last commit information. We have anti-feature, because we visualize ads. The development is under GPLv3 license. And in the application manifest it is written that this is our first version. 

---

When description file is ready it should be committed and pushed to the remote repository. Commit can be seen in GitLab repository. A merge request should be submitted. That is it. Now we can only wait the application to be published. 

---


Thanks for the watching. 

If you really like this tutorial, please donate. 

Company name:		Velbazhd Software LLC
Company email:		velbazhd.software@gmail.com
Company IBAN:		BG68FINV91502016122465

