Home | Getting Started | Reference | Introduction to Java | Gallery

Ucigame is designed for people who want to design and program 2D computer games. This page will give you some useful information to get started.

Programming is in Java

Computer programming with Ucigame uses a very popular language called Java. Java is a versatile language which can be used to make all types of computer applications. Java has several features designed primarily for large systems created by teams of many people. In Ucigame we generally ignore those features.

Many good books on Java have been written, and you may want to own one. However, those books generally tell you much more about the language then your will need for writing many Ucigame programs, so feel free to skip whatever doesn't seem relevant or comprehensible.

How to get started

You need to have version 1.5.0 or later of Java, which can be freely downloaded from Oracle, which now owns Sun Microsystems, the company which created Java. It's also called the J2SE Development Kit (JDK) 5 or 6 or 7. Start at Oracle's download page.

You will also need a copy of ucigame.jar, which contains all the code necessary for Ucigame programming. Download it by clicking on the link. (If you are using Internet Explorer, ucigame.jar may get renamed to ucigame.zip. In this case, rename it back to ucigame.jar.) Now you need to put ucigame.jar in a place where it can be found when you want to compile and run Java programs that use it. There are two main options:

1. This option may be best if you are running on your own computer. When Java was installed, its "Java Runtime Environment" or JRE was put on your computer. In Windows, it might be in a folder called C:\Program Files\Java\jre1.6.0. (Note that it will have the version number, such as 1.6.0, as part of the name.) Inside that folder is a subfolder called lib, and inside of lib is a subfolder called ext. Look inside that, and you'll see several .jar files. Any .jar file in this folder is accessible to any Java program running the corresponding version of Java. (It's possible to have more than one version of Java on a computer, which can lead to much confusion.) Copy ucigame.jar into this lib\ext folder, and you're ready.
2. This option may be best if you are running on a shared computer. Move ucigame.jar into the folder where you will be writing your game programs. Now you need to tell Java to look in ucigame.jar (it knows to look in the lib\ext folder without you telling it to, but nowhere else). At the command prompt, type in

   SET CLASSPATH=%CLASSPATH%;ucigame.jar;

   This command adds to the "classpath," that is, the list of places Java looks for class files.

3. [probably need other options for non-Windows and for specific programming environments]

If you get an error message like "package ucigame does not exists" when trying to compile, or an exception like "java.lang.NoClassDefFoundError: ucigame/Ucigame" when trying to run, that's a sure sign that there's a mismatch between your CLASSPATH and the location of ucigame.jar.

Once you have ucigame.jar and the classpath squared away, the steps for creating a Ucigame game application are:

