Java3DGamingWithNetBeans

Developing 3-D Games with the NetBeans IDE and jME 2.0.1

Contents


By rkusterer AT netbeans DOT org

This tutorial shows how to set up the NetBeans IDE to start creating Java 3-D games with the jMonkeyEngine framework. jME 2.0.1 now supports Solaris additionally to Windows (32/64-bit), Linux (32/64-bit), and Mac OS X, and the library path set-up of this tutorial was updated (October 2009).


Note: jMonkeyEngine version 3 (currently in alpha) comes with an integrated IDE based on the NetBeans platform that includes tools for model and material loading, conversion, editing and more called "jMonkeyPlatform". See http://jmonkeyengine.org/wiki/doku.php/jme3:jmonkeyplatform for more information.


  • The jMonkeyEngine is a 3-D engine for developing 3-D computer games. jME is not Drag'n'Drop, you have to code everything by hand, but the quality of the result makes it worth to be patient and learn it: Have a look at these 3-D apps created with jME.
  • jME provides you with a 3-D scene graph, a main event loop, a camera view, methods for loading 3-D models and animations, 3-D audio, input control (keyboard, mouse, joystick), collision detection, ray casting, cool special effects (water, fire, particle swarms, cloth, etc), and more.
  • The optional jME Physics framework adds dynamics (gravity, momentum, friction) to 3-D objects. You need a physics engine if you develop dynamic games like pinball, pool/snooker, pong, bowling, car racing. (Not covered here.)

Requirements:

Image:java-3d-game-samples_Java3DGamingWithNetBeans.png

0. File Tree Overview

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 file in one package, hello3d/test/HelloWorld.java .
NetBeansProjects/
  Hello3D/
    src/hello3d/test/HelloWorld.java
    build/classes/hello3d/test/HelloWorld.class
    build.xml
    dist/
      Hello3D.jar
      lib/                     (JAR libraries)
      natives/                 (native libraries)
  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...)
  nbjme/
    dist/javadoc

This NetBeans-ready sample project still uses jME 2.0 (to be updated).

1. Downloading the jME Framework

To get the jME framework:

  1. Create a directory jME2 in your NetBeansProjects directory: C:\Users\Joe\Documents\NetBeansProjects\jME2
  2. Go to http://code.google.com/p/jmonkeyengine/downloads/list and download jME2_0_1-Stable.zip. It contains all JARs and native libraries needed to use jME.
  3. Unpack the zip archive and save the jME2_0_1-Stable directory into the jME2 directory.

Next we create a NetBeans project and configure it to include the jME framework. This project will contain your future game application.

2. Setting up a jME-based Project in Netbeans

Start with an empty NetBeans Java project. We configure it to find jME library JARs on the Classpath, and to find necessary native dynamic libraries on the java.library.path.

2.1 New NetBeans project

  1. In NetBeans: 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 the directory where you want to save your project, for example C:\Users\Joe\Documents\NetBeansProjects\
    3. You do not need to set a Libraries Folder.
    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.

2.2 jME JARs on the 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 and into each subdirectory (lwjgl, junit, jorbis, jogl, swt). Multi-select all the JARs in these subdirectories.
    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 Libraries node: Here you see the JAR libraries that are on your project's classpath.

Image:jar-libraries_Java3DGamingWithNetBeans.png <- This screenshot is outdated

2.3 Native Dynamic Libraries on the Java Library Path

Files with suffices such as .dll, .so, .dylib, and .jnilib are called native dynamic libraries. They contain libraries that allow the 3-D Java application to run on all major operating systems: win32, win64, linux32, linux64, macosx, solaris! In jME2.0.1, these files are spread out over several directories (because some have the same name), so the path looks quite ghastly -- but it gives you really awesome platform independence.

  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 the path to the native libraries in the \jME2\jME2_0_1-Stable\lib\lib\*\native\*\ directories. -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_amd64/:../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_amd64/:../jME2/jME2_0_1-Stable/lib/lib/jogl/native/windows_i586/"
  2. Close the Properties window.

Note that : is the path separator for Unix. You need to use ; as a path separator for Windows.

Your Java project is now set up to use the jME framework.

Image:java-library-path_Java3DGamingWithNetBeans.png <- this screenshot is outdated

Next we fill in test code and run the project.

3. Running a jME application

3.1 Hello 3-D World!

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

  1. In the IDE's 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 HelloWorld file contains everything you need to create a tiny but fully working jME test application. Let's build and run the HelloWorld sample.

  1. In the Projects window, right-click HelloWorld.java and select Run File. Tip: Press the Shift-F6 keyboard shortcut.
  2. NetBeans builds and runs the file.
  3. If a video configuration window pops up, accept the defaults and click OK.
  4. 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.

Image:jmonkeyengine-helloworld_Java3DGamingWithNetBeans.png

3.2 Troubleshooting

Also known as java.lang.UnsatisfiedLinkError: no lwjgl in java.library.path

If you get the infamous runtime error about the java library path, check step 2.3 again. Typos or a misformed path are the main sources of error when setting up this framework. It has to be surrounded by normal quotation marks, and the whole library path has to be on one line. More about troubleshooting jME here and here in the jME documentation.

