“The beginning is the most important part of the work” - Plato

Written by Mark Powell Jan 24, 2005 at 09:43 PM

Before diving in, you might want to see the following links to understand what jME is and what it can do:

Demos

Screen Shots

Note that jME is a Java Game Engine, not a Game Creator. If you are new to programming, or don't know what Java (as opposed to Javascript) is, then this is not the ideal place to find out. I would suggest you follow some basic Java tutorials and come back when you feel confident.

Getting jME up and running in your development environment is relatively straight forward. However, there are several components you need to have in order to really get going. This guide will outline all the necessary steps from beginning to end.

Important: There is a much simpler guide to using jME if you are using an IDE such as eclipse or netbeans. They are located here: Eclipse and Netbeans. IDE developers are still advised to read the Development Conventions page.

Note: This page is geared toward a Windows XP installation. Other versions of Windows will have a similar procedure. Linux and other OS' will be similar as well, but the specifics are not covered here.

You need several things in order to develop with jME:

• Java Compiler and Runtime Environment
• CVS Source Code Control Utility
• Ant Build System
• LWJGL OpenGL/OpenAL Game Library
• jME Source Code

Note: When extracting files from archives, make sure you do not simply drag the files out of the archive, use the actual decompression function. In some programs, the former method will not create subdirectories which will cause errors.

Don't panic if this is sounding too complicated! It's easy. Here are the basic steps we're going to follow:

• Download and Install Java SDK
• Download and Install CVS Tool
• Download and Install Ant
• Download the jME Source Code, Plus LWJGL
• Compile jME
• Verify jME is Working

Ready to get jME up and running? Let's go!

You need to have the Java Compiler and Java Runtime Environment installed in order to use jME.

If you already have the Java SDK, you can just skip this step. If you don't, you can download the Java SDK from Sun from java.sun.com.

There are usually links to download the SDK's on the right hand side of the main page. It's a large download (around 50Mb), so it may take a few minutes, even on a high speed connection. It's probably easiest to just go ahead and download it to your desktop. You can get rid of the installation file later.

Once the SDK has been downloaded, double-click on the icon to begin the installation. Follow the steps and complete the installation.

After the installation has completed, it would be a good idea to verify that your installation was successful. Open a command prompt and type:

java -version

You should see something like the following:

java version "1.4.2_05"
java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_05-b04)
Java HotSpot(TM) Client VM (build 1.4.2_05-b04, mixed mode)

If you get an error, java may not be set up correctly. After you have the Java SDK installed, you can go on to the next step.

To obtain the source code for jME, you need to get access to the source code repository on a remote server. To do this, you use Subversion or CVS.

Note: Getting and compiling the source code for jME is what this guide is all about. If you just want the pre-compiled jar files of the latest release, you can simply download them from the website. Note that you will also need to download and install LWJGL manually!

If you want to use the 2.x series of JME, you will need to use Subversion. If you want to use the 1.x series of JME, you will need to use CVS. Though the 2.x series is not labelled full production yet, you are advised to work with 2.x unless you have a reason not to, in order to minimize future update and support issues.

Good IDE's have integrated CVS and Subversion clients which are much more useful and powerful for IDE usage than the standalone clients. The instructions below are for standalone clients.

(The following description is for installing WinCVS. If you are an experienced developer, you may prefer the Foundation version of SmartCVS. We are only describing the installation of WinCVS here because, though the Foundation version of SmartCVS is Java, powerful, and free, besides generally better, it is not open source.)

Download WinCVS from: www.wincvs.org Note that they have a windows client as well as one for the Mac and GTK. Again, this guide covers the Windows version. The others are probably very similar, though.

The download should be a “zip” file containing a 'setup.exe' executable file. After downloading this file (again, your desktop would be a good choice), use WinZip (or whatever unzip tool you prefer) to extract the the setup.exe file to your desktop.

Double click on the 'setup' file to begin the installation of WinCVS, and follow through until it's finished.

Available standalone clients.

• Command-line Subversion Distributions available for all platforms. Linux users can just use their native package management system to install Subversion.
• TortoiseSVN Open source Gui which runs only on Windows.
• Foundation version of SmartSVN Better Java Gui which runs on all platforms. Free, but not open-source, Interface is more intuitive than Tortoise. Network setup (proxy, ssh key setup, etc.) also works much better.

That's it for installing your CVS or Subversion client. You can set that aside for the moment, though. Before you can really do anything with the source, you'll need a way to compile it. That's done using a tool named 'Ant'.

Ant is a powerful, free, open source, build system written in Java. (It is in essence a replacement for 'make', if that helps clarify anything for you.) In order to use it, you need to download and install it. You can get ant from ant.apache.org. Simply go to the site and follow the instructions to download the zip file. (Again, your desktop is an easy choice.) Now that it's downloaded, you need to get it installed so you can use it. Ant does not have a nice installer like other programs, but it's not too difficult to set up.

