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

Demos CVS Browsing

This guide shows how to compile jME without a specific IDE. Consider reading guides for your favorite IDE like

• Setting up Eclipse to build jME
• Setting up NetBeans 5.0 to build jME and jME-Physics 2 (also NetBeans 5.5)
• Setting Up Netbeans 6.1 for JME 2.0
• Setting Up Netbeans 6.7 for JME 2.0

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.

Note: This 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
• JInput
• jME Source Code

Note: You can technically bypass the need for the CVS tool, Ant, and the jME source by downloading and using the latest jME release's jar files. However, it is highly recommended that you download and use the latest source code so that you have access to the latest fixes and features. This guide is meant to cover that type of usage.

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

1. Download and Install Java SDK
2. Download and Install CVS Tool
3. Download and Install Ant
4. Download the jME Source Code, Plus LWJGL & JInput
5. Compile jME
6. Verify jME is Working

You can skip some of these steps if you don't need them, but you will probably want to read through them anyway to make sure you have the correct versions of things.

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

Summary of steps:

1. Download Java
2. Install Java by double-clicking
3. Test to ensure proper installation

jME is a Java based engine. If you don't know what Java is, this is probably not the most ideal place to find out. If you're just learning Java programming language, jME might be a good thing to look at after you have some of the fundamentals down.

Nevertheless, you need to have a Java compiler and runtime environment installed in order to have anything to do with jME. You will probably want the one from Sun Microsystems, and you must have Java 1.5 or later.

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.5.0_09”
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_09-b03)
Java HotSpot(TM) Client VM (build 1.5.0_09-b03, mixed mode, sharing)

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.

Summary of steps:

1. Download a CVS Client
2. Unzip downloaded file
3. Install client by double-clicking

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 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!

CVS clients (what you want) are available in many flavors, most of which are completely free. If you already have a CVS client installed, you can skip this particular step. We are going to cover the usage of WinCVS. Other CVS clients will likely be similar.

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.

That's it for installing WinCVS. 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'.

Summary of steps:

1. Download Ant zip file
2. Create a destination directory
3. Extract Ant to destination
4. Update Environment
5. Test Installation

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, Select a location for the installation. Following the Windows paradigm: C:Program FilesApache would be a good choice. You can pick whatever you want, though (some people just use: C:\ant for example.)

Next, using WinZip (or whatever unzip tool you want), extract ant from the zip file you downloaded into the directory you choose. (Ie, C:\Program Files\Apache)

After that's done, you might want to rename the directory it unzipped to just be 'ant' instead of the long version-specific name that it has. That's up to you. We'll assume that you did that, here. (That is, the entire directory structure will look like: C:\Program Files\Apache\ant)

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:

1. Right click on 'My Computer', go to 'Properties'
2. Click the 'Advanced' tab
3. Click the 'Environment Variables' Button
4. 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.5 (or wherever your SDK is)

Then, update/edit the 'Path' variable to look like: ;%JAVA_HOME%\bin;%ANT_HOME%\bin

Note: You might not need to add the JAVA_HOME section to your path, but it's probably a good idea anyway. Regardless, you need the environment variable JAVA_HOME itself for ant to function.

Now, just click 'Ok', and your system should be updated.

Note: For users of an older version of Windows:

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\Apache\ant
set JAVA_HOME=c:\j2sdk1.5
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!

Summary of steps:

1. Setup WinCVS for connecting
2. Create a destination directory
3. Connect to CVS server
4. Download jME code with LWJGL
5. Disconnect from CVS server

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

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 or just with 'guest' (whithout quotes naturally))

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] (or just guest)

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.

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

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

Summary of steps:

1. Open a Command Prompt
2. Go to jME Directory
3. Compile jME
4. Compile Test Files

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

First, open a command prompt to do your compilation in. (Or, just use the one you checked ant with, if you want)

Next, 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.

Now, you're ready to compile. It only takes a couple commands to do that, neither of which will take very long. The first command compiles the main jME source code:

ant dist-all

You should now see ant going through the various build targets and performing the compilation. There should be no 'javac' error messages.

Next, the second command is to compile all the testing code and demos:

ant dist-test

Ant should now quickly compile the test files. Again, there should be no 'javac' error messages.

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

Summary of steps:

1. Open Command Prompt
2. Go to jME Directory
3. Run Some Demos

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 benificial 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.7.jar;./lib/jorbis-0.0.15.jar;./target/jme.jar;./target/jme-awt.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-images.jar;./target/jmetest-data-skybox1.jar;./target/jmetest-data-sound.jar;./target/jmetest-data-texture.jar <packagename.demo_name>

Note: If you are using OS X or Linux you will need to specify your classpath differently. Replace every ; above with a :. It should look like this:

java -Djava.library.path=./lib -cp
./lib/lwjgl.jar:./lib/jogg-0.0.7.jar:./lib/jorbis-0.0.15.jar:./target/jme.jar:./target/jme-awt.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-images.jar:./target/jmetest-data-skybox1.jar:./target/jmetest-data-sound.jar:./target/jmetest-data-texture.jar <packagename.demo_name>

Note: If you use java 6 or later (java –version) you can use a wildcard instead of having to list every single jar:

java -Djava.library.path=./lib -cp ./lib/*;./target/* <packagename.demo_name>

If you understand everything in the above line, you're good to go. If you don't, a little explanation is in order. We'll break it down into pieces:

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.7.jar;./lib/jorbis-0.0.15.jar;./target/jme.jar;./target/jme-awt.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-images.jar;./target/jmetest-data-skybox1.jar;./target/jmetest-data-sound.jar;./target/jmetest-data-texture.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)

The 'lwjgl.jar' file 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.

The 'jogg-0.0.7.jar' and 'jorbis-0.0.15.jar' files are needed for sound support, specifically ogg and vorbis. If you don't use any sounds, you shouldn't need these files.

The 'jme.jar' (and all the related jars) file is the compiled jME source code, packaged up in a jar file. Naturally, jME won't work without its own code.

<packagename.demo_name> is the name of the program you want to run (E.g. jmetest.effects.TestDynamicSmoker). A partial list of demos is below.

Note: Alternatively, you could reference the compiled code directly by specifying './build' instead of the 'jme.jar' file. If you work on jME itself, this could make your development slightly faster because you wouldn't need to build or update the jar file every time you change something.

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: Alternatively, you could reference the compiled code directly by specifying './testbuild' instead of the jar files.

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.

What this means is that 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 test\build\jmetest 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 testublidjmetest 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.TestAnisotropic
jmetest.renderer.TestBezierMesh
jmetest.renderer.TestBoxColor
jmetest.renderer.TestCylinder
jmetest.renderer.TestDisk
jmetest.renderer.TestEnvMap
jmetest.renderer.TestRenderQueue
jmetest.renderer.TestScenegraph
jmetest.renderer.TestTorus
jmetest.renderer.TestFireMilk
jmetest.renderer.TestMd2
jmetest.renderer.TestMd2JmeWrite
jmetest.sound.TestSoundGraph
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.7.jar;./lib/jorbis-0.0.15.jar;./target/jme.jar;./target/jme-awt.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-images.jar;./target/jmetest-data-skybox1.jar;./target/jmetest-data-sound.jar;./target/jmetest-data-texture.jar 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.

Important: If the demos fail to run (you might see a mention of invalid symbol in an LWJGL native library), make sure you have the latest graphics drivers installed. This accounts for a majority of the problems.

If all of the previous steps seem a bit too much for you, there is an Ant based help script that can help you start quicker.

Still having trouble? Visit the jME Forums. There are lots of helpful people there, ready to answer your questions.