jMonkey Wiki

The jME3 Threading Model

jME3 is similar to Swing in that, for speed and efficiency, all changes to the scene graph must be made in a single update thread. If you make changes only in Control.update(), AppState.update(), or SimpleApplication.simpleUpdate(), this will happen automatically. However, if you pass work to another thread, you may need to pass results back to the main jME3 thread so that scene graph changes can take place there.

public void rotateGeometry(final Geometry geo, final Quaternion rot) {
    mainApp.enqueue(new Callable<Spatial>() {
        public Spatial call() throws Exception {
            return geo.rotate(rot);
        }
    });
}

Note that this example does not fetch the returned value by calling get() on the Future object returned from enqueue(). This means that the example method rotateGeometry() will return immediately and will not wait for the rotation to be processed before continuing.

If the processing thread needs to wait or needs the return value then get() or the other methods in the returned Future object such as isDone() can be used.

Multithreading Optimization

First, make sure you know what Application States and Custom Controls are.

More complex games may feature complex mathematical operations or artificial intelligence calculations (such as path finding for several NPCs). If you make many time-intensive calls on the same thread (in the update loop), they will block one another, and thus slow down the game to a degree that makes it unplayable. If your game requires long running tasks, you should run them concurrently on separate threads, which speeds up the application considerably.

Often multithreading means having separate detached logical loops going on in parallel, which communicate about their state. (For example, one thread for AI, one Sound, one Graphics). However we recommend to use a global update loop for game logic, and do multithreading within that loop when it is appropriate. This approach scales way better to multiple cores and does not break up your code logic.

Effectively, each for-loop in the main update loop might be a chance for multithreading, if you can break it up into self-contained tasks.

Java Multithreading

The java.util.concurrent package provides a good foundation for multithreading and dividing work into tasks that can be executed concurrently (hence the name). The three basic components are the Executor (supervises threads), Callable Objects (the tasks), and Future Objects (the result). You can read about the concurrent package more here, I will give just a short introduction.

A Callable is one of the classes that gets executed on a thread in the Executor. The object represents one of several concurrent tasks (e.g, one NPC's path finding task). Each Callable is started from the updateloop by calling a method named call().
The Executor is one central object that manages all your Callables. Every time you schedule a Callable in the Executor, the Executor returns a Future object for it.
A Future is an object that you use to check the status of an individual Callable task. The Future also gives you the return value in case one is returned.

Multithreading in jME3

So how do we implement multithreading in jME3?

Let's take the example of a Control that controls an NPC Spatial. The NPC Control has to compute a lengthy pathfinding operation for each NPC. If we would execute the operations directly in the simpleUpdate() loop, it would block the game each time a NPC wants to move from A to B. Even if we move this behaviour into the update() method of a dedicated NPC Control, we would still get annoying freeze frames, because it still runs on the same update loop thread.

To avoid slowdown, we decide to keep the pathfinding operations in the NPC Control, but execute it on another thread.

Executor

/* This constructor creates a new executor with a core pool size of 4. */
ScheduledThreadPoolExecutor executor = new ScheduledThreadPoolExecutor(4);

Pool size means the executor will keep four threads alive at any time. Having more threads in the pool means that more tasks can run concurrently. But a bigger pool only results in a speed gain if the PC can handle it! Allocating a pool that is uselessly large just wastes memory, so you need to find a good compromise: About the same to double the size of the number of cores in the computer makes sense.

!!! Executor needs to be shut down when the application ends, in order to make the process die properly In your simple application you can override the destroy method and shutdown the executor:

@Override
public void destroy() {
    super.destroy();
    executor.shutdown();
}