1. Create a file called YourGame.java with the source code for your game in it. (This is a big step, of course. Lot's of sample programs on this site can serve as models.)
2. At the command prompt, enter javac YourGame.java. This compiles your program, which means that the .java file is transformed into one (or more) .class files. The .class files are used to actually run the game.
3. You may get compiler errors; if so, fix them and repeat the previous step.
4. Make sure that YourGame.class is now in your folder.
5. Run your game with java YourGame YourGame. The name of the game has to be repeated on the command line. This is something unique to Ucigame, and isn't true of Java programs in general.
6. You can stop the game by pressing the Escape key.

Running Ucigame games as applications and applets

Java programs can run as applications or as applets.

Applets are Java classes that extend java.applet.Applet. Since the Ucigame class extends JApplet which extends Applet, your game extends Applet. Applets usually override four methods from the Applet class: init, start, stop, and destroy; the Ucigame class does this for you. Applets are run inside another program, typically a web browser.

Java applications have a public static void main(String[]) method that provides a starting point for execution. Typically applications are run on the command line with java ClassName. Inside an Integrated Development Environment, an application can be started by a button press or a menu option.

Since the Ucigame class has a public static void main method and also extends Applet, your game that extends Ucigame be run either way.

Creating and running Ucigame games with Eclipse

Eclipse (www.eclipse.org) is a powerful and extendible set of tools for editing, managing, and running Java programs (and other languages too). Here are some tips for happy co-existence between Ucigame and Eclipse:

1. To start, from Eclipse's menu select File > New > Java Project. The recommended choice under "Project Layout" is "Use project folder as root for sources and class files" although either option will work fine.
2. An important step is to make sure ucigame.jar is available. The file can be located anywhere on your disk; a convenient location is the top level of your project. From Eclipse's menu select Project > Properties > Java Build Path > Libraries tab > Add External JARs... . Then navigate to the location of ucigame.jar on your computer and click Open. Finally, click OK in the Properties dialog box.
3. To activate Eclipse's nifty Code Completion pop-up boxes, you need to provide Eclipse with the JavaDocs for Ucigame. Download ucigame-javadocs.zip (perhaps to the same location as ucigame.jar), and unzip the file. You will see a subdirectory named UcigameJavaDocs. From Eclipse's menu select Project > Properties > Java Build Path > Libraries tab. Expand the tree under ucigame.jar. Highligh Javadoc location and click on Edit... Use Browse to navigate to the location of UcigameJavaDocs on your computer and click OK. Finally, click OK in the Properties dialog box.
4. When you create the primary class for your game, make sure that ucigame.Ucigame is specified as the Superclass.
5. It is usually convenient to store image files and sound files in their own subdirectories. If you do this, these subdirectories should go in the same directory as the .class files.
6. Eclipse will be happy to launch your game as an application or as an applet. Eclipse provides a built-in appletviewer that will run your Ucigame game if it is running as an applet. In most cases you will need to tell the appletview what the correct width and height of the window are. (A call to window.size() is ignored when a Ucigame game is running as an applet.) To do this, from Eclipse's menu select Run > Run Configurations ... > your class's name under Java Applet > (x)= Parameters. Put the correct values in the Width and Height areas and click Apply.
7. You may prefer to run your game as an application. To do this, from Eclipse's menu select Run > Run As > Java Application. Eclipse will show you a "Select Java Application" dialog box, where you can tell Eclipse the name of the class which has the main() method. Choose the option which has your game class's name, and press OK. You will now see an error message from Ucigame: "Please repeat the program name. For example, Java MyGame MyGame." Press OK. From Eclipse's menu, select Run > Run Configurations ... > your class's name under Java Application > (x)= Arguments. In the Program arguments area, type in the class name. Press Apply and then Run.

Packaging your Ucigame game in a JAR file

Java's JAR file format provides a convenient way to package your .class files, your art and sound assets, and ucigame.jar itself into one convenient file. More information about JAR files can be found in the Java Tutorials. Here is a simple guide to creating and using a JAR file, using as an example the Pong game from the Gallery.

1. In a folder that contains Pong.class, ucigame.jar, and an images folder, create a text file named PongManifest.txt (or any other name), with the following content:

Main-Class: Pong
Class-Path: ucigame.jar

Make sure that the last line ends with a new line or carriage return. A manifest file specifies information about the content of the JAR file.

2. Create a JAR file named Pong.java by using this command at the command prompt:

jar cfm Pong.jar PongManifest.txt Pong.class ucigame.jar images

jar is a program provided in the Java SDK. cfm are three control parameters for jar: c says to create a JAR file (the following command line argument, Pong.jar), f says to insert the named files and directories into the JAR file, starting from the argument after the manifest file, m says to use the manifest file named as the third argument.

3. To run this JAR file from the command line, enter

java -jar Pong.jar Pong

When the java program sees the -jar flag, it knows to look in the named JAR file and find its manifest. PongManifest.txt gives java the name of the main class and tells it to look for classes in ucigame.jar, which is also inside the JAR. Ucigame games, when run from the command line, require the name of the class file to be passed on the command line as an argument; this is the reason for Pong at the end of the command.

Commonly encountered problems

At the command prompt I entered javac *.java and got this message: javac is not recognized as an internal or external command, operable program or batch file.

The computer is not able to find the Java compiler program, javac.exe. First, make sure you have the Java Development Kit (JDK) installed. You should have a directory with a name like C:\Program Files\Java\jdk1.7.0_02\bin, and in that directory there should be a file named javac.exe. If this isn't the case, see How to get started, above. Second, the system's PATH environment variable needs to include that directory. Enter SET PATH at the command prompt to see (and not modify) the current value of PATH. If PATH does not include the directory containing javac.exe, then modify this environment variable by going to the Control Panel and finding a dialog box with a button titled "Environment Variables." This should enable you to see and edit PATH (sometimes Path). You will need to restart your Command Prompt session, and possibly your computer, for the new PATH to take effect.

I am trying to change the size of the window, and window.size() isn't working.

It sounds like you are running your game as an applet. As an applet, window.size() is ignored, and the window size is determined by the browser or appletviewer. If you are using Eclipse, see the preceding section for information on adjusting the window size values in Eclipse's appletviewer. If you are running in a browser, the game's viewable area is controlled by the width and height parameters in the HTML applet tag.

What next?

Click on Gallery at the top of this page to see Ucigame programs (including source) running as applets.