3.3 Optional: How to Get More Sample Code

You have several alternatives:

  • This NetBeans-ready sample project is very similar to the above HelloWorld: It shows a sommersaulting teapot and contains a custom packaging Ant script.
  • Copy any of the files from TutorialGuide in the same way as described, You should be able to run any sample file that has a main method. (Note: TestPongCool.java also requires ExplosionFactory.java to be present.)
  • Browse the source code online or on your hard drive at jME/jME2_0_1-Stable/src. You can learn a lot about using each feature from examples.

4. Optional: Helpful IDE Features

I recommend activating useful IDE features, such as automatic code completion and javadoc pop-ups, which is very helpful when learning a new framework.

4.1 Building from the Sources to Run Demos

  1. In NetBeans, choose New Project > Java > Java Project With Existing Sources. Click Next.
    1. Type nbjme as project name, and NetBeansProjects as project folder.
    2. Uncheck Set as main project. (Your game is your main project, this is just auxiliary.)
    3. Leave the rest as it is, and click Next.
    4. Under Source Package Folders, click Add Folder and browse to jME/jME2_0_1-Stable/src. Click Add and then Finish.
  2. Important: Now go back up to the chapter 2.2 and 2.3 about setting up the class path and the java library path! Complete both steps for the newly created nbjme project.
  3. Wait until “scanning projects” has completed, then look at the nbjme project in the Projects window. As soon as all red error badges have disappeared, you have got all the JARs set up. Seeing blue badges is okay.
  4. In the Projects window, right-click nbjme and Clean and Build. Wait a minute.
  5. When it's successfully done building, right-click nbjme and choose Run.
  6. If it asks you to select the main class, you must select jmetest.TestChooser. Click OK.
  7. The Test Chooser opens, pick one of the samples and have a look!

The test chooser demonstrates what jME is capable of. You find each example's source code in the jME/jME2_0_1-Stable/jmetest directory (under Source Packages in the nbjme's Project window). Read the sample's sources to learn how to use a feature. Remember, to see the test chooser again, just right-click the nbjme project and choose Run.

4.2 Activating Documentation Popups

Note: You must have completed 4.1 before you can set this up.

  • Right-click nbjme in the Projects window and choose Build javadoc from the menu.
  • Documentation will be extracted from the sources and saved in a browsable format.
  • This process takes quite a while, but you can already continue with the steps below.
  • When the IDE done generating javadoc, the jME documentation will automatically open in your web brower. Bookmark the page for later.
  1. In the Projects window, right-click nbjme's Libraries node, and choose Properties from the context-menu.
  2. Go to the Libraries 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 this for each jme*.jar file in the Libraries list!
  4. Close the Properties window.

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

4.3 Activating Source Navigation

  1. In the Projects window, right-click nbjme's Libraries node, 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 sources directory, such as ../jME/jME2_0_1-Stable/src/'
    2. Make certain to check Reference as Relative Path!
    3. Click Select. Click OK.
    4. Do this for each jme*.jar file in the Libraries list!
  4. Close the Properties window.

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

4.4 Making the Most of Helpful IDE Features

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

  • Place the caret into or after a variable or method such as SimpleGame. Press ctrl-space to see available methods and javadoc.
  • Place the caret between method parentheses and press ctrl-p (mac: command-p) to see expected parameters.
  • Ctrl-click (mac: command-click) a variable or method such as rootNode to open the source file, and to see where and how it was defined. (Hyperlink)
  • In the Project window, right-click your project and choose Properties. Under Build > Compiling, check Compile on Save. This way your project will build faster when you click Run (F6).
  • Click the colored marks (right side of the editor) to jump to errors, warnings, and highlighted occurrences.
  • Click the lightbulbs (left side of the editor) for hints and quick fixes, for example fixing import statements.

Learn more about NetBeans from http://www.netbeans.org/kb/.

Image:netbeans-code-completion_Java3DGamingWithNetBeans.png

5. Beyond HelloWorld: Creating Your Own jME Game

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

How? For instance replace this lineBox b=new Box("My box",new Vector3f(0,0,0),new Vector3f(1,1,1)); // Make a boxwithTeapot b=new Teapot("my teapot");Look at the imports section and use the yellow hint to fix the imports to includeimport com.jme.scene.shape.Teapot; Run the HelloWorld again to see the difference.

Some tips:

  • 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 in the package.
  • Use the NetBeans GUI Builder to design the game's intro screen (JFrame). For 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. See also: Threading/concurrency.
  • Create packages to store resources (textures, audio, images). Use getClassLoader syntax to load them.
  • You can keep the hello3d.test package to test things (later just delete it). It's completely fine to use SimpleGame at first.
  • By looking at samples, you gather code snippets for the features your game needs. After you understand the underlying inheritance structure, you can create a custom subclass of BaseGame for your application along the same lines.

Learn more from the jME Users Guide and Zathras' beginners FAQ.

6. Building and Distributing

  • How to run the project:
  • Either set a main class for the whole project like Main.java (Define it under Project Properties > Run) -- then use keyboard shortcut F6 to run the app in the IDE.
  • Or test-run individual files that have a main() method -- then use keyboard shortcut Shift+F6 to run.
Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo