| title |
|---|
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.
The following code sample shows the typical base structure of a jME3 game:
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 API of the base 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.
| Application class fields | Purpose |
|---|---|
| viewPort getViewPort() | The view object for the default camera. You can register advanced post-processor filters here. |
| settings setSettings() | Use this AppSettings object to specify the display width and height (by default 640×480), color bit depth, z-buffer bits, anti-aliasing samples, and update frequency, video and audio renderer, asset manager. See: AppSettings. |
| cam getCamera() | The default camera provides perspective projection, 45° field of view, near plane = 1 wu, far plane = 1000 wu. |
| assetManager getAssetManager() | An object that manages paths for loading models, textures, materials, sounds, etc. By default the Asset Manager paths are relative to your project's root directory. |
| audioRenderer getAudioRenderer() | This object gives you access to the jME3 audio system. |
| listener getListener() | This object represents the user's ear for the jME3 audio system. |
| inputManager getInputManager() | Use the inputManager to configure your custom inputs (mouse movement, clicks, key presses, etc) and set mouse pointer visibility. |
| stateManager getStateManager() | You use the Application's state manager to activate AppStates, such as Physics. |
| Application methods | Purpose |
|---|---|
| setPauseOnLostFocus(true) | 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. |
| start() | Call this method to start a jME3 game. By default this opens a new jME3 window, initializes the scene, and starts the event loop. |
| restart() | Loads modified AppSettings into the current application context. |
| stop() | Stops the running jME3 game and closes the jME3 window. |
| start(Type.Headless) etc | 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 Swing Canvas. Type.Headless – jME application runs its event loop without calculating any view and without opening any window. Can be used for a 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. |
| Internal class field/method | Purpose |
|---|---|
| context getContext() | The application context contains the renderer, AppSettings, timer, etc. Typically, you do not directly access the context object. |
| inputEnabled | 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 AppSettings. |
| keyInput, mouseInput joyInput, touchInput | 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. |
| renderManager getRenderManager() renderer getRenderer(); | Low-level and high-level rendering interface. Mostly used internally. |
| guiViewPort getGuiViewPort() | The view object for the orthogonal GUI view. Only used internally for HUDs. |
| timer | An internal update loop timer, don't use. See tpf in simpleUpdate() below to learn about timers. |
| paused | Boolean is used only internally during runtime to pause/unpause a game. (You need to implement your own isRunning boolean or so.) |
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:
| SimpleApplication Class Field | Purpose |
|---|---|
| rootNode getRootNode() | The root node of the scene graph. Attach a Spatial to the rootNode and it appears in the 3D scene. |
| guiNode getGuiNode() | Attach flat GUI elements (such as HUD images and text) to this orthogonal GUI node to make them appear on the screen. |
| flyCam getFlyByCamera() | 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. |
| SimpleApplication Method | Purpose |
|---|---|
| loadStatsView(); | 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. |
| loadFPSText(); | Call this method to print the current framerate (frames per second) to the screen. |
| setDisplayFps(false); | A default SimpleApplication displays the framerate (frames per second) on the screen. You can choose to deactivate the FPS display using this command. |
| setDisplayStatView(false); | 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. |
| SimpleApplication Interface | Purpose |
|---|---|
| public void simpleInitApp() | 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 Application States for best practices. |
| public void simpleUpdate(float tpf) | Override this method to hook into the 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 Application States and Custom Controls. |
| public void simpleRender(RenderManager rm) | Optional: Advanced developers can override this method if the need to modify the frameBuffer and scene graph directly. |
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 buil-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 AppSettings.
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 input handling.
| Key | Action |
|---|---|
| KEY_ESCAPE | Quits the game by calling app.stop() |
| KEY_C | Debug key: Prints camera position, rotation, and direction to the out stream. |
| KEY_M | Debug key: Prints memory usage stats the out stream. |
| F5 | 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:
| Camera Motion | Key or Mouse Input |
|---|---|
| Move Forward | KEY_W |
| Move Left (Strafe) | KEY_A |
| Move Backward | KEY_S |
| Move Right (Strafe) | KEY_D |
| Move Vertical Upward | KEY_Q |
| Move Vertical Downward | KEY_Z |
| Rotate Left | KEY_LEFT, or move mouse horizontally left (-x) |
| Rotate Right | KEY_RIGHT, or move mouse horizontally right (+x) |
| Rotate Up | KEY_UP, or move mouse vertically forward (+y) |
| Rotate Down | KEY_DOWN, or move mouse vertically backward (-y) |
| Rotate | BUTTON_LEFT, or hold left mouse button and drag to rotate |
| Zoom In | AXIS_WHEEL, or scroll mouse wheel backward |
| Zoom Out | AXIS_WHEEL, or scroll mouse wheel forward |
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 contructor, you create the SimpleApplication with only the AppStates you want to keep:
public MyAppliction() { super( new StatsAppState(), new DebugKeysAppState() ); }
- Or, in the
simpleInitApp()method, you remove the ones you do not want to keep:public void simpleInitApp() { stateManager.detach( stateManager.getState(FlyCamAppState.class)); ...