Added BaseAppState

src/docs/asciidoc/jme3/advanced/application_states.adoc

@@ -265,49 +265,23 @@ public class MyAppState extends AbstractAppState {
 
 
 
-=== The Future of AppState
+=== BaseAppState
 
 
-There are plans to change the SimpleApplication in the future. Sometime back it was decided that we should really refactor the Application class. SimpleApplication especially is a mess of 'magic' protected fields that on the one hand makes it really easy to slam some simple one-class application together, but on the other hand does new users no favors because they have no idea where 'cam' and 'assetManager' come from. Unfortunately, lots of code refers to Application and it's tough to change... especially the app states.
+A new link:http://javadoc.jmonkeyengine.org/com/jme3/app/state/BaseAppState.html[BaseAppState] class was introduced as part of the link:https://hub.jmonkeyengine.org/t/jmonkeyengine-3-1-alpha-4-released/35478[updates] being made to the AppState interface. AbstractAppState is the most minimal of the minimal implementations of the AppState interface. You essentially still need to do everything yourself, including getting the funky enable/disable/initialized/terminate logic right. Now you just extend BaseAppState and you get onEnable() and onDisable() already worked out for you.
 
-So, we hatched a plan to convert the Application class to an interface. This would give us some freedom to iterate on a new set of application base classes. You can read about the changes link:https://hub.jmonkeyengine.org/t/jmonkeyengine-3-1-alpha-4-released/35478[here]. As said before we are envisioning a better design, that is not enforced today, but that is already usable. 
+Notable BaseAppState changes are as follows:
 
-If you look at SimpleApplication default constructor you will understand how it works. 
+*  You no longer need to call super.initialize(stateManager, app) because it is now called by BaseAppState upon initialization for you.
+*  You no longer have to cast SimpleApplication to have access to AssetManager, AppStateManager, and you can even get a State directly. The getters getApplication(), getAssetManager(), getState(type) and thier methods are available to you immediately. However, you still have to cast SimpleApplication to get rootNode.
+*  You no longer call super during cleanup, its done for you now.
+*  It is now safe to do all initialization and cleanup in the onEnable()/onDisable() methods. Choosing to use initialize() and cleanup() for this is a matter of performance specifics for the implementor.
+*  Cleanup and setEnabled now have logging built in.
 
-[source,java]
-----
-public SimpleApplication() {
-    this(new StatsAppState(), new FlyCamAppState(), new AudioListenerState(), new DebugKeysAppState());
-}
-----
-
-Basically the application is injected upon construction with the default AppStates. Lets look at the second constructor.
-
-[source,java]
-----
-public SimpleApplication( AppState... initialStates ) {
-    super(initialStates);
-}
-----
+You use BaseAppState no differently than AbstractAppState, other than mentioned above, and which one you use is entirely up to you. However, BaseAppState makes your life easier and is the recommended one to use now.
 
-It allows you to specify what AppState you want for your application. So SimpleApplication is handy for test projects (I very often use it as is) but I recommend for a full blown game to use it like this:
+If you use netbeans or the jme SDK you can add the following template to your IDE.
 
-[source,java]
-----
-public class MyGame extends SimpleApplication {
-    
-    public MyGame(){
-         super(new MyCustomSate(), new AnotherState(), ....);
-    }
-
-    public static void main(String[] args) {
-        MyGame app = new MyGame();
-        app.start();
-    }
-
-}
-----
 
-Then have all logic implemented in AppStates and your SimpleApplication will never change much, except when you want to add a bootstrap AppState (or maybe you can have an AppState that manages AppStates...), SimpleApplication is just the list of states you are using.
 
-In future version, all the code in SimpleApplication will be refactored in AppStates (InputHandlingSate, RenderAppState, whatever) and you will decide what you want to use. But for legacy sake we kept the code as is for now.
+See link:http://javadoc.jmonkeyengine.org/com/jme3/app/state/BaseAppState.htmlBaseAppState for more information.