2013-12-03

Tutorial: How to develop a simple JavaFx 2.2 game

For my studies, I had to create a small project. I chose a JavaFx application and developed a little retro board game. At least I have only 5 classes which are not difficult to understand. You can download the application here. The source code is available on Github.

JavaFx game: Peg Solitaire

1. Requirements


What do we need to build the project:
If you want to create such a project from scratch, you'll also need:

2. Build the project (short story)


If you want to checkout the source code, you'll need to install Git and Maven. Please take a look at their docs, if you need any further help. Next, we can checkout the source code. Choose your working directory and run (a directory 'PegSolitaire' will be created):

git clone https://github.com/joerno/PegSolitaire.git

Before building the project with Maven, there are two lines in the file pom.xml to change. That is necessary, because Maven needs to know where the JavaFx JAR files are located. Please edit the pom.xml and change the properties javafx.runtime.lib (JRE lib folder) and javafx.runtime.lib.ant (JDK lib folder) to the right path. Don't forget the slash at the end of the path. Next go into the 'PegSolitaire' directory and run Maven:

mvn clean install

That will create an executable jar file in the target directory. Mention that also the lib-folder is needed, to run the program (in case you want to move the jar file). If you want to import the project in Eclipse, be sure to use a Java 7 SDK with compiler level 1.7.

The next steps will show the long story. I will try to explain how to create a project like this from the beginning.


3. Create a Maven project in Eclipse (long story)


In Eclipse select New Project->Maven->Maven Project and activate 'Create a simple project'.


Next set these values:



Now we will create all the files we need. Please use these packages and directories:


4. Graphics


With Tile and Gimp we can create our images in a fast way. Also download the image for the map here.

4.1 The background image


Start Tile and choose Menu->File->New...


To create a new tileset choose Menu->Map->New Tileset...


Now you can select the fields down right and brush the map, just like the image on top looks like. But don't brush any knights ;)



Finally go to the Menu again and select File->Save as image... Name it backgroung.png.

4.2 The knight image


In Gimp open the tileset image you downloaded before. The knight image is to huge, so we will resize it a little bit. First select the knight with the selection tool (32 px with, 64 px height). When choose from the menu -> image -> crop to selection. Next go to image->image scale and change only the height to 40. We will scale it once again, but this time deactivate the link (aspect ratio) between width and height. Enter a height of 28 px.



Now we will set the correct image size, because we need a 32x32 square. Go to menu->image->canvas size. Both values should be 32 pixel in width and height, also choose center in this dialog.


Export the image to knight.png

4.3 The empty highlighted image


In Gimp choose File->New... and enter 32x32 px with trancparency background (Advanced Options). Now select a foreground color like yellow and the airbrush tool. I used the Brush '2. Hardness 050' with a size of 20. Paint a little bit in the middle of the image and export the file to empty_highlight.png.

4.3 The final image


The last image is also the easiest to create. Just make a new image 250x100 px or similar and write something inside like 'Great job!'. Export it to finished.png.

5. Classes


I wrote a short description of the classes and what they do. Please take a look at the comments for more details.
  • PegSolitaire.java
The class with the method 'public void start(Stage primaryStage)' is the starting point for JavaFx. A new scene is created here, a container for all the content. Our whole map is added to the scene, with the width and height.



  • GameMap.java
The interface has methods to control the map(s). Using it, should allow to implemented additional maps.



  • CrossGameMap.java
It's an implementation of GameMap. The fields of the map are initialized and arranged with the method 'initCrossGameMap()'. The fields are objects of the SquareView class and have different states depending on the map. The SquareView objects are added to a Group ('knightGroup'). This is a renderable node and together with the background group (with the background image), we create another group ('mainGroup'). Finally, this one is added to scene.



  • SquareView.java
A SquareView extends ImageView. This JavaFx class allows us to use a single image resource in different ways, without loading the image file again and again. Depending on the field, our SquareView can have different states:
  • INACCESSIBLE - no move is possible
  • OCCUPIED - here is a knight that can be selected
  • EMPTY - just an empty field, no moves allowed, because it is not highlighted
  • EMPTY_HIGHLIGHT- an empty field, that is highlighted
If a state changes, the image changes too. We also add an EventHandler to our 'squareView'.



  • SquareEventHandler.java
Mouse clicks on an image are handled in this class. Here we check if a move is valid and removing a knight. If a knight is selected, the possible fields were highlighted.



6. Add Maven dependencies and plugins


Finally we want to build the application with Maven, that's why we have to add some lines to the pom.xml:
  • Dependencies: log4j and JavaFx
  • Plugins: maven-dependency-plugin (copy jar files we need to a directory 'lib'), maven-antrun-plugin
Additionally we have to deactivate the standard Maven plugins: maven-jar-plugin and maven-install-plugin. We have to use the ant plugin, because JavaFx has no Maven support yet. If we don't deactivate them, two jar files are created (one is not runnable). In my pom.xml file from github are some additional entries because of unit tests and so on. We don't need that for this tutorial project.



Please edit the pom.xml and change the properties javafx.runtime.lib (JRE lib folder) and javafx.runtime.lib.ant (JDK lib folder) to the right path. Don't forget the slash at the end of the path. Next go into the 'PegSolitaire' directory and run Maven:

mvn clean install

Of course you can run that also inside Eclipse. It will create an executable jar file in the target directory. Mention that also the lib-folder is needed, to run the program (in case you want to move the jar file). That's all :)