jMonkeyEngine 3.0 : Beginner's Guide: Whether you want to design 3D games with Java for love or for money, this is the primer you need to start using the free libraries of jMonkeyEngine 3.0. All hands on, all fun – it makes light work of learning.

At the time of printing, the jMonkeyEngine SDK needs 40 MB of memory, plus enough memory to load the particular game's assets. Your computer should have a minimum of 1 GHz CPU, and your graphic card must support OpenGL 2.0, or better. Suitable graphic cards include ATI Radeon 9500, NVIDIA GeForce 5 FX, Intel GMA 4500, and all newer ones.

You can use the jMonkeyEngine SDK on all operating systems that support the Java Development Kit 6 (JDK 6) or better. Currently this includes Windows XP/Windows Vista/Windows 7 or better, Mac OS X 10.5 or better, and Linux kernel 2.6 or better.

Enter the following command in your terminal to check whether you have the required Java Development Kit (JDK) installed:

javac -version

If this command returns javac 1.6.x or better, then your Java installation is set to go. If you still need to install the JDK, click on the Download JDK button at http://www.oracle.com/technetwork/java/javase/downloads/index.html and follow the installation instructions there.

The jMonkey team devised the jMonkeyEngine SDK to make the installation process as smooth as possible:

It's time for your first test run:

When the SDK opens, you will see the following application screen:

The Projects window, on the top left-hand side, is where you will browse Java files and manage Java packages, among other things. The SDK also contains an editor window for Java files, not visible here, that we will look at in a minute. At the bottom right-hand side of the screen, you see the Output - Application window; this is where build messages, runtime exceptions, warnings, and println() appear.

In the center, you see the OpenGL Window. We will use it later to preview the 3D scenes that we created using the Properties, SceneExplorer, and SceneComposer windows, not visible here.

The other two windows you can ignore for now. Later you may use the FilterExplorer window to configure special effects, and the AssetPackBrowser window to bundle up collections of 3D models.

Congrats, your tools are ready, and you have accomplished your first mission. Let's take a closer look at the jMonkeyEngine SDK.

The jMonkeyEngine SDK is your graphical user interface for the jMonkeyEngine library. The jMonkey team devised this integrated development environment (IDE) especially for 3D game development with Java. The jMonkeyEngine SDK assists you from start to end, whether you write code, integrate game assets, lay out scenes, or deploy the finished application.

Creating your Java game projects with jMonkeyEngine SDK has the added value that they are already preconfigured:

At the same time, there is nothing proprietary about the projects that the SDK creates: you are looking at standard Java SE projects. The SDK's clean, build, and run actions are automated using standard Ant build scripts. The Apache Ant build tool is already included when you install the SDK.

Although this book will repeatedly tell you how awesome the jMonkeyEngine SDK is, you are not forced to use it for coding. The jMonkeyEngine library is open source software: If you download the latest binary bundle from http://www.jmonkeyengine.com/nightly/, you can manually add the JAR files from the lib directory to your CLASSPATH, just like any other Java library. You can link these libraries in your favorite Java IDE, or do your Java development in a text editor on the command line if that's how you roll.

For now, let's continue using the SDK because it will get you started more swiftly. This book strives to keep code samples IDE-independent. If a shortcut or workflow only applies to the jMonkeyEngine SDK, it will be clearly pointed out as such.

Nonetheless you should give the jMonkeyEngine SDK a try. It contains many plugins that you will not find in generic IDEs: an asset pack manager and file converters for 3D models, a scene viewer and scene composer, a terrain editor, a procedural texture generator, a code snippet palette, and much more. Try it! If you are not convinced by the end of this book, you will find setup instructions for other IDEs in the appendix. Deal?

In order to test whether everything was installed correctly, let's run a few demos. A set of demos comes bundled with the jMonkeyEngine SDK as one of the project templates.

The SDK unpacks the bundled demos and makes copies of the demo sources. The new JME3 Tests project appears in the Projects window.

To run a demo:

Now that you know how to use the TestChooser, run some demos to see what is possible with jMonkeyEngine.

The jMonkeyEngine SDK provides you with a preconfigured project template that gets you started at lightning speed.

This is how you create a new project:

A new Java project named BasicGame appears in the Projects window, next to the JME3 Tests project.

The BasicGame project contains a simple Main.java template. Let's try to run this Java application:

As you can see, it's easy to create and run fully preconfigured game projects in the jMonkeyEngine SDK.

What just happened?

Let's open the BasicGame folder in the Projects window and look at the project structure that the SDK has just created for you.

You can see that the Projects window gives you access to three important areas: Project Assets, Source Packages, and Libraries, as well as the build script.

