This tutorial shows how to set up an IDE (integrated development environment) to create Java 3D games with the jMonkeyEngine framework (jME). An IDE integrates all your development tools (compiler, debugger, profiler, editor, docs, etc) into one graphical interface and spares you some of the complications of the commandline.

New: The 2.0.1 release is an update of the platform independent game engine that also supports Solaris, additionally to Windows (32 and 64 bit), Linux (32 and 64 bit), and Mac OS X. Since different native libraries now have the same name, the set-up instructions have now changed compared to jME2.0, to accomodate the new directory structure.

This tutorial is intended to work with jME 2.0.1 and NetBeans IDE 6.5 or better. Download the NetBeans IDE for Java SE bundle for free from http://www.netbeans.org.

See also: all_netbeans_tutorials

This is a simplified overview of the file structure we are going to set up by going through this tutorial.

• Instead of a complete list of all JARs and native libraries, I only mention lwjgl.jar and lwjgl.dll as examples.
• Instead of a whole application, I mention only one package hello3d/test/HelloWorld.java.

NetBeansProjects/
  Hello3D/
    build/classes/hello3d/test/HelloWorld.class
    build.xml
    dist/
      HelloApp.jar
      Hello3D.jar
      lib/ ... (many JAR files)
      natives/ ... (many native files)
    one-jar-ant-task.xml
    one-jar.mf
    src/hello3d/test/HelloWorld.java
  jME2/
    jME2_0_1-Stable
      src/
      lib/
      jme.jar (and more JARs...)
        lib/
          lwjgl
            lwjgl.jar (and more JARs...)
            natives/
              windows/
                lwjgl.dll (and more natives...)
      ...
  OneJar/
    one-jar-ant-task-0.96.jar
  nbjme/
    dist/javadoc
    ...

We will download two files: The archive jME2_0_1-Stable contains all JARs, sources, and native libraries needed to use jME 2.0.1. I recommend to also download the optional archive jME_2.0_JavaDoc. It contains jME developer documentation and is very helpful.

Steps:

1. Create a directory NetBeansProjects/jME2.
2. Go to http://code.google.com/p/jmonkeyengine/downloads/list
   1. Download jME2_0_1-Stable.zip
3. Unpack the zip archive.
4. Move the directory into your NetBeansProjects/jME2 directory.

Next we create a project and configure its class path and java library path.

We will set up an empty NetBeans project. We'll configure it to find jME libraries on the classpath and to find native dynamic libraries on the java.library.path.

In NetBeans:

1. Choose File > New Project from the menu.
2. In the New Project dialog, choose category Java > Java Application. Click Next.
   1. Project Name: Enter “Hello3D”.
   2. Project Location: Click Browse and choose a directory where you want to save your project, I recommend using your NetBeansProjects dirctory. On Windows this is at C:\Users\Joe\Documents\NetBeansProjects\
   3. Libraries Folder: (None)
   4. Check Set as main project. This will let you control the project using the NetBeans toolbar buttons.
   5. Uncheck Create Main class. You will create your own Main class.
3. Click Finish.

The Hello3D project now opens in the Projects window.

Next we add all jME JAR libraries to the project's classpath:

1. In the Projects window, right-click the Libraries node, and choose Add JAR/Folder from the context-menu.
   1. Browse to the jME2\jME2_0_1-Stable\lib\ directory. Multi-select all .jar files (ctrl-click).
   2. Check Reference as Relative Path.
   3. Click Select.
2. Again, right-click the Libraries node, and choose Add JAR/Folder.
   1. Browse to the jME2\jME2_0_1-Stable\lib\lib (!) directory. Browse into each subdirectory lwjgl, junit, jorbis, jogl.
   2. Multi-select all the JARs in there.
   3. Check Reference as Relative Path.
   4. Click Select.
