com.jmex.game
Class StandardGame

java.lang.Object
  extended by com.jme.app.AbstractGame
      extended by com.jmex.game.StandardGame
All Implemented Interfaces:
java.lang.Runnable

public final class StandardGame
extends AbstractGame
implements java.lang.Runnable

A game that implements all of the basic functionality that you will need.

This is intended to be the next logical step up from SimpleGame and can be utilised in production games.

StandardGame provides the following features to ease game development:

as well as re-initialisation of the graphical context (if settings change for example) and everything else a typical game requires.

However, even with all of the extras that StandardGame provides it does not force anything extra on you as the non-necessary items should be put into your GameStates and managed there. This process helps to organise the different aspects of your game and get the game process started ASAP to kill the long-standing problem of start-up lag.

Version:
$Revision: 4133 $, $Date: 2009-03-19 20:40:11 +0000 (Thu, 19 Mar 2009) $
Author:
Matthew D. Hicks

Nested Class Summary
static class StandardGame.GameType
           
 
Nested classes/interfaces inherited from class com.jme.app.AbstractGame
AbstractGame.ConfigShowMode
 
Field Summary
static int DISPLAY_CANVAS
           
static int DISPLAY_MODE
           
static int DISPLAY_WINDOW
           
static boolean THREAD_FRIENDLY
           
 
Fields inherited from class com.jme.app.AbstractGame
display, finished, settings
 
Constructor Summary
StandardGame(java.lang.String gameName)
           
StandardGame(java.lang.String gameName, StandardGame.GameType type)
           
StandardGame(java.lang.String gameName, StandardGame.GameType type, GameSettings settings)
           
StandardGame(java.lang.String gameName, StandardGame.GameType type, GameSettings settings, java.lang.Thread.UncaughtExceptionHandler exceptionHandler)
           
 
Method Summary
protected  void cleanup()
          Called once the game loop has finished.
 void delayForUpdate()
          Causes the current thread to wait for an update to occur in the OpenGL thread.
<T> T
executeInGL(java.util.concurrent.Callable<T> callable)
          Convenience method that will make sure callable is executed in the OpenGL thread.
 Camera getCamera()
          The internally used Camera for this instance of StandardGame.
 java.awt.Canvas getCanvas()
          The java.awt.Canvas if DISPLAY_CANVAS is the DISPLAY_MODE
 DisplaySystem getDisplay()
          The internally used DisplaySystem for this instance of StandardGame
 StandardGame.GameType getGameType()
           
protected  GameSettings getNewSettings()
          Subclasses must implement getNewSettings to instantiate and populate a GameSettings object.
 GameSettings getSettings()
          The GameSettings implementation being utilized in this instance of StandardGame.
 boolean inGLThread()
          Convenience method to let you know if the thread you're in is the OpenGL thread
protected  void initGame()
          Create and initialise all game data.
protected  void initSound()
           
protected  void initSystem()
          Initialise the display system.
 boolean isStarted()
          Will return true if within the main game loop.
 void lock()
          Will wait for a lock at the beginning of the OpenGL update method.
protected  void quit()
          quit exits the program.
 void recreateGraphicalContext()
           
 void reinit()
          Rebuild the system.
 void reinitAudio()
           
 void reinitVideo()
           
protected  void render(float interpolation)
          Display the updated game information.
 void resetCamera()
           
 void run()
           
 void setBackgroundColor(ColorRGBA backgroundColor)
          Override the background color defined for this game.
 void setIcons(Image[] icons)
           
 void setUncaughtExceptionHandler(java.lang.Thread.UncaughtExceptionHandler exceptionHandler)
          Specify the UncaughtExceptionHandler for circumstances where an exception in the OpenGL thread is not captured properly.
 void shutdown()
          Gracefully shutdown the main game loop thread.
 void start()
          start begins the game.
 void unlock()
          Used in conjunction with lock() in order to release a previously assigned lock on the OpenGL thread.
protected  void update(float interpolation)
          Update the game state.
 
Methods inherited from class com.jme.app.AbstractGame
assertDisplayCreated, finish, getAttributes, getVersion, setConfigShowMode, setConfigShowMode
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DISPLAY_WINDOW

public static final int DISPLAY_WINDOW
See Also:
Constant Field Values

DISPLAY_CANVAS

public static final int DISPLAY_CANVAS
See Also:
Constant Field Values

THREAD_FRIENDLY

public static boolean THREAD_FRIENDLY

DISPLAY_MODE

public static int DISPLAY_MODE
Constructor Detail

StandardGame

public StandardGame(java.lang.String gameName)

StandardGame

public StandardGame(java.lang.String gameName,
                    StandardGame.GameType type)

StandardGame

public StandardGame(java.lang.String gameName,
                    StandardGame.GameType type,
                    GameSettings settings)

StandardGame

public StandardGame(java.lang.String gameName,
                    StandardGame.GameType type,
                    GameSettings settings,
                    java.lang.Thread.UncaughtExceptionHandler exceptionHandler)
Method Detail

getNewSettings

protected GameSettings getNewSettings()
Description copied from class: AbstractGame
Subclasses must implement getNewSettings to instantiate and populate a GameSettings object. The default getAttributest method in AbstractGame calls this to get an initial GameSettings, which is conditionally updated interactively.

Specified by:
getNewSettings in class AbstractGame
See Also:
AbstractGame.getNewSettings()

getGameType

public StandardGame.GameType getGameType()

start

public void start()
Description copied from class: AbstractGame
start begins the game. The game is initialized by calling first initSystem then initGame. Assuming no errors were encountered during initialization, the main game loop is entered. How the loop operates is implementation-dependent. After the game loop is broken out of via a call to finish, cleanup is called. Subclasses should declare this method final.