First thing: Select a location for the installation. Following the Windows paradigm: C:Program Files/Apache would be a good choice. You can pick whatever you want, though (some people just use: C:/ant for example.)

Next, extract ant from the zip file you downloaded into the directory you choose.

Now that you have ant unzipped, you need to be able to access it from the command prompt, which means altering your Windows setup to include it in your path. For Windows XP (or Windows 2000, and possibly NT), to alter your environment, do the following:

• Right click on 'My Computer', go to 'Properties'
• Click the 'Advanced' tab
• Click the 'Environment Variables' Button
• Find the 'System Variables' section at the bottom.

Now that you found where you need to be, you need to add and change a few things:

First, add these variables:

ANT_HOME - C:\Program Files\Apache\ant (or wherever you installed it)
JAVA_HOME - C:\j2sdk1.4.2_05 (or wherever your SDK is)

Then, update/edit the 'Path' variable to look like:

;%JAVA_HOME%\bin;%ANT_HOME%\bin

Make sure you don't remove the variables that are already there. Now, just click 'Ok', and your system should be updated.

You may need to update your config.sys file instead. This can be found in: C:\config.sys

To do this, just add the following lines to it (Note that you should replace the directories with the ones that you actually installed Ant and Java in):

set ANT_HOME=c:\Program Files\Apacheant
set JAVA_HOME=c:\j2sdk1.4.2_05
set PATH=%PATH%;%ANT_HOME%bin

