Home

Welcome to the Jme3-utils wiki!

Why should I use this library?

The aim of this library is to lower the amount of boilerplate code that is needed to bootstrap a new jMonkeyEngine application. The library also includes some useful utils classes to deal with Spatials, Geometries, colors, etc. More info can be found on the javadoc.

Bootstrap application

You can create a new jMonkeyEngine application by simply extending the JmeLauncher class and implementing the init() method. That's it!

public class TestApplication extends JmeLauncher {
    
    @Override
    public void init() {
    }
    
}

The JmeLauncher class takes care of a lot of things:

• installs the JUL to SLF4J bridge. This bridge routes all incoming jul records to the SLF4J API.
• disables the pausing of the application when losing focus.
• disables the default settings screen of jMonkeyEngine
• removes the default ESC mapping for closing the application
• initialise Lemur's GuiGlobals instance
• initialise ApplicationGlobals instance
• loads application settings from an application.properties file on the class path.

Configuring the application

When starting the application using the JmeLauncher class, the application will look for an application.properties file on the class path. A custom file can be specified by setting the -Dapplication.configurationFile JVM parameter when starting the application.
e.g. -Dapplication.configurationFile=/home/user/custom.properties

Example application.properties file:

# name of the application
title = My Application

# Specify the resolution in the format: {width}x{height}:{depth}
# eg. 1280x800:32
resolution = 1280x800:32

# the frame rate limit
framerate = 60

An overview of the supported parameters:

Key	Description	Example
title	The title of the application in the title bar.	title = My Application
resolution	The resolution of the application in the format {width}x{height}:{depth}. The default is set to the first available HD resolution.	resolution = 1280x800:32
gammaCorrection	Enable or disable gamma correction. The default is set to true.	gammaCorrection = true
framerate	The framerate of the application. The default is set to -1, no frame rate limit imposed.	framerate = 60
vsync	Enable or disable vsync. The default is set to false.	vsync = true
frequency	Set the frequency of the monitor. The default value is queried from the system. It's best to only use this when the system could not identify the refresh rate of the monitor.	frequency = 60
antiAliasing	Set the anti aliasing value. The value can be 0, 2, 4, 8, 16. The default is set to 0.	antiAliasing = 0
renderer	The OpenGL renderer. The value can be LWJGL-OpenGL2, LWJGL-OpenGL3, LWJGL-OpenGL33, LWJGL-OpenGL4, LWJGL-OpenGL41, LWJGL-OpenGL42, LWJGL-OpenGL43, LWJGL-OpenGL44, LWJGL-OpenGL45. The default is set to LWJGL-OpenGL2.	renderer = LWJGL-OpenGL2
fullscreen	Enable or disable fullscreen. The default is set to false.	fullscreen = false
resizable	Allows the display window to be resized by dragging its edges. True to make a resizable window, false to make a fixed size window. The default is set to false.	resizable = true

Apart from the supported keys, any custom key can be added to the properties file. The values of the keys can be retrieved using the ApplicationProperties class.

Example application

An example application that showcases some of the utility methods of the library:

public class TestApplication extends JmeLauncher {

    public static void main(String[] args) {
        new TestApplication().start();
    }

    @Override
    public void init() {
        // create a sphere
        Geometry sphere = GeometryUtils.createGeometry(new Sphere(32, 32, 1), ColorRGBA.Green, false);

        // create a Lemur label and align it in the center of the screen
        Label label = new Label("My label");
        GuiUtils.center(label);

        // attach the sphere to the scene graph
        ApplicationGlobals.getInstance().getRootNode().attachChild(sphere);
        // attach the label to the GUI
        ApplicationGlobals.getInstance().getGuiNode().attachChild(label);

        // print out our custom specified property
        System.out.println("My specified key: " + ApplicationProperties.getInstance().get("custom.key", "fallback"));
    }

}

application.properties:

title = Jme3-utils test
custom.key = Test from properties

When starting this application you get:

The startup and available settings of the application are logged, this makes debugging a lot easier:

2019-06-05 13:01:12,504 INFO  [main] com.rvandoosselaer.jmeutils.ApplicationSettingsFactory - Loading application settings
2019-06-05 13:01:12,516 DEBUG [main] com.rvandoosselaer.jmeutils.ApplicationSettingsFactory - Supported resolutions: [1440x900:32, 1152x720:32, 1024x768:32, 1024x640:32, 1280x800:32, 800x600:32, 800x500:32, 640x480:32, 720x480:32]
2019-06-05 13:01:12,519 INFO  [main] com.rvandoosselaer.jmeutils.ApplicationProperties - No application.configurationFile property found, loading default /application.properties
2019-06-05 13:01:12,525 DEBUG [main] com.rvandoosselaer.jmeutils.ApplicationSettingsFactory - Settings: {DepthBits=24, UseInput=true, FrameRate=60, MinHeight=0, DisableJoysticks=true, Title=Jme3-utils test - 0.1.0, GammaCorrection=true, SwapBuffers=true, AudioRenderer=LWJGL, Resizable=false, MinWidth=0, VSync=true, Samples=0, StencilBits=0, SettingsDialogImage=/com/jme3/app/Monkey.png, Renderer=LWJGL-OpenGL2, OpenCLPlatformChooser=com.jme3.opencl.DefaultPlatformChooser, Frequency=0, Height=800, Fullscreen=false, OpenCL=false, BitsPerPixel=32, Width=1280}
2019-06-05 13:01:13,288 DEBUG [jME3 Main] com.rvandoosselaer.jmeutils.ApplicationGlobals - Initializing ApplicationGlobals with TestApplication@339aca90
My specified key: Test from properties

Notice the last line of the log, printing out the key in the application.properties file.