jMonkeyPlatform: Application Deployment

After you have written and tested your game, you want to brand it and distribute it to your users. If you use the build script provided by the jMonkeyPlatform's BaseGame, you have the following deployment options:

Requirements

Since JAR files are platform independent, your customers can play your jMonkeyEngine application on Windows, Mac OS, or Linux. The only requirement is that the user has the free Java 5 or 6 Runtime (or browser plugin) installed. For more information see http://java.com.

Branding

  1. Open your game project in the jMonkeyPlatform's Projects window.
  2. Right-click the project and open the Properties
  3. Open the properties → Application section. Here you do your branding:
    1. Title: the game's name
    2. Vendor: your name
    3. Description: why your game is the coolest ever ;)
    4. Homepage: Your web URL
    5. Splashscreen: Browse to a picture that will be shown while the game loads.
  4. Click OK.
  5. Clean and Build.

Creating the Distributable

When you run the build script provided by the jMonkeyPlatform, it automatically compiles your classes, libraries, and assets. It creates a dist directory in your project directory which contains the executable JAR and a directory with libraries.

In the simplest case, you zip up the dist directory and distribute it to your customers. Companies often have additional tools to create executables and installers.

Here are your deployment options in detail:

Desktop Application (JAR)

The JAR file is the most common deployment method for Java desktop applications. The user downloads the executable JAR file to his machine and runs it to start the game.

  1. Right-click your project and open the Project Properties.
  2. In the Application>Web Start category, make sure the box "Enable Web Start" is not checked. Click OK.
  3. Right-click your project and Clean and Build.
  4. If the build succeeds you see a line similar to
    Building jar: /home/joe/jMonkeyPlatform/MySuperTestGame/dist/MySuperTestGame.jar
    this means the executable JAR has been generated successfully in your project directory.
  5. Zip up the dist directory and distribute it to your users. Make sure to keep the lib directory in it!

Most operating systems execute a JAR when users double-click on it, but you can also create a launcher.

Desktop Executables

jMonkeyPlatform allows you to create launchers for different desktop platforms, like an .exe file for Windows systems, an Application for MaxOSX and a launcher for Linux systems.

  1. Right-click your project and open the Project Properties.
  2. In the Application>Desktop category, select the checkboxes for the platforms you want to distribute to.
  3. Click OK.

When you build your project, zip files for each selected platform will be created in the dist folder that contain all that is needed to run your application on that platform.

Web Start (JNLP)

Web Start allows your users to start your application by simply clicking a link that you provide, for example in a button on your web page. The browser downloads the JAR file and then automatically runs your game in an extra window. The only requirement is that the user's browser has the Java plugin installed. This is a very user-friendly way for your customers to play your game without any extra steps to install it. Optionally, you can set it up so the file is saved to their desktop and can be restarted later, so they do not need to be online to play.

  1. Right-click your project and open the Project Properties.
    1. In the Application>Web Start category, check the box to Enable Web Start.
    2. Check the box to make the application self-signed. :!:
    3. Optionally, check the box to allow offline use.
    4. Make sure Application Descriptor is activated. Click OK.
  2. Right-click your project and Clean and Build. The dist directory is generated.
  3. Upload the contents of the dist directory to a public http server
  4. Either edit the sample launch.html file, or simply add a standard link (A HREF) pointing to your .jnlp file to one of your web pages.
  5. Tell your users to open your page in a webbrowser, and click the link to webstart the application.

Look at the sample launch.html, you can have any custom content around the link. Keep a copy of your launcher file because the jMonkeyPlatform will always regenerate its default launch.html.

Also, see this demo video on creating WebStarts.

Browser Applet

A browser Applet is a Java application that runs in the web browser while the user is visiting your web page. The only requirement is that the user's browser has the Java plugin installed. There is no installation step, the user can play right away in the browser. The user will not be able to save the game to his harddrive, nor can he play offline.

These instrcutions assume that you have already written a game that you want to turn into an Applet. As opposed to other jME3 games, Applets cannot capture the mouse for navigation, so the camera will be switched to dragToRotate mode. The jMonkeyPlatform and the included build script already contain what you need.

To Turn a Project Into an Applet

  1. Right-click your project and open the Project Properties.
    1. In the Application>Applet category, check the box to enable Applet creation.
    2. Change the applet width and height as you want it.
    3. Click OK.
  2. Right-click your project and Clean and Build.

The dist/Applet directory now contains all the files necessary for the game to run as Applet. To test the Applet-based game, run the project in the jMonkeyPlatform.

To Deploy the Game as Applet

  1. Edit the dist/Applet/run-applet.html file in anyway you like. Just keep the Applet code.
  2. Upload the contents of the dist/Applet directory to a public http server.
  3. Access the run-applet.html file using a webbrowser
  4. Click the link to web-start your application.

To Troubleshoot Applets

Android

TODO

Tip: Switching Build Configurations

The jMonkeyPlatform has a Run Configuration menu in the toolbar. Use it to save your various sets of Project Property configuations, and switch between them.

  1. Click the Set Project Configuration popup in the toolbar and choose Customize.
  2. The Project Properties Run section opens. Under Configuration, click New.
  3. Name the saved configuration, for instance "my webstart" vs "my desktop app", or "development" vs "deployment". Click OK.
  4. Make sure the new config is selected in the Set Project Configuration popup above the editor.
  5. Make changes to the Project Properties as described above.

Now you can use the Set Project Configuration popup menu to switch between your run/build configurations.

Tip: Reducing Distribution Size

There may be several parts of the full jMonkeyEngine library that you do not even use in your application. You should leave out the corresponding libraries from your distribution.

To remove unused libraries:

  1. Right-click your project and select "Properties"
  2. Select "Libraries" on the left
  3. Select the "jme3-libraries" entry and press "remove".
    This library package contains all libraries for jME3 and is quite large.
  4. Press the "Add Library" button
  5. Select the "jme3-libraries-lwjgl-minimum" library
  6. Add other jME3 libraries in the same way depending which features you use (jme3-libraries-gui, jme3-libraries-physics, jme3-libraries-video etc.)
  7. Click OK.
  8. Clean, Build and Run the project and make sure you have not missed anything.

view online version