2 - Using APE

By the end of this chapter, the reader will be able to:

Now that you've written your first Java program and shown that your java installation is up and running, it's time to make use of the fantastic new APE tool that we've provided for you!

APE as a package (for this material) comes as a set of two jar files. The first is APE itself, which is the engine that drives the underlying environment. The second is a specific instance of that environment - in the case of our material, a simple pacman game. The package is flexible enough to allow for people to write their own front-ends and rule systems if they wish to provide another environment, but that's well beyond our capabilities at the moment and so we must be satisfied with playing about with the Pacman game provided.

APE is very simple to use, although it requires a little bit of extra setup before we can use it. The first step is to download the two files: APEV1.jar and APEpacman.jar. Once they have been downloaded to your system, they must be installed so JCreator has access to them.

From the project menu in JCreator, choose Project Settings. This will open up the project settings dialog. In the tab that says JDK Profiles will be your installation of the Java development environment (the exact text on the dialog will vary depending on how the system has been installed). Double click on this line of text to bring up the options for that profile:

Fig 2.1: Profile Settings

This will bring up a second dialog box containing a list of all the class libraries being used by your installation. This is not important at this point. What is important is the process you go through to add APE to the list of classes your Java installation can work with. Click on the button that says 'add' and choose 'Add archive'.

Fig 2.2: Adding an Archive

This will bring up a dialog box - navigate to where you downloaded the APE Jar files and select and open each in turn. They will be added to the list of available classes for your Java profile, meaning that you are now APE ENABLED. Awwoogah!

If you've done this correctly, you'll see the jar files you added now listed in the classes tab as can be seen in the image underneath. Once you've got this, keep clicking OK until you get back to the IDE itself.

Fig 2.3: After The Archive Has Been Added

This is all the work that you need to put into the process to make JCreator make use of the APE libraries - if you are using a different IDE you may need to go through a different process. Check your application documentation for details on the process.

So, now you've got APE available, how do you make use of it? For this, we need to look at a new Java program. This program is slightly more complicated than the one we wrote in the previous chapter, but it serves as a baseline for all the programs you write over the next few chapters. Whenever you are asked to start a new program, you should start from the template you are given below:

import draconia.APE.pacman.*; public class ApeTemplate { public static void main (String args[]) { PacmanGame main = new PacmanGame(); main.setMap ("blank"); main.showGame(); } }

Okay, let's go through this program line by line to show what each part is doing.

The first line import draconia.APE.pacman.*; is telling Java where it can find all of the different pieces of code that belong to the APE Pacman game. You told JCreator where it could find the Jar files, and this line of code is telling Java where in those Jar files it can find the code you will reference later in the program.

The second line is familiar to what we saw last chapter - we give the name of the class, in this case ApeTemplate. As you write your own programs for the APE tool you will change the name of the class, but otherwise leave the basic structure alone. There is a JCreator template file available in the Resources section for APE programs also.

The third line likewise is similar to the one we say in the last chapter, and it does exactly the same thing.

It is in the next lines that we start seeing anything new. The first of these lines is

PacmanGame main = new PacmanGame();

This line is telling Java that we want to create for ourselves a new PacmanGame, and that we want to be able to refer to it by the name main. The PacmanGame contains all of the methods that let us play around with pacman, and so is very important to our programs.

Then we have the following line:

main.setMap ("blank");

We have already told Java that we want a PacmanGame and we want to be able to call it by the name main. Here we are using our PacmanGame (main) and telling it to set the map for pacman to the one called blank. There are dozens of maps shipped with APE (a full list of which is included at the end of this book), and we will occasionally ask you to change the map you are using through this mechanism.

It is the third line that causes the game to actually display itself:

main.showGame();

Pacman will sit inactive until this instruction is given. When it is, then the game will be displayed in all its technicolour glory. Compile and run this starting program, and Pacman will open up for you.

The only thing that will happen is that the game window will display - pacman won't do anything yet, because you haven't told him to do anything. He is your willing slave, and will obey your instructions without question or hesitation, even if you send him into imminent and inescapable danger! Ooh, the sense of power!

Fig 2.4: The APE Interface

The big black expanse of space in which Pacman is currently floating is the grid. Each of the white dots is... well, a white dot. The aim of the game is to make pacman eat all of the dots. At least, the aim of this map is - other maps have different puzzles built into them. This is a nice simple map for us to use as our baseline for the explanation of how to make pacman move, though.

Different maps introduce different aspects of the game. Ghosts, power pills and obstacles will also appear in later stages of the tool - but let's concentrate on the first principles before we worry about all of that.

How do we make Pacman move, then? Well, we just tell the game we want him to move:

