Happy Rockets Step by Step

Simple graphical appliction step by step

This is a step by step guide that describes how to create a very simple graphical application (actually not a game yet) using the java classes I have prepared for the Games Fundamentals module. As any set of classes needs some name, I called them “Kingston University Games Fundamentals Classes” which seems to be a very sophisticated name but still very logical if you understand the background, isn’t it?

In this guide we use eclipse as the development tool.

The Happy Rockets application is a small black window with a flock of small happy rockets flying in from the left, see the picture below:

Organising your work

First, please download the current version of KUGF classes, available here. Unpack the archive and place it somewhere on your disk. It is wise to put them in My Documents/workspace folder (h:/data/workspace for KU students), as this is the default place where eclipse looks for it. This means that some of the unarchieved files should appear as
"My Documents/workspace/Games/ball.gif" (h:/data/workspace/Games/ball.gif), for example. If you have an old project under this name - use another name for the new one, as it has so completely different organisation that you should avoid mixing them.

Now, start eclipse. When it asks about the workspace folder give the one into which you have put the Games files (without the Games itself), it may be My Documents/workspace (h:/data/workspace at KU) - it means that hopefully you will have just to accept what eclipse proposed. A bit complicated but it is essential to be at the right place on your disk.

Now, find a tool called New Java Project in your toolbar, click it, and type the Project name as Games (or whatever name you made for the project). The system should notice your existing project and load it; if not - check carefully all the paths.

In your left-hand side panel there should be a lot of items. The orange boxes are packages - small sets of java classes. Some of them are listed below:

• kingston.gamefx - is the main package of classes that create a gaming application
• kingston.sprite - sprite classes
• kingston.games.happyrockets - the application described here (not yet in your tree!)
• kingston.games.asteroids, etc. - other available demo games.

Please take a time to explore the structure. And then - let's start the actual programming!

Running the canvas

Our application will be done actually as a java package. It's a good habit to keep java classes in packages - it helps to keep the project well organised. All the names of packages start with kingston to make them hopefully different from the names given by other programmers to other packages. According to the convention, this name prefix should be uk.ac.kingston - similar to our Internet domain, but I tried to keep things simpler. kingston.games is a prefix given in our project to all games, so a good package name for Happy Rockets may be kingston.games.rockets.

Click a toll called New Java Package in the toolbar and provide the name of the package: kingston.games.happyrockets. Click ok. We have created a new package (should be visible in the pane on your left; white box means there are no classes in it).

Now, let's create the Game Class, the most important class of our almost-a-game application. Click the New Java Class button and provide HappyRocketsGame as the name of the new class. Check if the Source folder and Package are ok (you should already know how they should be). As a superclass, the class after which we will inherit, we will use one of the essential classes from the gamefx (game framework) package, called, well, just Game. The name of the superclass must be fully qualified, ie. kingston.gamefx.Game. Ensure that Constructors from superclass and Inherited abstract methods boxes are checked and click ok!

Now take a while to learn more about the Game superclass: check the documentation site. This class is really important as it implements the logic for your game. We'll be back in it in a while.

Now, create another class, the startup class. Once more click on Create Java Class button and this time type HappyRockets as the name of the class, and kingston.gamefx.GameApplet as the superclass. Before clicking Finish please check the box named public static void main...

What you should get is something like this:

First line informs java what package you are developing, and the second one - what other classes do you import. We will need other class to be imported, so add another import like this

Now, a word of explanation on both classes we import:

• GameApplet is the base class for all aplets aware of gaming stuff. Our class extends this class so that to make HappyRockets runnable as an applet.
• GameWinApp encapsulates stuff needed for a windowed application to be a game (or almost-a-game). We will construct an instance of this class in a moment.

First of all, let's initialise the applet by overriding its standard function called init. Within it, we will create an instance of our gaming class, HappyRocketGame (created previously), and associate it with the applet:

That's all you need to start with an applet - all other details are hidden within your gamefx package! To try out - take the Run... button (a white arrow on a green back), click a small black arrow on the right and from the menu choose Run... Then choose "Java Applet" and click New. Provide all the details - remember what are the names of your Project and Applet Class. A white window should appear - not very impressive, but always something to start with...

Now, let's do the application. We need an instance of HappyRocketGame and an instance of GameWinApp (windowed application class). Just add the following lines into the main function:

Try out the application as you did with the applet.