Specified by:
start in class AbstractGame

run

public void run()
Specified by:
run in interface java.lang.Runnable

initSystem

protected void initSystem()
Description copied from class: AbstractGame
Initialise the display system.

This includes not just the DisplaySystem but also any other input and display related elements such as windows, cameras, and the input system.

Note that the display must be initialised in this method.

Specified by:
initSystem in class AbstractGame

getCanvas

public java.awt.Canvas getCanvas()
The java.awt.Canvas if DISPLAY_CANVAS is the DISPLAY_MODE

Returns:
Canvas

initSound

protected void initSound()

resetCamera

public void resetCamera()

initGame

protected void initGame()
Description copied from class: AbstractGame
Create and initialise all game data.

What happens here is purely application dependent; it is where, for example, the initial scene graph and the starting environment could be loaded. It is suggested that any frequently used resources are loaded and cached in this method.

This method is called once after AbstractGame.initSystem() has completed.

Specified by:
initGame in class AbstractGame

update

protected void update(float interpolation)
Description copied from class: AbstractGame
Update the game state.

Any user input checks, changes to game physics, AI, networking, score table updates, and so on, should happen in this method. The rate at which this method is called will depend on the specific game implementation in use.

Note that this method should not update the screen.

Specified by:
update in class AbstractGame
Parameters:
interpolation - definition varies on implementation, -1.0f if unused
See Also:
AbstractGame.render(float)

render

protected void render(float interpolation)
Description copied from class: AbstractGame
Display the updated game information.

This method normally involves clearing the display and rendering the scene graph, although subclasses are free to do any screen related work here. The rate at which this method is called will depend on the specific game implementation in use.

Note that this method is run on the OpenGL thread, it should not alter the game state in any way.

Specified by:
render in class AbstractGame
Parameters:
interpolation - definition varies on implementation, -1.0f if unused
See Also:
AbstractGame.update(float)

reinit

public void reinit()
Description copied from class: AbstractGame
Rebuild the system.

This method is called when the system requires rebuilding, for example is the screen resolution is altered. This method may be called at any time by client code.

Specified by:
reinit in class AbstractGame

reinitAudio

public void reinitAudio()

reinitVideo

public void reinitVideo()

recreateGraphicalContext

public void recreateGraphicalContext()

cleanup

protected void cleanup()
Description copied from class: AbstractGame
Called once the game loop has finished.

Subclasses should use this method to release any resources, for example data that was loaded in the initXXX() methods.

Specified by:
cleanup in class AbstractGame

quit

protected void quit()
Description copied from class: AbstractGame
quit exits the program. By default, it simply uses the System.exit() method.

Specified by:
quit in class AbstractGame

getDisplay

public DisplaySystem getDisplay()
The internally used DisplaySystem for this instance of StandardGame

Returns:
DisplaySystem
See Also:
DisplaySystem

getCamera

public Camera getCamera()
The internally used Camera for this instance of StandardGame.

Returns:
Camera
See Also:
Camera

getSettings

public GameSettings getSettings()
The GameSettings implementation being utilized in this instance of StandardGame.

Returns:
GameSettings
See Also:
GameSettings

setBackgroundColor

public void setBackgroundColor(ColorRGBA backgroundColor)
Override the background color defined for this game. The reinit() method must be invoked if the game is currently running before this will take effect.

Parameters:
backgroundColor -

shutdown

public void shutdown()
Gracefully shutdown the main game loop thread. This is a synonym for the finish() method but just sounds better.

See Also:
AbstractGame.finish()

isStarted

public boolean isStarted()
Will return true if within the main game loop. This is particularly useful to determine if the game has finished the initialization but will also return false if the game has been terminated.

Returns:
boolean

setUncaughtExceptionHandler

public void setUncaughtExceptionHandler(java.lang.Thread.UncaughtExceptionHandler exceptionHandler)
Specify the UncaughtExceptionHandler for circumstances where an exception in the OpenGL thread is not captured properly.

Parameters:
exceptionHandler -

delayForUpdate

public void delayForUpdate()
                    throws java.lang.InterruptedException,
                           java.util.concurrent.ExecutionException
Causes the current thread to wait for an update to occur in the OpenGL thread. This can be beneficial if there is work that has to be done in the OpenGL thread that needs to be completed before continuing in another thread. You can chain invocations of this together in order to wait for multiple updates.

Throws:
java.lang.InterruptedException
java.util.concurrent.ExecutionException

inGLThread

public boolean inGLThread()
Convenience method to let you know if the thread you're in is the OpenGL thread

Returns:
true if, and only if, the current thread is the OpenGL thread

executeInGL

public <T> T executeInGL(java.util.concurrent.Callable<T> callable)
              throws java.lang.Exception
Convenience method that will make sure callable is executed in the OpenGL thread. If it is already in the OpenGL thread when this method is invoked it will be executed and returned immediately. Otherwise, it will be put into the GameTaskQueue and executed in the next update. This is a blocking method and will wait for the successful return of callable before returning.

Type Parameters:
T -
Parameters:
callable -
Returns:
result of callable.get()
Throws:
java.lang.Exception

lock

public void lock()
Will wait for a lock at the beginning of the OpenGL update method. Once this method returns the OpenGL thread is blocked until the lock is released (via unlock()). If another thread currently has a lock or it is currently in the process of an update the calling thread will be blocked until the lock is successfully established.


unlock

public void unlock()
Used in conjunction with lock() in order to release a previously assigned lock on the OpenGL thread. This MUST be executed within the same thread that called lock() in the first place or the lock will not be released.


setIcons

public void setIcons(Image[] icons)