After updating config.sys, just go ahead and re-boot. (You won't need to do that for WinXP/2000)

Now, Ant should be installed and ready to go! To test it, open a new command prompt window. (Note that you can't use one that was up before you altered your environment, though! Just open a new one.) At the prompt, in any directory, type:

ant -version

It should print out a message that is clearly from ant, and is the version you just downloaded and installed. If you get an error message, check your environment to make sure you specified everything correctly.

That's it for installing Ant. You're now finally ready to download jME!

The first step is to download the jME source. In order to do this, you will use your CVS or Subversion client.

Summary of steps:

• Set up CVS or Subversion client for connecting
• Create a destination directory
• Connect to CVS or Subversion server
• Download jME code with LWJGL
• Perhaps disconnect from CVS server

Basically, the command-line CVS commands you need to execute are as follows: (make sure to replace [java.net username] with your java.net username)

cvs -d :pserver:[java.net username]@cvs.dev.java.net:/cvs login
cvs -d :pserver:[java.net username]@cvs.dev.java.net:/cvs checkout -P jme

If you have a command-line CVS client, you probably already know what you're doing, and you just needed the commands. If you're new to this, or are using WinCVS, read on.

First, if you haven't done it already, start WinCVS. A 'Preferences' dialog may appear, which you will need to add some things to. If it doesn't appear, go to: Admin→Preferences…

In the 'General' dialog that appears, enter the following:

Authentication: pserver
Path: /cvs
Host Address: cvs.dev.java.net
Username: [java.net username]

Using Windows Explorer (or a command prompt), create a place to put the jME code you're about to download. Something like: C:/projects might be a reasonable choice. Don't worry that it's not jME specific. That will be handled for you later.

Next, you need to login to the remote CVS server that stores all the code. To do this, go to: Admin→Login…

Your previously entered data should be there under the 'General' tab. Also, you should probably check the box at the bottom of the 'Local Settings' tab that says 'Force Using the CVSROOT (-d)' so you can get the '-d' option. Click 'Ok' to start the login. WinCVS should connect to the host, then prompt you for a password. Enter your java.net password here.

You should now be logged into the CVS server, so you're ready to get the source code! This is called performing a 'Checkout' of the code. In order to do this, go to: Remote→Checkout module…

That should bring up a dialog asking for a module and a destination directory. There are many different projects on on this CVS server. A 'module' specifies which project you're interested in. In this case, you want the source for jME.

Enter 'jme' (without the quotes) for the module name. This specifies that you want the code for the jME project.

Next, either navigate to or specify your newly created folder as your destination directory (ie, C:projects). Again, don't worry that it's not 'jME' specific.

After specifying this, click 'Ok'. Now, the jME source code should begin downloading to your local machine. It will end up under a 'jme' directory in your destination directory. Ie, in this case: 'C:\projects\jme'

After it finishes downloading, it'd probably be nice of you to go ahead and log out of the CVS server. Use Admin→Logout to disconnect.

Command-line users can run

    svn co http://jmonkeyengine.googlecode.com/svn/trunk jme

Assuming that subdirectory “jme” didn't exist before-hand, this will check out the trunk branch to a new work are rooted in subdirectory “jme” of your current directory.

Developers who intend to commit code changes need to be a JME project member (with a gmail account), and will change the URL to

    https://guser.name@jmonkeyengine.googlecode.com/svn/trunk

where your gmail account is “guser.name@gmail.com”. At some point, you will be prompted for your gmail password, which you can find at http://code.google.com/hosting/settings.

Users of graphical Subversion clients just specify the URL

http://jmonkeyengine.googlecode.com/svn/trunk

to the client. Your client may want you to break up the protocol, hostname, repository path, and sub-repository path like “http”, “jmonkeyengine.googlecode.com”, ”/svn”, ”/trunk”.

That's all there is to getting the source code! Easy, right?

There's an added benefit of downloading the source code instead of the jar files. You get LWJGL with it! LWJGL is a lower-level API that communicates to your video card via OpenGL, and is needed for jME to function. LWJGL will end up being under (in our example): c:\projects\jme\libs [Only advanced JME users will need to use the LWJGL API, and 99% of them should work from the LWJGL API spec without seeing any LWJGL code. Therefore, IMO, inclusion of LWJGL code introduces maintenance difficulties and gives the average user no benefit.]

Now that you have the source code, it needs to be compiled. You will use the ant installation that you did eariler.

Compiling jME is easy after you've done all the setup.

First, open a command prompt, then change to the directory where you downloaded ant to. In the example here, this can be done with:

cd c:\projects\jme

Note: There may be a small issue with your 'jme' directory: There might be 2 of them, one inside the other! The jme directory you're interested in is the one that has the 'build.xml' file in it. If you have this issue, you should be able to just move the directories around to eliminate the duplication. This appears to be a CVS organization issue.

Now, you're ready to compile. Run:

ant dist-test

You should now see ant going through the various basic build targets and performing the compilation, then compiling and testing code and demos. There should be no 'javac' error messages.

That's it. It's done. Now the only thing left to do is test your installation.

To test your jME installation, you can just run some of the demo programs you compiled in the previous step.

First, open a command prompt (or use one you already have open). Then, navigate to your main 'jme' directory. In our examples, this would be: C:\projects\jme (Or, from the note in the previous section: C:\projects\jme\jme You're after the one with the 'lib', and 'target' directories in it.)

The next real step is to run a demo. However, before you do that, it would be beneficial for you to actually understand how things work.

Here's the command you ultimately want to execute:

java -Djava.library.path=./lib -cp ./lib/lwjgl.jar;./lib/jogg-0.0.5.jar;./lib/jorbis-0.0.12.jar;./target/jme.jar;./target/jme-effects.jar;./target/jme-model.jar;./target/jme-sound.jar;./target/jme-terrain.jar;./target/jmetest.jar;./target/jmetest-data.jar;./target/jme-awt.jar

Important Be aware that the sample command-line here generally will not work as-is, because it contains versioned jar files, and these versions are updated regularly. You must look in the lib and target subdirectories to see the current versions. You probably just want to update those version numbers present in the CLASSPATH, not pollute your CLASSPATH by including all of those jars.

UNIX-specific: Most of the CLASSPATH setup samples on this page won't work for UNIX. However, UNIX/Linux/MacOS/Cygwin users can get a head start with this shell script. Just download it to your JME root directory, make it executable, and run with no args to see syntax usage. If your browser can't download files with .bash extension, download it as rundemo.txt then rename to rundemo.bash. It's much easier to accommodate library changes this way. : Seems that this Wiki does not accommodate attachment uploads other than images. If you know how to do it, please upload the script to the Wiki for me and change the link to an Internal link.

If you understand everything above, you're good to go. If you don't, a little explanation is in order.

java

This is what runs all java applications. It launches the Java 'virtual machine' and executes a compiled java program inside of it. You don't really need to know how that all works, but it would probably be helpful to you in the long run to learn more about it. But, this isn't a java tutorial, so we'll just leave it at that.

-Djava.library.path=./lib

This portion of the command defines where the java VM can find external libraries. In this case, it tells it where to find the .dll files for LWJGL (they're in the lib directory – go have a look if you want). This needs to be there because LWJGL uses those libraries to talk to the graphics card in your computer, and jME needs to use LWJGL.

-cp ./lib/lwjgl.jar;./lib/jogg-0.0.5.jar;./lib/jorbis-0.0.12.jar;./target/jme.jar;./target/jmetest.jar;./target/jmetest-data.jar

This portion tells the java VM what the 'classpath' is. The classpath of an application defines where needed compiled files can be found. Without the classpath being set, the java VM wouldn't know to look in the jar files for the various classes, nor would it know where the compiled demos or jME source code is. (jar files are collections of files, usually compiled classes)

• lwjgl.jar is the jar file for LWJGL. It contains all the files it needs to do what it does. Since jME uses LWJGL extensively, nothing will work without this.
• jogg-0.0.5.jar and jorbis-0.0.12.jar are needed for sound support, specifically ogg and vorbis. If you don't use any sounds, you shouldn't need these files.
• jme.jar is the compiled jME source code, packaged up in a jar file. Naturally, jME won't work without its own code.

The 'jmetest.jar' and 'jmetest-data.jar' files contain all of the code for the test applications (demos), as well as the extra data needed to run them (images, models, sounds, etc..). You can't run the tests without the applications themselves!

Note: One final thing to mention about the classpath: '-classpath' could be used instead of '-cp'. They mean the exact same thing. '-cp' is just a very commonly used shorthand.

Note: One more final thing to mention about the classpath . If you're only working with JME in your command shell, it is usually much more convenient to set your CLASSPATH variable to the exact same value as as for the -cp/-classpath param. Your java command lines become much shorter this way because you don't need the classpath stuff any more. Samples for Windows and UNIX Bourne-compatible (incl. Linux and Cygwin):

set CLASSPATH=lib/lwjgl.jar;lib/jogg-0.0.7.jar;lib/jorbis-0.0.15.jar;target/jme.jar;target/jme-effects.jar;target/jme-model.jar;target/jme-audio.jar;target/jme-terrain.jar;target/jmetest.jar;target/jmetest-data-model.jar;target/jmetest-data-cursor.jar;target/jmetest-data-sound.jar;target/jmetest-data-skybox1.jar;target/jmetest-data-texture.jar;target/jmetest-data-images.jar;target/jme-awt.jar

CLASSPATH=lib/lwjgl.jar:lib/jogg-0.0.7.jar:lib/jorbis-0.0.15.jar:target/jme.jar:target/jme-effects.jar:target/jme-model.jar:target/jme-audio.jar:target/jme-terrain.jar:target/jmetest.jar:target/jmetest-data-model.jar:target/jmetest-data-cursor.jar:target/jmetest-data-sound.jar:target/jmetest-data-skybox1.jar:target/jmetest-data-texture.jar:target/jmetest-data-images.jar:target/jme-awt.jar
export CLASSPATH

Now you need to tell java what application to run. You can't just give it the name of the application file, though. You have to enter the full package name of it. By convention, the package name of a file corresponds to what directory it's in, hence calling it a path. Again, this isn't a java tutorial. If you don't fully understand packages in Java, it would probably be in your benefit to learn how they work.

Now that we've covered the command, what are the demos that you can run? Well, there are lots of them. You can go look through the testbuildjmetest directories, looking for class files that begin with the word 'Test'. The full package name will name will be the directory names separated by a '.' (See the examples below).

There are lots of demo programs. The ones listed below are some of the more interesting ones. One final note before we get to them, though. The demos will all start with the jME splash screen. To run the actual demo, pick your options and click 'Ok'.

Now, for a partial list of demos. Again, you can find more in the testbuildjmetest directories. These are listed in alphabetical order. Run any or all of them in any order you want:

• jmetest.effects.TestDynamicSmoker
• jmetest.effects.TestLensFlare
• jmetest.effects.TestParticleSystem
• jmetest.intersection.TestCollision
• jmetest.renderer.TestBoxColor
• jmetest.renderer.TestDisk
• jmetest.renderer.TestEnvMap
• jmetest.renderer.TestScenegraph
• jmetest.renderer.TestFireMilk
• jmetest.sound.TestSoundGraph I believe this class is obsolete. Perhaps replaced by jmetest.audio.TestJmexAudio
• jmetest.terrain.TestTerrainLighting

Just in case you're still having trouble understanding what to do, here is the exact command to run the first demo on the list, the 'TestDynamicSmoker' demo. Again, this assumes you're in the base 'jme' directory (the one where you ran ant from):

java -Djava.library.path=./lib -cp ./lib/lwjgl.jar;./lib/jogg-0.0.5.jar;./lib/jorbis-0.0.12.jar;./target/jme.jar;./target/jmetest.jar;./target/jmetest-data.jar jmetest.effects.TestDynamicSmoker

If you have set your CLASSPATH variable as explained previously, your java command becomes

java -Djava.library.path=./lib  jmetest.effects.TestDynamicSmoker

That's it! Try out the demos. They give you a nice overview of some of the really great features jME has. They should help you see why jME is an excellent choice for developing your future game.

Still having trouble? Visit the jME Forums. There are lots of helpful people there, ready to answer your questions. Last Updated ( Dec 16, 2007 at 1:39Am )

<Forward |User's Guide| Introduction>