3. Optional: If you use swt (or an existing jme project gives you errors messages about missing swt), also add all the JARs in the swt subdirectories at jME2_0_1-Stable/lib/lib/swt/*/.jars
4. Your project is now set up to compile an appliation using the jME framework.

Look into the Projects window and open the library node: Here you see the JAR libraries on your project's classpath.

Next we add all native dynamic libraries to the Java Library Path:

1. In the Project window, right-click your project and choose Properties from the context-menu.
   1. Go to the Run category of the Properties window.
   2. VM Options: Enter into the VM Options field where to find the native libraries.
      • Syntax for Windows:

        -Djava.library.path="..\jME2\jME2_0_1-Stable\lib\lib\lwjgl\native\windows\;..\jME2\jME2_0_1-Stable\lib\lib\jogl\native\windows_i586\"

      • Syntax for MacOSX:

        -Djava.library.path="../jME2/jME2_0_1-Stable/lib/lib/lwjgl/native/macosx/:../jME2/jME2_0_1-Stable/lib/lib/jogl/native/macosx/"

      • Syntax for Linux:

        -Djava.library.path="../jME2/jME2_0_1-Stable/lib/lib/lwjgl/native/linux/:../jME2/jME2_0_1-Stable/lib/lib/jogl/native/linux_i586/

      • Syntax for Solaris:

        -Djava.library.path="../jME2/jME2_0_1-Stable/lib/lib/lwjgl/native/solaris/:../jME2/jME2_0_1-Stable/lib/lib/jogl/native/solaris_i586/"

2. Close the Properties window.
3. Your project is now set up to run an applications built with the jME framework.

Tip: Since Java is platform independent, it makes sense to concatenate these lines to a platform independent java library path: You can let your application know where it can find native libraries for any operating system, in one line:

-Djava.library.path="../jME2/jME2_0_1-Stable/lib/lib/lwjgl/native/macosx/:../jME2/jME2_0_1-Stable/lib/lib/jogl/native/macosx/:../jME2/jME2_0_1-Stable/lib/lib/lwjgl/native/linux/:../jME2/jME2_0_1-Stable/lib/lib/jogl/native/linux_i586/:../jME2/jME2_0_1-Stable/lib/lib/lwjgl/native/solaris/:../jME2/jME2_0_1-Stable/lib/lib/jogl/native/solaris_i586/:../jME2/jME2_0_1-Stable/lib/lib/lwjgl/native/windows/:../jME2/jME2_0_1-Stable/lib/lib/jogl/native/windows_i586/"

Yup, looks ugly, but that's what I'm using and it has worked for me. (If you're using 64 bit architecture, replace linux_i568 or windows_i568, with linux_amd64 or windows_amd64.) If you are typing this into NetBeans on Windows, you have to replace / with \ and : with ;. So for Windows it should be

-Djava.library.path="..\jME2\lib\lib\lwjgl\native\macosx\;..\jME2\lib\lib\jogl\native\macosx\;..\jME2\lib\lib\lwjgl\native\linux\;..\jME2\lib\lib\jogl\native\linux_i586\;..\jME2\lib\lib\lwjgl\native\solaris\;..\jME2\lib\lib\jogl\native\solaris_i586\;..\jME2\lib\lib\lwjgl\native\windows\;..\jME2\lib\lib\jogl\native\windows_i586\"

Next we fill in test code and run the project.

To test the set-up, we will use the HelloWorld sample file from the jME tutorial.

In NetBeans:

1. In the Projects window, right-click the project's Source Packages node, and select “New > Java package”.
   1. Create a package called hello3d.test.
   2. Leave the rest and click Finish.
2. In the Projects window, open the Source Packages node.
   1. Right-click the hello3d.test node, and select “New > Java class”.
   2. Create a class called HelloWorld.java.
   3. Leave the rest and click Finish.
3. Download the file TutorialGuide/HelloWorld.java.
4. Open HelloWorld.java in a text editor and copy the content into your hello3d/test/HelloWorld.java file in the IDE.
5. Change the line in the beginning that says package jmetest.TutorialGuide; to

   package hello3d.test;

6. Save the file.

This file is all you need to create a fully working jME application. Let's build and run the HelloWorld sample.

• In the Projects window, right-click HelloWorld.java and select Run File. Tip: Press the Shift-F6 keybard shortcut.
• NetBeans builds and runs the file.
• If a jMonkey configuration window pops up, click OK.
• You should now see a very simple demo application showing a black background and a gray cube.
  • Press the W or S key to move forward or backward.
  • Press the A or D key to move left or right.
  • Move the mouse to look around.

You can copy any of the files from TutorialGuide in the same way and run any sample code that has a main method. (Note: TestPongCool.java also requires ExplosionFactory.java to work.)

First we will create a NetBeans project for the jME sources. Here I describe how to get started quickly with the static snapshot of the sources.

1. In NetBeans, choose New Project > Java > Java Project With Existing Sources. Click Next.
2. Type nbjme as project name, and NetBeansProjects as project folder. Leave the rest as it is, and click Next.
3. Under Source Package Folders, click Add Folder and browse to jME/jME2_0_1-Stable/src. Click Add and then Finish.
4. Go back up to the chapter about setting up the class path and the java library path. Complete both steps for the newly created nbjme project! Don't forget adding the swt JARs.
5. Wait until “scanning projects” has completed, then look at the nbjme project in the Projects window. If the red badges have disappeared, you got all the JARs. (Seeing a blue badge is okay.)
6. In the Projects window, right-click nbjme and Clean and Build. Wait.
7. When it's successfully done building, right-click nbjme and Run.
   1. If it asks you to select the main class, select jmetest.TestChooser! Click OK.

You have now built jME from the sources. When you run it, a useful test chooser will open: Use it to browse bundled examples of various jME features. You can find the example's source code in the nbjme/src/jmetest directory (under Source Packages in the IDE's Project window). Read the sample's source file to learn how to use a feature.

Advanced tip: If you live on the bleeding edge of development, you can check out the svn repository with the very latest sources (instead of using the static src directory). It should work the same, you just have to add the Source Package Folder from the checked out directory instead of jME/jME2_0_1-Stable/src. Also in other situations described in this tutorial, you have to replace jME/jME2_0_1-Stable/src with the path to your checked out sources.

In this step, you will learn how to activate useful IDE features, such as automatic code completion and javadoc pop-ups.

First we have to build the javadoc from the sources (if they release the javadocs as extra file in the future, then you can skip this step).

1. In the Projects window, right-click your previously created nbjme project, and choose Build javadoc.
2. This may take a few minutes. When it's done, the jME documenation will open in your browser. Bookmark it.
3. The jME javadoc has been created in the directory nbjme/dist/javadoc.

Note that if you ever clean the nbjme project, you also have to rebuild the javadoc. Practically you should never have to clean your copy of the nbjme project, because it never changes.

If you are a bleeding-edge developer and got the project's source code from the svn repository instead of using this snapshot, then you will have to rebuild the javadoc regularly.

Now we configure NetBeans to find jME's developer documentation.

1. In the Projects window, right-click the Libraries of nbjme, and choose Properties from the context-menu.
2. Go to the Libaries part of the Properties window.
3. Select the jme.jar entry, and click Edit.
   1. Click Browse next to the Javadoc field and browse to the location of the javadoc directory: dist/javadoc.
   2. Make certain to check Reference as Relative Path.
   3. Click Select. Click OK.
   4. Do the same for each jme*.jar !
4. Close the Properties window.

Configuring NetBeans to find the Javadoc activates handy development features: You are now able to use automatic code completion and documentation pop-ups in this jME project in the IDE.

Next we will give the NetBeans Navigator access to the jME sources in JME2/jME2_0_1-Stable/src.

1. In the Projects window, right-click the Libraries of the nbjme project, and choose Properties from the context-menu.
2. Go to the Libaries part of the Properties window.
3. Select the jme.jar entry, and click Edit.
   1. Click Browse next to the Sources field, and browse to the location of the src directory, e.g. ../jME2/jME2_0_1-Stable/src.
   2. Make certain to check Reference as Relative Path.
   3. Click Select. Click OK.
   4. Do the same for each jme*.jar!
4. Close the Properties window.

Configuring NetBeans to find the sources allows you to learn a lot from reading the actual code.

Let's try out some of the IDE's productivity features:

• Place the caret into or after a variable or method (for example SimpleGame). Press ctrl-space to see available methods and documentation.
• Place the caret between method parentheses and press ctrl-p (mac: command-p) to see expected parameters.
• Click the lightbulbs (left side of the editor) for hints and quick fixes, for example fixing of import statements.
• Click the colored marks (right side of the editor) to jump to errors, warnings, and highlighted occurrences.
• Ctrl-click (mac: command-click) a variable or method (for example rootNode) to open the source file where it was defined.

Learn more form http://www.netbeans.org/kb/.

OneJAR (http://one-jar.sourceforge.net/) provides a way to package your classes, liberaries and native libs in one jar! Here is how to set up NetBeans to automate the process. Let's call the single-JAR file HelloApp.jar (stand-alone) to distinguish it from the previously created Hello3D.jar (not fully stand-alone because of the necessary libraries).

1. Download one-jar-sdk-096.jar, unpack it somewhere.
2. Create a directory OneJar next to the Hello3D directory.
3. Copy the file one-jar-ant-task-0.96.jar from one-jar-sdk to OneJar.
4. Copy the file one-jar-ant-task.xml from one-jar-sdk to Hello3D
5. Edit the first line of Hello3D/one-jar-ant-task.xml to say

   value="../OneJar"

Create a file onejar.mf in the Hello3D directory, with the following content:

Manifest-Version: 1.0
Ant-Version: Apache Ant 1.7.1
Main-Class: com.simontuffs.onejar.Boot
Class-Path: lib/gluegen-rt.jar lib/jinput.jar lib/jme-audio.jar lib/jme-awt.jar lib/jme-collada.jar lib/jme-colladabinding-src.jar lib/jme-colladabinding.jar lib/jme-editors.jar lib/jme-effects.jar lib/jme-font.jar lib/jme-gamestates.jar lib/jme-model.jar lib/jme-ogrexml.jar lib/jme-scene.jar lib/jme-swt.jar lib/jme-terrain.jar lib/jme.jar lib/jogl.jar lib/jorbis-0.0.17.jar lib/junit-4.1.jar lib/lwjgl.jar lib/lwjgl_util.jar lib/lwjgl_util_applet.jar
One-Jar-Main-Class: hello3d.test.HelloWorld

Open your project's build.xml and add the following before the closing </project> tag:

    <import file="one-jar-ant-task.xml" />
 
    <!-- provide a path where executable distros should be saved  -->
    <property name="release.dir" value="${basedir}/release"/>
    <!-- provide the path to the shared native libraries directory -->
    <property name="natives.lwjgl.dir" value="../jME2/jME2_0_1-Stable/lib/lib/lwjgl/native/" />
    <property name="natives.jogl.dir" value="../jME2/jME2_0_1-Stable/lib/lib/jogl/native/" />
    <!-- provide a base name for your executable. -->
    <property name="standalone.jar.name" value="Polygonesia"/>
 
    <import file="one-jar-ant-task.xml" />
 
    <target name="dist-onejar" depends="jar"
            description="Bundles a stand-alone OneJAR distribution">
        <echo>Bundling: OneJAR is copying natives to ${dist.jar.dir}/natives </echo>
        <copy todir="${dist.jar.dir}/natives/windows_i586">
            <fileset dir="${natives.lwjgl.dir}/windows/"  includes="*.dll"/>
            <fileset dir="${natives.jogl.dir}/windows_i586/"  includes="*.dll"/>
        </copy>
        <copy todir="${dist.jar.dir}/natives/windows_amd64">
            <fileset dir="${natives.lwjgl.dir}/windows/"  includes="*.dll"/>
            <fileset dir="${natives.jogl.dir}/windows_amd64/"  includes="*.dll"/>
        </copy>
        <copy todir="${dist.jar.dir}/natives/linux_i586">
            <fileset dir="${natives.lwjgl.dir}/linux/"  includes="*.so"/>
            <fileset dir="${natives.jogl.dir}/linux_i586/"  includes="*.so"/>
        </copy>
        <copy todir="${dist.jar.dir}/natives/linux_amd64">
            <fileset dir="${natives.lwjgl.dir}/linux/"  includes="*.so"/>
            <fileset dir="${natives.jogl.dir}/linux_amd64/"  includes="*.so"/>
        </copy>
        <copy todir="${dist.jar.dir}/natives/macosx">
            <fileset dir="${natives.lwjgl.dir}/macosx/" includes="*.dylib"/>
            <fileset dir="${natives.lwjgl.dir}/macosx/" includes="*.jnilib"/>
            <fileset dir="${natives.jogl.dir}/macosx/"  includes="*.dylib"/>
            <fileset dir="${natives.jogl.dir}/macosx/"  includes="*.jnilib"/>
        </copy>
        <copy todir="${dist.jar.dir}/natives/solaris_i586">
            <fileset dir="${natives.lwjgl.dir}/solaris/" includes="*.so"/>
            <fileset dir="${natives.jogl.dir}/solaris_i586/"  includes="*.so"/>
        </copy>
        <echo>Bundling: OneJAR is composing ${standalone.jar.name}-all.jar</echo>
        <one-jar destfile="${dist.jar.dir}/${standalone.jar.name}-all.jar" manifest="onejar.mf" update="true">
            <main>
                <fileset dir="${build.classes.dir}/" />
            </main>
            <lib>
                <fileset file="${dist.jar.dir}/lib/*.*" />
            </lib>
            <binlib>
                <fileset file="${dist.jar.dir}/natives/windows_amd64/*.*" />
                <fileset file="${dist.jar.dir}/natives/windows_i586/*.*" />
                <fileset file="${dist.jar.dir}/natives/linux_i586/*.*" />
                <fileset file="${dist.jar.dir}/natives/linux_amd64/*.*" />
                <fileset file="${dist.jar.dir}/natives/macosx/*.*" />
                <fileset file="${dist.jar.dir}/natives/solaris_i586/*.*" />
            </binlib>
            <fileset file="${basedir}/properties.cfg"></fileset><!-- optional -->
        </one-jar>
        <echo file="${dist.jar.dir}/README.txt" append="true">
Run the stand-alone distribution from the command line using:
        java -jar -Xmx256m ${standalone.jar.name}-all.jar
        </echo>
 
        <echo>Bundling: OneJAR is preparing ${standalone.jar.name}-win32.jar</echo>
        <one-jar destfile="${dist.jar.dir}/${standalone.jar.name}-win32.jar" manifest="onejar.mf" update="true">
            <main>
                <fileset dir="${build.classes.dir}/" />
            </main>
            <lib>
                <fileset file="${dist.jar.dir}/lib/*.*" />
            </lib>
            <binlib>
                <fileset file="${dist.jar.dir}/natives/windows_i586/*.*" />
            </binlib>
        </one-jar>
        <echo>Bundling: OneJAR is preparing ${standalone.jar.name}-win64.jar</echo>
        <one-jar destfile="${dist.jar.dir}/${standalone.jar.name}-win64.jar" manifest="onejar.mf" update="true">
            <main>
                <fileset dir="${build.classes.dir}/" />
            </main>
            <lib>
                <fileset file="${dist.jar.dir}/lib/*.*" />
            </lib>
            <binlib>
                <fileset file="${dist.jar.dir}/natives/windows_amd64/*.*" />
            </binlib>
        </one-jar>
        <echo>Bundling: OneJAR is preparing ${standalone.jar.name}-linux32.jar</echo>
        <one-jar destfile="${dist.jar.dir}/${standalone.jar.name}-linux32.jar" manifest="onejar.mf" update="true">
            <main>
                <fileset dir="${build.classes.dir}/" />
            </main>
            <lib>
                <fileset file="${dist.jar.dir}/lib/*.*" />
            </lib>
            <binlib>
                <fileset file="${dist.jar.dir}/natives/linux_i586/*.*" />
            </binlib>
        </one-jar>
        <echo>Bundling: OneJAR is preparing ${standalone.jar.name}-linux64.jar</echo>
        <one-jar destfile="${dist.jar.dir}/${standalone.jar.name}-linux64.jar" manifest="onejar.mf" update="true">
            <main>
                <fileset dir="${build.classes.dir}/" />
            </main>
            <lib>
                <fileset file="${dist.jar.dir}/lib/*.*" />
            </lib>
            <binlib>
                <fileset file="${dist.jar.dir}/natives/linux_amd64/*.*" />
            </binlib>
        </one-jar>
        <echo>Bundling: OneJAR is preparing ${standalone.jar.name}-mac.jar</echo>
        <one-jar destfile="${dist.jar.dir}/${standalone.jar.name}-mac.jar" manifest="onejar.mf" update="true">
            <main>
                <fileset dir="${build.classes.dir}/" />
            </main>
            <lib>
                <fileset file="${dist.jar.dir}/lib/*.*" />
            </lib>
            <binlib>
                <fileset file="${dist.jar.dir}/natives/macosx/*.*" />
            </binlib>
        </one-jar>
        <echo>Bundling: OneJAR is preparing ${standalone.jar.name}-solaris.jar</echo>
        <one-jar destfile="${dist.jar.dir}/${standalone.jar.name}-solaris.jar" manifest="onejar.mf" update="true">
            <main>
                <fileset dir="${build.classes.dir}/" />
            </main>
            <lib>
                <fileset file="${dist.jar.dir}/lib/*.*" />
            </lib>
            <binlib>
                <fileset file="${dist.jar.dir}/natives/solaris_i586/*.*" />
            </binlib>
        </one-jar>
        <echo>Bundling: OneJARs are done.</echo>
    </target>

Go to the Run menu and Clean and Build the project (or use the toolbar button). A stand-alone HelloApp-all.jar is now automatically created in the dist directory everytime you build.

You can customize the build dependency of this ant target if you want to speed up your development build cycle. To call the dist-onejar target manually:

• Open the Files window in NetBeans (pc: ctrl-2, mac: command-2)
• Open your project's file tree so you see the build.xml file
• Right-click build.xml and select Run Target > Other Targets > dist-onejar

You can also assign a shortcut to your custom target.

• Open the Files window in NetBeans (pc: ctrl-2, mac: command-2)
• Open your project's file tree so you see the build.xml file
• Click the triangle next to build.xml to list all targets.
• Right-click dist-onejar and choose Create Shortcut from the context-menu. Use the wizard to create a keyboard shortcut, a toolbar button, a menu item, etc, for this target.

• Create a file HelloApp.bat in the dist directory, with the content:

java -jar -Xmx256m HelloApp-win32.jar

• Distribute the .bat file together with the .jar file!
• It's the same for 64-bit Windows, just replace the word win32 with win64.

• For 32bit linux for example, create a file HelloApp-linux32.sh in the dist directory, with the content:

#!/bin/sh
java -jar -Xmx256m HelloApp-linux32.jar

• Distribute the .sh file together with the .jar file!
• It's the same for Solaris and 64-bit Linux, just replace the word linux32 with solaris or linux64 respectively.

When you have created the JAR with OneJAR as described above, doubleclick the JAR to start it in Mac OS X.