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.

This tutorial is intended to work with jME 2.0 and NetBeans IDE 6.5 or better. Download the NetBeans IDE for Java SE bundle for free from http://www.netbeans.org. jME 2.0 is deprecated as of September 2009. But as long as the download is still available this still works.

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/ ... (JAR files)
      natives/ ... (native files)
    one-jar-ant-task.xml
    one-jar.mf
    src/hello3d/test/HelloWorld.java
  jME2/
    jME_2.0_Complete_(r4093)/
      jME_2.0.jar
      lib/
        lwjgl.jar (and more JARs...)
        natives/
          lwjgl.dll (and more natives...)
      run_jME.bat
      run_jME.sh
    jME_2.0_Distribution_(r4093)/
      jme.jar (and more JARs...)
    jME_2.0_JavaDoc_(r4093)/
      index.html (and more docs...)
    jME_2.0_Sources/
      src/
      lib/
        lwgl/ ...
          lwjgl.jar ...
          native/lwjgl.dll ...
        mvn-lib-install
      pom.xml
      build.xml
  OneJar/
    one-jar-ant-task-0.96.jar

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

Note: I write * instead of the explicit version number.

Steps:

1. Create a directory jME2.
2. Go to http://code.google.com/p/jmonkeyengine/downloads/list http://code.google.com/p/jmonkeyengine/downloads/list?can=4&q=jme
   1. Download jME_2.0_Complete*.zip
   2. Download jME_2.0_JavaDoc*.zip
   3. Download jME_2.0_Distribution*.zip
3. Unpack the zip archives.
4. Move each of the resulting directories into the 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. For example 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\jME_2.0_Complete_(r4093)\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\jME_2.0_Complete_(r4093)\ directory and select the file jME_2.0.jar.
   2. Check Reference as Relative Path.
   3. Click Select.
3. 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.

      -Djava.library.path="../jME2/jME_2.0_Complete_(r4093)/lib/natives/"

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

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.)

The jME-2.0.jar also contains demos that show well what jME is capable of. (This step is optional.)

1. Change into the directory: cd jME2/jME_2.0_Complete*/
2. Among other things you will see run_jME.bat and run_jME.sh.
3. To run the test:
   • On Mac OS X and Linux, execute ./run_jME.sh in a Terminal window.
   • Or: On Windows, execute run_jME.bat.
   • Or: In general, run java -jar -Xmx256m -Djava.library.path=“lib/natives” jME_2.0.jar on the commandline.

The jmetest.TestChooser starts. Select your screen settings and select one of the demos to run. See also: zathrasbeginnersfaq.

Browse all the source code here and learn how to use each feature from examples: http://jmonkeyengine.googlecode.com/svn/trunk/src/jmetest/

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

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

1. If you haven't done so yet, go to http://code.google.com/p/jmonkeyengine/downloads/list http://code.google.com/p/jmonkeyengine/downloads/list?can=4&q=jme and download the file jME_2.0_JavaDoc*.zip. Unpack and save it to your jME2 directory.
2. In the Projects window, right-click Libraries and choose Properties from the context-menu.
3. Go to the Libaries part of the Properties window.
4. Select the jME_2.0.jar entry, and click Edit.
   1. Click Browse next to the Javadoc field and browse to the location of the javadoc directory, e.g. jME2\jME_2.0_JavaDoc_(r4093)\.
   2. Make certain to check Reference as Relative Path.
   3. Click Select. Click OK.
5. 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 the jME sources.