What we have done so far?

• In both cases (applet and application) we have created an instance of HappyRocketGame that is going to implement the whole game logic (it does not yet, so what we got so far is just empty window)
• We have associated this instance with the HappyRocket class, which implements the behaviour typical for a gaming applet. You shouldn't be interested in the details of this class, but you can check at the the documentation site.
• As an option, we have created an instance of the Windowed Application class, GameWinApp, and also associated it with the HappyRocketGame instance. Notice that when we start the game we do it in either applet or application mode, so there is no way to wake up more than just one instance of HappyRocketGame.

Adding some graphics

In this section we will develop the HappyRockerGame class (please open it in eclipse).

The graphics in the game is based on a concept of sprites. Sprites are graphical elements that may be displayed and mover around the screen. A special package kingston.sprite is specially dedicated to support the sprites (see documentation site).

As we have to process many sprites at a time, what we actuaully need is a SpriteList instance. This is a handy object that can hold any number of sprites. We also need a bitmap image to feed the sprites with (they have to get an appearance provided). So let's start by adding two member variables to our class:

Are there red error signals? Well, we lack import lines. It's a common thing in java: many times when you add any feature into your code, you have to add some imports:

Well done! Now a short lesson about how the Game-derived class works (have you read the documentation site?). Here is an essential list of functions that you are likely to override in your class:

• onStart, called before the animation is started,
• onUpdate called repeatedly to update the game state,
• onDraw called repeatedly to render the game state,
• onTerminate called once before the game is terminated.

(You should have found the stubs of these classes already within your class).

The most noteworthy is the onUpdate/onDraw pair. It is called by the framework in each animation frame, or about 80 times per second. The onUpdate function is where you update the game, ie. do all the necessary calculations. In our game we will produce new rockets here and advance the motion of the existing ones. The onDraw should paint the entire game window. We will paint black background there and the whole flock of rockets.

We also need some initialisation stuff. This involves creating a list of sprites and loading the rocket image. A good place to put it in is the onStart function.

Let's summarise:

• onStart: create a new SpriteList, load the image of the rocket.
• onUpdate: produce new rockets, update all the rockets, remove those which are no longer visible.
• onDraw: paint the black background, draw all the rockets.
• onTerminate: actually, we don't need anything here, leave it empty.

This is the onStart stuff (just put these lines inside your onStart function):

While the first line is stratghtforward, the latter one is a little bit more complex: check the documentation site to learn all the details.

To produce a new rocket we simply need:

BitmapRocket is a special subclass of sprites - ready to display after loading an image. The parameters provided also mean that the rocket will display at (10, 10) on the screen - what is not exactly what we want. The last param, timeElapsed, is just the current system time and it is ok. To improve rocket creation, let's try this:

And we have to add another statement to add the rocket to the list:

However we are far from having onUpdate in its final version, let's move on to onDraw just to be able to see what we have:

First two lines choose the paint color and paint the entire window. The loop iterates through all the m_drawList elements and draws each of them. The Graphics g object is a graphical device used for any graphical operation.

Tuning the Sprites

Running the application shows two problems: first, our sprites are motionless, and second: there are much too many of them. The first problem may be solved by assigning each of them a random direction and velocity:

Direction is now chosen on random from the range of 0..PI. As 0 radians normally point upwards, and the angles are measured clockwise, this means the rocket will head anywhere but on the right. Velocity is anything from 0 to 1 (pixel per milisecond = 1000 pixels per second).

The problem of too high number of sprites may be also solved using the random number generator. Here is the entire part of the onUpdate function that creates the rockets (just combine these two pieces of code):

Math.random() * 80 generates random numbers from the range 0..79. As the function is called 80 times per second (this is FPS, Frame Per Second rate), obviously this value will be less then 5 around 5 times a second, on average. Simple?

Running this application shows that, indeed, the rate in which new rockets are created is acceptable, but rockets remain motionless. This is because we still fail to call the sprite's onUpdate function that is indispensable if we want to gain from their automatic movement facility. This can be solved by iterating along the whole list of sprites. Additionally, for each sprite we check if it is still visible on the screen, and if it is not, we remove it form the list:

Notice the last line containg remove(i--). The loop control variable, i, is here decremented to reflect the fact that an item has been removed. Without this, the loop would skip the next element after the removed one.

Run the application now. Enjoy!