The com.jme3.app.state.AppState class is a customizable jME3 interface that allows you to control the global game logic – the overall game mechanics. (To control the behaviour of a Spatial, see Custom Controls instead. Controls and AppStates can be used together.)

There are situations during your game development where you think:

• Mouse and key inputs are handled differently in-game versus in the main menu. Can I group a set of input handler settings, and activate and deactivate them all in one step?
• I have the in-game scene, and a character editor, and a Captain's Quarters screen. Can I group a set of nodes and behaviours, and swap them in and out in one step?
• When I pause the game, I want the character's "idle" animation to continue, but all other loops and game events should stop. How do I define what happens when the game is paused/unpaused?
• I have a conditional block that takes up a lot of space in my simpleUpdate() loop. Can I wrap up this block of code, and switch it on and off in one step?
• Can I package everything that belongs in-game, and everything that belongs to the menu screen, and switch between these two "big states" in one step?

You can! This is what AppStates are there for. An AppState class is subset of (or an extension to) your application. Every AppState class has access to all fields in your main application (AssetManager, ViewPort, StateManager, InputManager, RootNode, GuiNode, etc) and hooks into the main update loop. An AppState can contain:

• a subset of class fields, functions, methods (game state data and accessors),
• a subset of GUI elements and their listeners,
• a subset of input handlers and mappings,
• a subset of nodes that you load and attach to the rootNode,
• a subset of conditional actions that you branch to in the simpleUpdate() loop,
• a subset of other AppStates and Controls
• … or combinations thereof.

Each AppState lets you define what happens in the following situations:

• The AppState is initialized: You load and initialize game data, InputHandlers, AppStates and Controls and attach nodes.
  The AppState has its own simpleInitApp() method, so to speak.
• The AppState has been enabled (unpaused): This toggles a boolean isEnabled() to true. Here you attach nodes and listeners that should become active while it's running.
• While the AppState is running/paused: You can poll isEnabled() to define paused and unpaused game behaviour in the update() loop that. Polls and modify the game state, modify the scene graph, and triggers events. If !isEnabled(), write code that skips the running sections of this AppState's update() loop.
  Each AppState has its own update loop, which hooks into the main simpleUpdate() loop (callback).
• The AppState has been disabled (paused): This toggles a boolean isEnabled() to false. Switch to your specific "paused" state.
• The AppState is cleaned up: Here you decide whether to save this AppState's game state, unregister Controls and InputHandlers, detach related AppStates, and detach nodes from the rootNode.

To implement game logic:

1. Create one AbstractAppState instance for each set of game mechanics.
2. Implement game behaviour in the AppState's update() method.
   • You can pass custom data as arguments in the constructor.
   • The AppState has access to everything inside the app's scope via the Application app object.
3. Attach the AppState to the AppStateManager (stateManager.attach(myAppState);).
4. Activate and deactivate (unpause and pause) the AppStates that you need.

When you add several AppStates to one Application and activate them, their initialize() methods and update() loops are executed in the order in which the AppStates were added to the AppStateManager.

JME3 comes with a BulletAppState that implements Physical behaviour (using the jBullet library). You, for example, could write an Artificial Intelligence AppState to control all your enemy units. Existing examples in the code base include:

• BulletAppState controls physical behaviour in PhysicsControl'ed Spatials.
• TestAppStates.java an example of a custom AppState
  • RootNodeState.java

The AppState interface lets you initialize sets of objects, and hook a set of continously executing code into the main loop.

super.initialize(stateManager, app);
this.app = (SimpleApplication) app;

The AbstractAppState class already implements some common methods (isInitialized(), setActive(), isActive()) and makes creation of custom AppStates a bit easier. We recommend you extend AbstractAppState and override the remaining AppState methods: initialize(), setEnabled(), cleanUp().

Definition:

public class MyAppState extends AbstractAppState {
 
    private SimpleApplication app;
 
    private Node x = new Node("x");  // some custom class fields...    
    public Node getX(){ return x; }  // some custom methods... 
 
    @Override
    public void initialize(AppStateManager stateManager, Application app) {
      super.initialize(stateManager, app); 
      this.app = (SimpleApplication)app;          // cast to a more specific class
 
      // init stuff that is independent of whether state is PAUSED or RUNNING
      this.app.getRootNode().attachChild(getX()); // modify scene graph...
      this.app.doSomething();                     // call custom methods...
   }
 
   @Override
    public void cleanup() {
      super.cleanup();
      // unregister all my listeners, detach all my nodes, etc...
      this.app.getRootNode().detachChild(getX()); // modify scene graph...
      this.app.doSomethingElse();                 // call custom methods...
    }
 
    @Override
    public void setEnabled(boolean enabled) {
      // Pause and unpause
      super.setEnabled(enabled);
      if(enabled){
        // init stuff that is in use while this state is RUNNING
        this.app.getRootNode().attachChild(getX()); // modify scene graph...
        this.app.doSomethingElse();                 // call custom methods...
      } else {
        // take away everything not needed while this state is PAUSED
        ...
      }
    }
 
    @Override
    public void update(float tpf) {
      if(isEnabled()){
        // do the following while game is RUNNING
        this.app.getRootNode().getChild("blah").scale(tpf); // modify scene graph...
        x.setUserData(...);                                 // call some methods...
      } else {
        // do the following while game is PAUSED, e.g. play an idle animation.
        ...        
      }
    }
 
}

You define what an AppState does when Paused or Unpaused, in the setEnabled() and update() methods. Call myState.setEnabled(false) on all states that you want to pause. Call myState.setEnabled(true) on all states that you want to unpause.

The com.jme3.app.state.AppStateManager holds the list of AppStates for an application. AppStateManager ensures that activate AppStates can modify the scene graph, and that the update() loops of active AppStates is executed. There is one AppStateManager per application. You typically attach several AppStates to one AppStateManager, but the same state can only be attached once.

The AppStateManager's render(), postRender(), cleanUp() methods are internal, ignore them, users never call them directly.

You can only access other AppStates (read from and write to them) from certain places: From a Control's update() method, from an AppState's update() method, and from the SimpleApplication's simpleUpdate() loop. Don't mess with the AppState from other places, because from other methods you have no control over the order of modifications; the game can go out of sync because you can't know when (during which half-finished step of another state change) your modification will be performed.

You can use custom accessors to get data from AppStates, to set data in AppStates, or to trigger methods in AppStates.

this.app.getStateManager().getState(MyAppState.class).doSomeCustomStuffInThisState();

To access class fields of the application the way you are used to, initialize them to local variables:

private SimpleApplication app;
private Node              rootNode;
private AssetManager      assetManager;
private AppStateManager   stateManager;
private InputManager      inputManager;
private ViewPort          viewPort;
private BulletAppState    bullet;
 
public void initialize(AppStateManager stateManager, Application app) {
  super.initialize(stateManager, app);
  this.app = (SimpleApplication) app; // can cast Application to something more specific
  this.rootNode     = this.app.getRootNode();
  this.assetManager = this.app.getAssetManager();
  this.stateManager = this.app.getStateManager();
  this.inputManager = this.app.getInputManager();
  this.viewPort     = this.app.getViewPort();
  this.bullet       = this.stateManager.getState(BulletAppState.class);
}