1. Go to the IDE menu and select Team>Subversion>Checkout. (In NetBeans 6.5 it's Versioning>Subversion>Checkout.)
   1. Repository URL: Enter http://jmonkeyengine.googlecode.com/svn/trunk
   2. Leave user and password blank and click next to connect to the repository.
   3. Repository Folder: Enter trunk.
   4. Local folder: Browse to your jME2 folder
   5. Click Finish.

Wait for the source files to finish downloading. If NetBeans asks whether it should open the new project, you can say yes. (See below)

1. In the Projects window, right-click Libraries and choose Properties from the context-menu.
2. Go to the Libaries part of the Properties window.
3. Select the jME_2.0.jar entry, and click Edit.
   1. Click Browse next to the Sources field, and browse to the location of the trunk directory, e.g. jME2\trunk\.
   2. Make certain to check Reference as Relative Path.
   3. Click Select. Click OK.
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/.

Now that you know how to run a jME sample file, and have access to sample code, you can start your own game.

Tips:

• When creating a new project from scratch consider using the Java Desktop Application category instead of a vanilla Java SE project. It creates a Swing Application Framework-based project that already comes with a main window and some menus.
• If you prefer Maven over Ant, you can also create a custom Maven project instead.

• Right-click the project and choose Rename from the context-menu to change the project name (or any files or packages) without breaking the project.
• Create a new package for your game's source files, and create a Main.java class (New File > JFrame form) in the package.
• Use the NetBeans GUI Builder to design the game's intro screen (JFrame). Foor instance create a Start button that creates a new instance of your game. You can also add cool graphics and Settings/Save/Load buttons here.
• Create new packages to store resources (textures, audio, images).
• Keep the hello3d.test package to test things (Later you can just delete it).

• How to build and run the project:
  • Either set a main class for the whole project like Main.java (Project Properties > Run) – then use keyboard shortcut F6.
  • Or test-run individual files that have a main method – then use keyboard shortcut Shift+F6

It's fine to use SimpleGame for quick demos. By looking at existing samples, you see the underlying inheritance structure, and along the same lines, you create a custom subclass of BaseGame for your application. Learn more from the jME Users Guide and zathrasbeginnersfaq.

During development it's enough to run your Java application from the IDE. But for a release you want other people to be able to run it outside the IDE. You need an executable distribution, optimally it should be only one file.

Advanced Tip: Do you want to save space and create smaller executables? Then remove the complete jME-2.0.jar from the Libraries node and instead add the individual JARs from the jME_2.0_Distribution directory. The jME_2.0_Distribution is 15MB smaller because it doesn't contain any examples or sample media.

• If your app depends on one of those samples, you have to copy these files over into your packages.
• You may need to fix some imports etc after this change (use code completion).
• You will also have to redo the step of assigning javadoc and sources (chapter 4).

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/jogl.jar lib/jorbis-
 0.0.17.jar lib/lwjgl.jar lib/lwjgl_util.jar lib/lwjgl_util_applet.jar
  lib/swt.jar lib/jME_2.0.jar lib/swing-layout-1.0.3.jar lib/one-jar-a
 nt-task-0.96.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" />
    <echo>OneJAR: Creating distributable OneJAR</echo>
    <target name="dist-onejar" depends="jar"
            description="Creates a standalone OneJAR distribution">
        <echo>OneJAR: Copying natives to ${dist.jar.dir} </echo>
        <copy todir="${dist.jar.dir}/natives">
            <fileset dir="../jME2/jME_2.0_Complete_(r4093)/lib/natives/" />
        </copy>
        <echo>OneJAR: Composing HelloApp.jar</echo>
        <one-jar destfile="${dist.jar.dir}/HelloApp.jar" manifest="onejar.mf">
            <main>
                <fileset dir="${build.classes.dir}/" />
            </main>
            <lib>
                <fileset file="${dist.jar.dir}/lib/*.*" />
            </lib>
            <binlib>
                <fileset file="${dist.jar.dir}/natives/*.*" />
            </binlib>
        </one-jar> 
        <echo>OneJAR: Done. Run the file using:
        java -jar -Xmx256m HelloApp.jar
        </echo>      
    </target>

Go to the Run menu and Clean and Build the project (or use the toolbar button). A stand-alone HelloApp.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.jar

• Distribute the .bat file together with the .jar file!

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

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

• Distribute the .sh file together with the .jar file!

• Install Apple Developer Tools for Java from http://developer.apple.com
• Open the application /Developer/Applications/Utilities/Jar Bundler and enter the following:
  • Build Information > Main class: Choose HelloApp.jar.
    • Optional: Check Use Mac menu bar.
    • Optional: Add a custom icon.
  • Properties > Maximum Heap Size: 256m.
  • Click the Create Application button, and save the file as HelloApp.app into your project's dist directory.
• The Mac Launcher (.app) can be distributed as a stand-alone file!

(Work in progress)

How to activate Java Web Start:

1. In the Projects window, right-click the project node, and select Properties from the context-menu
2. Open the category Application > Web Start
   1. Check Enable Web Start
   2. Codebase: Local execution
   3. If you like, you can select an icon.
   4. If it's a free open-source game, you can check Allow Offline
   5. Check Self-Signed (?)
   6. Select Application Descriptor (use project main class)
3. Open the category Run
   1. Make certain your project has the right main class set.

Everytime you Clean & Build the project (from Run menu, or click toolbar button), NetBeans will create the JAR and a distributable JNLP file in the dist directory. (TODO: more details: How to link the dynamic libraries? Signing?)

Learn more here: Deploying jME Applications with Webstart

Advanced users may want to build jME themselves from the sources. If you haven't downloaded the sources earlier as described above, do so now:

NetBeans Menu: Team > Subversion > Checkout, enter data from this page

• Repository URL http://jmonkeyengine.googlecode.com/svn/trunk/
• User/Password: Leave blank, check save password. Click Next.
• Repository folder: trunk.
• Point it to a local working directory where you want the download to be saved, e.g. jME2.
• Click Finish. Wait for download to complete.

Since the project contains a pom.xml file, NetBeans recognizes the project as Maven project and you can open it directly.

Now follow the instructions from jme_maven_setup:

• Don't miss the setup commands in the file lib/mvn-lib-install!!
  • The mvn commands configure Maven to find the extra libraries in the lib directory. (Usually Maven downloads libraries from repositories, but these aren't available anywhere.)
  • Running these commands requires a real installation of the Maven tool, not just the NetBeans plugin! (NetBeans does have a GUI for adding Maven dependencies, but copying and running the commands is faster than filling out the panel 7 times.)
• Continue the jme_maven_setup instructions on the command line with mvn clean install

An alternative, if you are more of an Ant whiz: Rename the pom.xml file to whatever (then it will no longer be recognized as a Maven project) and create a “Free-Form Java Project” in NetBeans like it is described here for NetBeans 6.5.