Chapter 1. Installing jMonkeyEngine

When a group of heroes set out on a quest, they grab their armor and weapons—when you set out on a game development adventure, you grab the jMonkeyEngine SDK.

The jMonkeyEngine Software Development Kit (SDK) contains everything that you need to get started quickly: the jMonkeyEngine libraries, Javadoc, sample code, and lots of nifty game development utilities. This bundle also includes all necessary native libraries, such as LightWeight Java Game Library (LWJGL). This means there is no second installation step, neither for the development team, nor for users of the games that we create.

In this chapter you will learn:

What the hardware and software requirements are
How to install the jMonkeyEngine SDK
How the tools in the jMonkeyEngine SDK make a developer's life easier
How to create and distribute jMonkeyEngine games

Installation requirements for game developers

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.

Time for action – installing the jMonkeyEngine SDK

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

Go to http://jmonkeyengine.org/downloads/.
Download the jME3 SDK for your operating system and unzip it, if necessary.
Double-click on the installer and complete the installation wizard.

It's time for your first test run:

Find the jMonkeyEngine SDK icon in your Applications folder or Start menu and double-click on it to run the SDK.
When the jMonkeyEngine SDK opens for the first time, a dialog box asks you to specify a folder for storing your projects. Browse to your home directory, click on the Create new folder button, and name the folder jMonkeyProjects.
With your new folder still selected, click on Set Project Folder to close the dialog box.

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.

jMonkeyEngine SDK at your service

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:

The jMonkeyEngine JAR files and native libraries are on the classpath
Javadoc popups and code completion for jMonkeyEngine methods are set up in the source editor
The provided Ant build script is ready to build, run, and deploy your application

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.

Tip

Did you know?

jMonkeyEngine SDK is built on top of the NetBeans Platform. This means that you can install all kinds of NetBeans IDE plugins. The NetBeans plugins prepackaged in the jMonkeyEngine SDK include version control tools and a Java debugger. Open the jMonkeyEngine SDK and choose Tools | Plugins from the menu, then click on Available Plugins to browse and install other cool add-ons for free, such as a Java profiler.

Can I work in other Java IDEs?

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?

Time for action – running a demo

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.

Choose File | New Project from the menu to open the New Project wizard.
Select JME3 Tests from the jME3 category.
Accept the defaults and complete the wizard.

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:

Right-click on JME3 Tests and click on Build and Run. Wait for the TestChooser window to open.
For example, select the TestWalkingChar demo and click on OK.
Tip
Type walking into the filter box to find it more quickly.
Accept the default display settings and click on OK.
When the demo opens, use the WASD keys and drag the mouse to navigate the simple scene. Press the Space bar to shoot fireballs.
When you have seen enough of this demo, the press Esc key. Either select another demo, or click on Cancel to exit.

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

What just happened?

It's good to know that, during the development process, you can always return to the JME3 Tests demos for inspiration. Browse the demo's Source Package if you are looking for code samples that showcase particular features. Feel free to modify your copy of the code samples and experiment. In the unlikely case that you break the project, you can always recreate the JME3 Tests template from the New Project menu.

Restoring the demos is as easy as creating a fresh game project, which is what we will do next.

Time for action – creating a project

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:

Choose File | New Project from the menu
Select BasicGame from the jME3 category.
You can rename the project here, but for now, accept the defaults and complete the wizard.

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:

Open the BasicGame project's Source Packages, and double-click on the mygame/Main.java file to open it. You see that the JDK contains a full-featured editor for Java files.
Right-click on the BasicGame project and click on Build and Run.
Accept the default display settings and click on OK.
The application window opens and shows a blue 3D cube on a black background. If this works, you know that your project is set up correctly.
Press the Esc key to quit the BasicGame project's window.

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.

Assets and the art pipeline

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:

Lay out concept art, either digital or on paper, to get an idea of what you need; you do this in parallel to planning your Java object model.
Insert mock-up art in alpha builds: these sample files don't look and sound like the real thing yet. They are merely placeholders in the right size and format that help you debug your loading code.
Insert drafts in beta builds that are close to the final look and feel that you want; this helps you beta test and iron out the kinks.
Include the final artwork in the release builds. Typically, assets are converted to data formats that are optimized for the target platform.

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:

Supported File Type	Usage
`.mesh.xml`, `.material`, `.skeleton.xml`, `.scene`	Ogre Mesh XML (3D models) Ogre DotScene (3D scenes)
`.obj`, `.mtl`	Wavefront objects (3D models)
`.blend`	Blender files (3D models)
`.jpg`, `.png`, `.tga`, `.gif`, `.dds`, `.hdr`, `.pfm`	Images and textures
`.fnt`	Bitmap fonts
`.wav`, `.ogg`	Wave and OGG Vorbis audio

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

http://Blender.org: This is a full-featured mesh editor for 3D models and scenes
http://Gimp.org: This is a graphic editor for images and textures
http://Audacity.sourceforge.net: This is a sound editor for audio files

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?

Time for action – distributing a 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:

Right-click on the BasicGame project in SDK, and open the project's Properties window.
Go to the Application | Desktop pane and select the checkboxes for your target operating systems, for example Windows, Mac, and Linux. Click on OK.
Right-click on the BasicGame project, and Clean and Build it.

Look into the Output window to follow the build process.

What just happened?

When the build is finished, switch to your operating system's file explorer:

Browse to the jMonkeyProjects/BasicGame/dist/ folder in your user home.
Unzip and run the BasicGame executable for your operating system.
The application window opens and displays the blue cube demo. Press the Esc key to quit.

This exercise shows you that the SDK generates distributable builds of your BasicGame project that runs fine on your desktop, outside the jMonkeyEngine SDK.

Impressive—you have just built a basic 3D application that runs on the three most widely used operating systems. Notice how you didn't have to configure any CLASSPATH or library paths.

Can I sell my jMonkeyEngine game?

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

You do not pay any fees to use the jMonkeyEngine libraries or SDK
You can use the jMonkeyEngine for hobby, educational, or commercial purposes
You can include the jMonkeyEngine libraries in a Java application that you sell or give away for free
You can offer your application that includes the jMonkeyEngine libraries as download, serve it over the network, or distribute it on digital media
Using the jMonkeyEngine does not require you to open source your own code (but you can)

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.

Summary

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!

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.

What do you get with Print?