Ucigame - Getting Started
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:
- 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.
- 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.
- [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:
- 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.)
- 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.
- You may get compiler errors; if so, fix them and repeat
the previous step.
- Make sure that YourGame.class is now in your folder.
- 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.
- 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:
- 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.
- 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.
- 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.
- When you create the primary class for your game, make sure
that ucigame.Ucigame is specified as the Superclass.
- 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.
- 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.
- 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.
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.6.0_20\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 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 system 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.