jMonkeyEngine-wiki/docs/modules/core/pages/app/simpleapplication.adoc

= SimpleApplication
:revnumber: 2.1
:revdate: 2020/07/24
:keywords: display, basegame, documentation, intro, intermediate, init, input, game, loop, rootnode, application, simpleapplication


The base class of the jMonkeyEngine3 is `com.jme3.app.SimpleApplication`. Your first game's Main class extends SimpleApplication directly. When you feel confident you understand the features, you will typically extend SimpleApplication to create a custom base class for the type of games that you want to develop.

SimpleApplication gives you access to standard game features, such as a scene graph (rootNode), an asset manager, a user interface (guiNode), input manager, audio manager, a physics simulation, and a fly-by camera. You call app.start() and app.stop() on your game instance to start or quit the application.


[IMPORTANT]
====
For each game, you (directly or indirectly) extend SimpleApplication exactly once as the central class. If you need access to any SimpleApplication features from another game class, make the other class extend xref:app/state/application_states.adoc[AbstractAppState] (don't extend SimpleApplication once more).
====

NOTE: The SimpleApplication class is undergoing changes. To understand how these changes may affect your projects and how to best prepare for them, see  <<tutorials:beginner/hello_simpleapplication.adoc#the-future-of-simpleapplication,The Future of SimpleApplication>> topic in the "`Hello SimpleApplication`" tutorial for beginners.

The following code sample shows the typical base structure of a jME3 game:

[source,java]
----

import com.jme3.app.SimpleApplication;

public class MyBaseGame extends SimpleApplication {

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

    @Override
    public void simpleInitApp() {
       /* Initialize the game scene here */
    }

    @Override
    public void simpleUpdate(float tpf) {
       /* Interact with game events in the main loop */
    }

    @Override
    public void simpleRender(RenderManager rm) {
       /* (optional) Make advanced modifications to frameBuffer and scene graph. */
    }
}
----

Let's have a look at the +++<abbr title="Application Programming Interface">API</abbr>+++ of the base class.


== Application Class

Internally, com.jme3.app.SimpleApplication extends com.jme3.app.Application. The Application class represents a generic real-time 3D rendering jME3 application (i.e., not necessarily a game). Typically, you do not extend com.jme3.app.Application directly to create a game.
[cols="25,75", options="header"]
|===

a|Application class fields
a|Purpose

a|viewPort +
getViewPort()
a|The view object for the default camera. You can register advanced xref:effect/effects_overview.adoc[post-processor filters] here.

a|settings +
setSettings()
a|Use this AppSettings object to specify the display width and height (by default 640x480), color bit depth, z-buffer bits, anti-aliasing samples, and update frequency, video and audio renderer, asset manager. +
See: xref:system/appsettings.adoc[AppSettings].

a|cam +
getCamera()
a|The default xref:renderer/camera.adoc[camera] provides perspective projection, 45° field of view, near plane = 1 wu, far plane = 1000 wu.

a|assetManager +
getAssetManager()
a|An object that manages paths for loading models, textures, materials, sounds, etc. +
By default the xref:asset/asset_manager.adoc[Asset Manager] paths are relative to your project's root directory.

a|audioRenderer +
getAudioRenderer()
a|This object gives you access to the jME3 xref:audio/audio.adoc[audio] system.

a|listener +
getListener()
a|This object represents the user's ear for the jME3 xref:audio/audio.adoc[audio] system.

a|inputManager +
getInputManager()
a|Use the xref:input/input_handling.adoc[inputManager] to configure your custom inputs (mouse movement, clicks, key presses, etc) and set mouse pointer visibility.

a|stateManager +
getStateManager()
a|You use the Application's state manager to activate xref:app/state/application_states.adoc[AppStates], such as xref:physics:physics.adoc[Physics].

|===
[cols="25,75", options="header"]
|===

a|Application methods
a|Purpose

a|setPauseOnLostFocus(true)
a|Set this boolean whether the game loop should stop running when ever the window loses focus (typical for single-player game). Set this to false for real-time and multi-player games that keep running.

a|start()
a|Call this method to start a jME3 game. By default this opens a new jME3 window, initializes the scene, and starts the event loop.

a|restart()
a|Loads modified xref:system/appsettings.adoc[AppSettings] into the current application context.

a|stop()
a|Stops the running jME3 game and closes the jME3 window.

a|start(Type.Headless) etc
a|Switch Context com.​jme3.​system.​JmeContext.Type when starting the application: +
Type.Display – jME application runs in a window of its own. (This is the default.) +
Type.Canvas – jME application is embedded in a xref:tutorials:how-to/java/swing_canvas.adoc[Swing Canvas]. +
Type.Headless – jME application runs its event loop without calculating any view and without opening any window. Can be used for a xref:networking:headless_server.adoc[Headless Server] application. +
Type.OffscreenSurface – jME application view is not shown and no window opens, but everything calculated and cached as bitmap (back buffer) for use by other applications.

|===
[cols="25,75", options="header"]
|===

a|Internal class field/method
a|Purpose

a|context +
getContext()
a|The application context contains the renderer, xref:system/appsettings.adoc[AppSettings], timer, etc. Typically, you do not directly access the context object.

a|inputEnabled
a|this internal boolean is true if you want the system to listen for user inputs, and false if you just want to play a non-interactive scene. You change the boolean using xref:system/appsettings.adoc[AppSettings].

a|keyInput, mouseInput +
joyInput, touchInput
a|Default input contexts for keyboard, mouse, and joystick. Internally used to enable handling of joysticks or touch devices. The base classes contain key and mouse button enums.

a|renderManager +
getRenderManager() +
renderer +
getRenderer();
a|Low-level and high-level rendering interface. Mostly used internally.

a|guiViewPort +
getGuiViewPort()
a|The view object for the orthogonal +++<abbr title="Graphical User Interface">GUI</abbr>+++ view. Only used internally for xref:ui/hud.adoc[HUD]s.

a|timer
a|An internal update loop timer, don't use. See `tpf` in `simpleUpdate()` below to learn about timers.

a|paused
a|Boolean is used only internally during runtime to pause/unpause a game. (You need to implement your own isRunning boolean or so.)

|===


== SimpleApplication Class

The com.jme3.app.SimpleApplication class extends the generic com.jme3.app.Application class. SimpleApplication makes it easy to start writing a game because it adds typical functionality:

*  First-person (fly-by) camera
*  Scene graph that manages your models in the rendered 3D scene.
*  Useful default input mappings (details below.)

Additional to the functionality that Application brings, SimpleApplication offers the following methods and fields that can be used, for example, inside the `simpleInitApp()` method:
[cols="25,75", options="header"]
|===

a|SimpleApplication Class Field
a|Purpose

a|rootNode +
getRootNode()
a|The root node of the scene graph. Attach a xref:scene/spatial.adoc[Spatial] to the rootNode and it appears in the 3D scene.

a|guiNode +
getGuiNode()
a|Attach flat +++<abbr title="Graphical User Interface">GUI</abbr>+++ elements (such as xref:ui/hud.adoc[HUD] images and text) to this orthogonal +++<abbr title="Graphical User Interface">GUI</abbr>+++ node to make them appear on the screen.

a|flyCam +
getFlyByCamera()
a|The default first-person fly-by camera control. This default camera control lets you navigate the 3D scene using the preconfigured WASD and arrow keys and the mouse.

|===
[cols="25,75", options="header"]
|===

a|SimpleApplication Method
a|Purpose

a|loadStatsView();
a|Call this method to print live statistic information to the screen, such as current frames-per-second and triangles/vertices counts. You use this info typically only during development or debugging.

a|loadFPSText();
a|Call this method to print the current framerate (frames per second) to the screen.

a|setDisplayFps(false);
a|A default SimpleApplication displays the framerate (frames per second) on the screen. You can choose to deactivate the FPS display using this command.

a|setDisplayStatView(false);
a|A default SimpleApplication displays mesh statistics on the screen using the com.jme3.app.StatsView class. The information is valuable during the development and debugging phase, but for the release, you should hide the statistics HUD. +
*pass:[*]Note:* There is a dark quad behind the stats. Each letter displayed in the stats is a quad. Each quad has 4 vertexes and 2 triangles. +

456/2 = 228 +
912/4 = 228

This means if you display stats, there will be 456 triangles and 912 vertices showing in the stats view in addition to anything you add yourself.

|===
[cols="40,60", options="header"]
|===

a|SimpleApplication Interface
a|Purpose

a|public void simpleInitApp()
a|Override this method to initialize the game scene. Here you load and create objects, attach Spatials to the rootNode, and bring everything in its starts position. See also xref:app/state/application_states.adoc[Application States] for best practices.

a|public void simpleUpdate(float tpf)
a|Override this method to hook into the xref:app/update_loop.adoc[update loop], all code you put here is repeated in a loop. Use this loop to poll the current game state and respond to changes, or to let the game mechanics generate encounters and initiate state changes. Use the float `tpf` as a factor to time actions relative to the _time per frame_ in seconds: `tpf` is large on slow PCs, and small on fast PCs. +
For more info on how to hook into the update loop, see xref:app/state/application_states.adoc[Application States] and xref:scene/control/custom_controls.adoc[Custom Controls].

a|public void simpleRender(RenderManager rm)
a|*Optional:* Advanced developers can override this method if the need to modify the frameBuffer and scene graph directly.

|===


[TIP]
====
Use `app.setShowSettings(true);` to present the user with a splashscreen and the built-in display settings dialog when starting the game; or use `app.setShowSettings(false);` to hide the built-in screen (in this case, you may want to provide a custom splashscreen and settings panel). Set this boolean before calling `app.start()` in the `main()` method of the SimpleApplication. See also xref:system/appsettings.adoc[AppSettings].
====



== Default Input Mappings

The following default navigational input actions are mapped by the default `flyCam` control in a SimpleApplication: You can use these mappings for debugging and testing until you implement custom xref:input/input_handling.adoc[input handling].
[cols="2", options="header"]
|===

a|Key
a|Action

a|KEY_ESCAPE
a|Quits the game by calling `app.stop()`

a|KEY_C
a|Debug key: Prints camera position, rotation, and direction to the out stream.

a|KEY_M
a|Debug key: Prints memory usage stats the out stream.

a|F5
a|Hides or shows the statistics the bottom left.

|===

As long as the `flyCam` is enabled, the following so-called "`WASD`" inputs, including MouseLook, are available:
[cols="2", options="header"]
|===

a|Camera Motion
a|Key or Mouse Input

a|Move Forward
a|KEY_W

a|Move Left (Strafe)
a|KEY_A

a|Move Backward
a|KEY_S

a|Move Right (Strafe)
a|KEY_D

a|Move Vertical Upward
a|KEY_Q

a|Move Vertical Downward
a|KEY_Z

a|Rotate Left
a|KEY_LEFT, or move mouse horizontally left (-x)

a|Rotate Right
a|KEY_RIGHT, or move mouse horizontally right (+x)

a|Rotate Up
a|KEY_UP, or move mouse vertically forward (+y)

a|Rotate Down
a|KEY_DOWN, or move mouse vertically backward (-y)

a|Rotate
a|BUTTON_LEFT, or hold left mouse button and drag to rotate

a|Zoom In
a|AXIS_WHEEL, or scroll mouse wheel backward

a|Zoom Out
a|AXIS_WHEEL, or scroll mouse wheel forward

|===


== Defaults and Customization

By default, a SimpleApplication displays Statistics (`new StatsAppState()`), has debug output keys configured (`new DebugKeysAppState()`), and enables the flyCam (`new FlyCamAppState()`). You can customize which you want to reuse in your SimpleApplication.

The following example shows how you can remove one of the default AppStates, in this case, the FlyCamAppState:

*  Either, in your application's constructor, you create the SimpleApplication with only the AppStates you want to keep:
[source,java]
----
public MyApplication() {
  super( new StatsAppState(), new DebugKeysAppState() );
}
----

*  Or, in the `simpleInitApp()` method, you remove the ones you do not want to keep:
[source,java]
----
  public void simpleInitApp() {
    stateManager.detach( stateManager.getState(FlyCamAppState.class));
    ...
----