The Projects window shows the logical structure of a jMonkeyEngine project. This view only displays files that you need during development, and it filters out build folders and configuration files. For comparison, have a look at the project's physical structure, which lets you browse the actual files on your hard drive; choose Window | Files from the menu to open the Files window. Click the triangles to open the subsections and compare the two views, as shown in the previous screenshot.

Browse the Libraries section in the Projects window. You can see that it lists all the JAR files that are preconfigured on this project's CLASSPATH. Compare this to the physical dist/lib directory in the Files window.

If you know about Ant build scripts, you may want to open the Important Files node in the Projects window and browse the preconfigured Ant targets. Compare this to the physical build file, build.xml in the Files window.

You will see that a jMonkeyEngine-based application is a standard Java project made up of the following files and folders:

Project folder	Usage
JMonkeyProjects/BasicGame/assets	You store multimedia assets here
jMonkeyProjects/BasicGame/build/	The SDK generates build classes here
jMonkeyProjects/BasicGame/build.xml	You customize the Ant build script here
jMonkeyProjects/BasicGame/dist/	The SDK generates executables here
jMonkeyProjects/BasicGame/nbproject/	The SDK stores the default build script and metadata here
jMonkeyProjects/BasicGame/src/	You store source code here
jMonkeyProjects/BasicGame/test/	You store JUnit test classes here (optional)

Certain files and folders are automatically created and maintained by the jMonkeyEngine SDK such as build, dist, and nbproject. The SDK recreates these files and folders when you build the application, so do not edit them.

The other folders, highlighted in yellow, contain your sources and assets. Using the test folder is optional; for now, just ignore it. As in any Java project, you have full control over the project's build.xml file, and your two main folders, assets and src.

Switch back to the Projects window. You see that the Project Assets folder corresponds to jMonkeyProjects/BasicGame/assets/, and the Source Packages folder corresponds to jMonkeyProjects/BasicGame/src/. You are free to set up subfolders and packages inside these two folders, as your project requires.

Your Java classes obviously go into Source Packages, but what does the Project Assets folder contain? Open the Project Assets folder and look inside: you will see subfolders for Sounds, Textures, and Models. This folder is where you store your multimedia content.

Every 3D game requires some multimedia assets, whether it's 3D models, image files, sound clips, video clips, or music. This book focuses on the development aspect—how to tie assets and code together and deploy the game. Being able to write source code only takes you halfway there: to develop games, you also need to go through the art pipeline.

By art pipeline we mean the creative process of creating 3D models, composing background music, and so on. The art pipeline runs in stages parallel to your coding milestones:

Including sounds and images in your game means that you either need access to a multimedia library, or you need to create your assets using external tools.

The jMonkeyEngine SDK does not include any multimedia editors. This is because a game engine should not prescribe the artist's choice of design software. You are free to create assets in any third-party tools that you fancy and have access to. Just make certain that you can export the artwork in formats that jMonkeyEngine supports.

The following external file types are supported by jMonkeyEngine:

If you have not chosen your multimedia tools yet, the following are some suggestions of popular editors that support the formats mentioned earlier:

All of these are examples of software that is available for Windows, Mac OS, and Linux; all three are open source, and you can download and use them for free.

There are many more free and paid design tools available if you do a search. Whichever software you choose to create your assets, consult the respective manuals for details on how to use them. 3D modeling in particular is not a trivial task, but it's definitely worth learning.

Now that you have the design and development tools installed, you have everything you need to create your game.

But what do your users install to play your game?

During the development phase, you typically build and run your game right from the jMonkeyEngine SDK. Your users, however, neither have nor want the SDK. They expect to run the game by, for instance, executing a desktop application that runs on their Java Virtual Machine.

Switch to the Files window, and look into the dist folder. Every time you Build this project, the SDK generates an executable JAR file here. When you right-click on the project and choose Clean, the dist folder is deleted—so remember never to move any unique files there.

Let's go through the basic deployment process together:

Look into the Output window to follow the build process.

Yes, the jMonkeyEngine SDK is a free open source software released under the BSD license. To answer the most common questions right away:

All that is required from you is that you adhere to the BSD license, and keep the license together with the jMonkeyEngine libraries included in your distribution. Simply copy the license from the jMonkeyHomepage. Don't worry, it's nice and short and can be found at http://jMonkeyEngine.org/wiki/doku.php/bsd_license.

In this chapter you learned how to install the jMonkeyEngine SDK and run sample applications. You saw that it is easy to get started with game development using the jMonkeyEngine SDK, and how easy it is to distribute a game using the jMonkeyEngine SDK.

Come on over to the next chapter, where we write some actual code!