Main.move();

We put this line of code after the code that is provided, but before the closing braces. Let's start a new program for this... as it's our first expedition into APE, let's call our program MyFirstMonkey. Base it on the template, and we'll add in a line to make Pacman move:

import draconia.APE.pacman.*; public class MyFirstMonkey { public static void main (String args[]) { PacmanGame main = new PacmanGame(); main.setMap ("blank"); main.showGame(); main.move(); } }

Compile and execute this program, and you'll see pacman moves - a little bit:

Fig 2.5: Moved on One Space

He only moves on a single space, because Pacman is obedient and only does what he is told. You told him to move, and move he did. Now he won't move again until you tell him. You can't issue instructions to him while the program is running - once he's followed your orders he will stay there, inert, until you close down and run the program again.

You may see at the bottom of the screen that when you issue Pacman an order you get some information displayed. The first of these is the difficulty of the map you are using - different difficulty settings have different effects on the game which we will discuss later. The second part is the player position on the grid - when Pacman has moved on a space his position is 0,18 which may seem strange, but we'll talk about why that is when we move on to more advanced topics.

The final piece of information is the number of steps that pacman has taken, and the maximum number of steps he can take on that map. When the number of steps is equal to the maximum number of steps, you have failed to achieve the objectives of the map in time. For this map, you have 1000 steps Pacman can take, which is more than ample. Other maps have less generous limits set for you to ensure a certain efficiency of your solutions.

But again, that's all in our future. For now, we want him to do something more than move a single space in the grid. Let's try getting him to move two. We do this by telling him to move, and then telling him to move once more:

import draconia.APE.pacman.*; public class MyFirstMonkey { public static void main (String args[]) { PacmanGame main = new PacmanGame(); main.setMap ("blank"); main.showGame(); main.move(); main.move(); } }

Fig 2.6: Moved On Two Spaces

If you want him to move three spaces then - well, you guessed it, you tell him to move three times. If you want him to move all the way to the other side of the map, then issue the move command 19 times and he'll get there. That may seem somewhat long winded, but we'll see better ways to accomplish this kind of goal in later chapters.

But, what else can we do with pacman? As it happens, quite a bit! When we call the move method, pacman moves a space in the direction he is facing. If we want him to move in a different direction, then we just need to change the way he is facing. We do this by using the turnLeft() and turnRight() methods, and we use these in almost exactly the same way we use the move method - we send the message that we want pacman to turn, and turn he does.

Consider for example if we wanted him to move two spaces forward, and then turn right, and the move another two spaces - he would end up as can be seen below.

Fig 2.7: Pacman Turning

We can make pacman move wherever we like in the game - each command that we give him will be executed step by step until we get to the end of the program, at which point the program will simply stop running.

Let's look at the program that would cause Pacman to go in a circle and end up where he started:

import draconia.APE.pacman.*; public class MyFirstMonkey { public static void main (String args[]) { PacmanGame main = new PacmanGame(); main.setMap ("blank"); main.showGame(); main.move(); main.move(); main.turnRight(); main.move(); main.move(); main.turnRight(); main.move(); main.move(); main.turnRight(); main.move(); main.move(); main.turnRight(); } }

Running this would give us the following at the end of Pacman's run:

Fig 2.8: Full Circle

Easy enough, eh? Well, hopefully for now that is the case. In chapters to come we'll see there is more to Pacman than simply the ability to move around a grid - he can perceive his surroundings and make decisions based on what he can see, which is very useful.

For now though, we are limited to statements of code that are executed one after another - this is known as sequential programming. There is no opportunity to change what code is going to be executed based on information received when the program is running. Obviously this is a somewhat limited way of writing a computer program, but it will do for now.

Before you go off and perform an exercise of your own based on pacman, let's look at a slightly odd situation with this particular map - what happens if you cause pacman to turn left and then move?

There is nothing to stop you trying this, but the program won't like it because you are going outside the realms of the grid - part of the process of writing code means making sure things like this don't happen:

import draconia.APE.pacman.*; public class BrokenMonkey { public static void main (String args[]) { PacmanGame main = new PacmanGame(); main.setMap ("blank"); main.showGame(); main.turnLeft(); main.move(); } }

Run this program, and what you'll see when pacman attempts to move is this in the output window:

Fig 2.9: A Horrible Error!

Yikes, that looks scary! All it means though is that you tried to move pacman off the grid. Technically this is called an exception, and indicates something has gone wrong with your program. Eventually everything that is written above will make perfect sense, but for now all you need to know is that if you see something like this, it means your program is not working properly and you need to figure out why.

When writing code, it's often very useful to be able to send messages to yourself to ensure that what you think is happening in the code is really the case. In the last chapter we looked at the System.Out.println method which displays a line of text to the console - however, you won't be looking at the console when you are using APE, you'll be looking at Pacman. For this reason, there is a sendMessage method available in the Pacman game. Just pass a string of text to this and you'll have a message displayed along the top of the screen, which can be very useful for showing you what you think should be happening:

import draconia.APE.pacman.*; public class MyFirstMonkey { public static void main (String args[]) { PacmanGame main = new PacmanGame(); main.setMap ("blank"); main.showGame(); main.move(); main.move(); main.turnRight(); main.sendMessage ("Okay, I should be facing towards the right."); main.move(); main.move(); main.turnRight(); main.sendMessage ("Okay, I should be facing down now."); main.move(); main.move(); main.turnRight(); main.sendMessage ("Am I facing towards the left? I should be."); main.move(); main.move(); main.turnRight(); main.sendMessage ("Huzzah, I am done!"); } }

Sometimes though you want to be able to include little notes for yourself in the code so that you can follow what's supposed to be happening when you read the program. You don't want this to be displayed in the console because they may be long, complicated, or simply inappropriate.

With Pacman it doesn't really matter very much, but imagine if you were using Microsoft Word or some other application package, and every ten seconds it popped up some message that the developer was using to keep track of what should be happening - that would get very annoying very quickly.

Part of being a programmer means being able to write code collaboratively with other people, and having them be able to understand what is happening in the program... or rather, what you think should be happening in the program. Java provides a mechanism for including notes for people that are ignored by the compiler - preface a line with a double backslash, and Java will ignore that line whenever it goes to compile a program. It'll be there purely for your benefit when you come back to read the code. Lines of the program prefaces in this way are called comments, and are vital to ensuring clear, readable code - especially when your code starts getting more complex:

// This sets up the packages that the APE program will use. import draconia.APE.pacman.*; // We open our class here - it's called MyFirstMonkey. public class MyFirstMonkey { // All programs in Java must have a main method - it's where the program execution begins. // This is the start of our main method. public static void main (String args[]) { // We're creating a pacman game here, and we're going to // call it 'main' PacmanGame main = new PacmanGame(); // For this program, we're using the blank map. main.setMap ("blank"); // Display the game. main.showGame(); // Make Pacman move. main.move(); // Make Pacman move. main.move(); // Make Pacman turn right. main.turnRight(); // Send a message to the interface. main.sendMessage ("Okay, I should be facing towards the right."); // Make Pacman move. main.move(); // Make Pacman move. main.move(); // Make Pacman turn right. main.turnRight(); // Send a message to the interface. main.sendMessage ("Okay, I should be facing down now."); // Make Pacman move. main.move(); // Make Pacman move. main.move(); // Make Pacman turn right. main.turnRight(); // Send a message to the interface. main.sendMessage ("Am I facing towards the left? I should be."); // Make Pacman move. main.move(); // Make Pacman move. main.move(); // Make Pacman turn right. main.turnRight(); // Send a message to the interface. main.sendMessage ("Huzzah, I am done!"); } }

Java allows for two other kinds of comments... another is the block comment which starts with a /* symbol and ends with a */. Anything between these symbols will be treated as a comment:

/* All programs in Java must have a main method - it's where the program execution begins. This is the start of our main method. */

And there is also the Javadoc comment, which works exactly the same except it begins with a /** symbol. Don't worry about the Javadoc commenting format - it's used to automatically generate documentation from a program listing, and is not a concern for us at the moment.

Comments can also be useful for temporarily removing sections of your program so you can see what effect changes can have without having to delete and retype. As time goes by, you will find comments to be very useful when developing the solutions to the maps you'll see.

Okay, now you've seen a little bit of what you can do with APE, it's time for you to try a map of your own. Change the map to easy_does_it and load it up. Your challenge is to have pacman eat all of the dots on the map... the trick is, you only have twenty moves in which to do it. Having pacman turn around does not count as a move - only when he takes a step forward does it count towards your total allowance of moves.

Certainly using the first three commands from APE that we have seen, it's possible to make Pacman move in a range of interesting ways... but that's only the foundation of what's possible with APE. Many more exciting commands are available at your finger tips, and in chapters to come we'll even get Pacman to think about what he's doing, and make choices based on the situations that he is faced with.

It may seem quite strange to think that making pacman move around a grid will actually teach you anything about programming, but you'll learn more from this than you might believe. Ever see the Karate Kid? This is real Mister Miyagi stuff you're learning right now, for reals.

Further Reading

The following table details further reading on the topic in this chapter, and also any external resources that you may find useful.