Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## superwaba.ext.xplat.game
Class GameEngine

    java.lang.Object
      |
      +--waba.ui.Control
            |
            +--waba.ui.Container
                  |
                  +--waba.ui.Window
                        |
                        +--waba.ui.MainWindow
                              |
                              +--superwaba.ext.xplat.game.GameEngineMainWindow
                                    |
                                    +--superwaba.ext.xplat.game.GameEngine

public abstract class GameEngine
extends superwaba.ext.xplat.game.GameEngineMainWindow

This abstract class represents the game API engine.

     Version 1.1 of the GameEngine features:

     Highscores management.
     Versionned options management of String, Integer, Float and Boolean types.
     Quick text display through text pre-rendering for game status & score display.
     Sprite/animated sprite support.
     Animation control.
     AnimatedButton control.
     Game framework extending the Superwaba MainWindow.

     You can find a complete game API sample named 'Ping' in the SW examples folder.

     NOTE: This sample may be used as a skeleton for your own game development and the
     source reading may be much helpful to understand this framework.
     You also can change the game settings at the top of the file 'Ping.java' to
     experiment the different game API behaviours.

     Further i recommand the reading of the Superwaba game API tutorial that gives
     many details on this framework use.

     1) GAME FRAMEWORK DESCRIPTION

     Basically the game engine consists in a class that extends Superwaba's MainWindow.
     This class is named GameEngine and provides
     many game oriented services like game settings and game highscores management.
     You won't have to access the game associated settings nor the highscore databases
     directly, you will have to use HighScores
     and Options interfaces instead.
     This services are retrievable by the getHisghscores() and the getOptions() calls.

     2) GAME SETUP

     A game using this API has to extend the GameEngine class,
     like this:

     public class MyOwnGame extends GameEngine {
     ...
     }

     to setup the game engine, you will have to provide some information.
     These information are defined through the following GameEngine member variables:

       gameName             = "Ping";

       // when not run on device, appCreatorId does not always return the same value.

       gameCreatorID        = Settings.onDevice ? waba.sys.Settings.appCreatorId:"PiNg";

       gameVersion          = 100;   // v1.00
       gameHighscoresSize   = 7;     // store the best 7 highscores
       gameRefreshPeriod    = 75;    // 75 ms refresh periods
       gameIsDoubleBuffered = true;  // used double buffering to prevent flashing display
       gameDoClearScreen    = true;  // screen is cleared before each frame display
       gameHasUI            = false; // no UI elements, frame displays are optimized

     -gameName             the name of the game, this information is used to name the game associated databases.
     -gameCreatorID        the creatorID of the game
     -gameVersion          the game version number
     -gameHighscoresSize   number of best scores to save in the highscores database
     -gameRefreshPeriod    refresh period in milliseconds for action games, or NO_AUTO_REFRESH for non animated games.
     -gameIsDoubleBuffered enable/disable Superwaba's double-buffering
       (the image is first build in memory and then copied quickly to the screen,
       this prevents "object flickering" when the drawings are to slow)
     -gameDoClearScreen    enable/disable the whole screen erasing between frames displays.
     -gameHasUI            declare UI uses, if false the drawing is improved

     You see below the definition of a the sample game named "Ping":

     import superwaba.ext.xplat.game.*;
     import superwaba.ext.xplat.util.props.*;
     ...

     public class Ping extends GameEngine {

     // constructor
     public Ping()
     {
       waba.sys.Settings.setPalmOSStyle(true);

       // define the game API setup attributes

       gameName             = "Ping";

       // when not run on device, appCreatorId does not always return the same value.

       gameCreatorID        = Settings.onDevice ? waba.sys.Settings.appCreatorId:"PiNg";

       gameVersion          = 100;   // v1.00
       gameHighscoresSize   = 7;     // store the best 7 highscores
       gameRefreshPeriod    = 75;    // 75 ms refresh periods
       gameIsDoubleBuffered = true;  // used double buffering to prevent flashing display
       gameDoClearScreen    = true;  // screen is cleared before each frame display
       gameHasUI            = false; // no UI elements, frame displays are optimized
       ...
     }

     3) GAME FRAMEWORK DETAILS

     The GameEngine class traps many Superwaba event handler functions to fulfill tasks
     behind the scenes. Thus the following Superwaba functions cannot be overloaded in your
     game's main window:

     void onStart  ();
     void onExit   ();
     void onEvent  (Event ev);

     they are replaced by the following game API functions that may be overloaded :

     void onGameInit   ();
     void onGameExit   ();

     void onKey        (KeyEvent evt);
     void onPenDown    (PenEvent evt);
     void onPenUp      (PenEvent evt);
     void onPenDrag    (PenEvent evt);

     void onTimer      (ControlEvent evt);
     void onOtherEvent (Event evt);

     The framework extends the event handlers to provide game specific events, such as:

     void onGameStart  ();
     void onGameStop   ();

     The first one is called when the game mainloop starts (when the game enters the
     "run mode"), the second one when the run mode is leaved.

     You can control (run/stop) and retrieve the current state by the game API functions and fields:

     void    start     ();
     void    stop      ();
     boolean gameIsRunning;

     The game API supports both arcade games that are "time driven" (a timer causes
     frequent screen refreshes to get an animation of the game elements/objects)
     and "static" games such as cards, puzzles, etc.

     When entering the game run mode by the start() call, time based games
     arm a timer that causes scheduled calls to your overloaded onPaint()
     to draw a new frame/image.

     On static games that may be designated as "user event driven" refreshes have to
     be launched by an explicit call of refresh() that also causes the call
     of your overloaded onPaint() to draw a new frame/image. Static games
     can also use timers to signal the end of a reflection time, etc.

     4) GAME SPRITES

     A Sprite is a graphical object typicaly used in games that can be moved,
     with collision detection feature and background saving/restoring capability.

     To create a sprite you will have to provide an Image object, it's transparency color
     if needed (DRAW_SPRITE mode), a flag indicating if the background have to be saved
     (required if screen clearing is disabled as far as the screen is not
     erased to be redrawn completly) and the sprite valid positions area (Rect).

     You may also have to define the drawOp for the Sprite drawing. It's common values are:
     USE_CURRENT_DRAWOP default
     DRAW_SPRITE
     DRAW_PAINT

     You can override the onPositionChange() method to manage valid positions, collisions,
     bounces or any other object position based condition.

     The default implementation checks position validity by using the region argument
     of the sprite constructor.
     see the "Ping" source code for more details.

     When background saving is enabled, each sprite display with the show() method
     restores any previously saved background.

     In some games, sprites may overlap... if you write such a game, you may have to
     call the sprite hide() method explicitly (which is not necessary in the common
     usage) in the reverse draw order to restore the background.

     5) ANIMATIONS

     This Animation control provides an image sequence display. You can handle the
     animation frames displays by your own, or call one of the several start()
     methods provided to launch a thread driven animation.

     The animation is composed by a collection of Image objects that can be loaded
     from indexed BMP files (one frame per image) or from a so-called multi-image
     bitmap. It is an image format that contains all the animation frames side by side.
     All the images share a same color palette and must have the same size.

     You may use the Gif2Bmps tool in \superwaba\apps\xplat\Gif2Bmps folder to
     convert animated gif images into the convenient format.

     6) ANIMATED BUTTONS

     The AnimatedButton class is a button implementation that extends the
     Animation class. It uses an animation containing the different states of the
     button and their transition frames in a specific layout.

9) INFORMATION
For any information, proposal or request about this Superwaba extension game API.
You can send an email to Frank Diebolt
-or-
post a message in the newsgroup: pilot.programmer.waba

Field Summary
`static int` | `GAME_ENGINE_VERSION`
`String` | `gameCreatorID` Game CreatorID.
`boolean` | `gameDoClearScreen` True if the screen should be cleared before the onPaint() call.
`protected boolean` | `gameHasUI` Must be set to true if the game screen has any control from the waba.ui package.
`int` | `gameHighscoresSize` Amount of highscores entries in the highscores database.
`boolean` | `gameIsDoubleBuffered` True if the game uses SuperWaba's double buffering feature.
`protected boolean` | `gameIsRunning` True if the game is running.
`String` | `gameName` Name of the game.
`int` | `gameRefreshPeriod` Automatic refresh period in milliseconds.
`int` | `gameVersion` Game version.
`static int` | `NO_AUTO_REFRESH` No automatic refresh.

Fields inherited from class waba.ui.MainWindow
`defaultFont`

Fields inherited from class waba.ui.Window
`beepIfOut, borderStyle, canDrag, eraseBackgroundNow, flicker, HIDE_STATE, highResPrepared, imgCovered, lastSwappedContainer, mainSwapContainer, menubar, needsPaint, NO_BORDER, RECT_BORDER, ROUND_BORDER, TAB_BORDER, TAB_ONLY_BORDER, title, titleFont, topMost, VK_BOTTOM, VK_HIDE, VK_TOP, zStack`

Fields inherited from class waba.ui.Container
`BORDER_LOWERED, BORDER_NONE, BORDER_RAISED, BORDER_SIMPLE, children, lastH, lastW, lastX, lastY, parentWindow, tail`

Fields inherited from class waba.ui.Control
`AFTER, appId, asContainer, asWindow, backColor, backDis, BEFORE, BOTTOM, CENTER, enabled, FILL, FIT, fm, fmH, focusLess, font, foreColor, foreDis, height, LEFT, parent, PREFERRED, RANGE, RIGHT, SAME, TOP, visible, width, x, x2, y, y2`

Constructor Summary
`GameEngine()` Creates a new GameEngine

Method Summary
`TextRenderer` | `createTextRenderer(Font font, Color foreColor, String text, int maxDigits)` Create a new TextRenderer.
`HighScores` | `getHighScores()` Get the game highscores.
`Options` | `getOptions()` Get a new instance of the game options.
`void` | `onGameExit()` Event notication called when the game exits.
`abstract void` | `onGameInit()` Event notication called when the game is initialized.
`void` | `onGameStart()` Event notication called when the game mainloop is entered.
`void` | `onGameStop()` Event notication called when the game mainloop is leaved.
`void` | `onKey(KeyEvent evt)` Event notication called when a key event is signaled.
`void` | `onOtherEvent(Event evt)` Event notication called when any other event is signaled.
`void` | `onPaint(Graphics g)` Called at each refresh to draw the current game state
`void` | `onPenDown(PenEvent evt)` Event notication called when an pen down event is signaled.
`void` | `onPenDrag(PenEvent evt)` Event notication called when an pen drag/move event is signaled.
`void` | `onPenUp(PenEvent evt)` Event notication called when an pen up event is signaled.
`void` | `onTimer(ControlEvent evt)` Event notication called when a control event is signaled.
`void` | `refresh()` This function causes an onPaint() call to draw a new frame. This function has to be called in non time based games to refresh the complete screen.
`void` | `start()` Must be called to start the game.
`void` | `stop()` Must be called to make the game stop.

Methods inherited from class superwaba.ext.xplat.game.GameEngineMainWindow
`onEvent, onExit, onStart, setGameEngine`

Methods inherited from class waba.ui.MainWindow
`_onTimerTick, _runThreads, addThread, addTimer, appEnding, appStarting, exit, getCommandLine, getFontMetrics, getMainWindow, killThreads, removeThread, removeTimer`

Methods inherited from class waba.ui.Window
`_doPaint, _doPaint, _postEvent, damageRect, destroyZStack, dontSaveBehind, getClientRect, getFocus, getOffScreen, getPreferredHeight, getPreferredWidth, getTopMost, isTopMost, isVisible, loadBehind, makeUnmovable, onClickedOutside, onPopup, onUnpop, paintTitle, popupBlockingModal, popupMenuBar, popupModal, postPopup, postUnpop, pumpEvents, saveBehind, setBorderStyle, setDoubleBuffer, setFocus, setMenuBar, setStatePosition, setTitle, setTitleFont, swap, unpop`

Methods inherited from class waba.ui.Container
`add, add, add, broadcastEvent, findChild, getChildren, onColorsChanged, paintChildren, remove, setEnabled`

Methods inherited from class waba.ui.Control
`addTimer, contains, createGraphics, getAbsoluteRect, getBackColor, getFont, getForeColor, getNext, getParent, getParentWindow, getPos, getRect, getSize, isDisplayed, isEnabled, onBoundsChanged, onFontChanged, onWindowPaintFinished, postEvent, repaint, repaintNow, requestFocus, setBackColor, setBackForeColors, setFocusLess, setFont, setForeColor, setRect, setRect, setRect, setVisible`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, toString, wait, wait`

Field Detail

### GAME_ENGINE_VERSION

    public static final int GAME_ENGINE_VERSION

### gameName

    public String gameName

  Name of the game.
  The Highscores/Options databases are prefixed with this name.

### gameCreatorID

    public String gameCreatorID

  Game CreatorID.
  The Highscores/Options databases references are created with this ID.
  This must be a String with exactly four characters. This has the effect to link the databases to the game software causing an automatic database removal when the application is deleted from the device.

### gameVersion

    public int gameVersion

  Game version.
  This information is written in the Options database and may be compared to it's old version retrievable by the getOldVersion() function of the Options interface. E.g. 100 for 1.00)

### gameHighscoresSize

    public int gameHighscoresSize

  Amount of highscores entries in the highscores database.

### NO_AUTO_REFRESH

    public static final int NO_AUTO_REFRESH

  No automatic refresh.
  See Also:
    `gameRefreshPeriod`

### gameRefreshPeriod

    public int gameRefreshPeriod

  Automatic refresh period in milliseconds.
  The NO_AUTO_REFRESH value prevents the engine to do time based refreshes. You will have to call explicitly the refresh() function to force a screen repainting.
  See Also:
    `refresh`

### gameIsDoubleBuffered

    public boolean gameIsDoubleBuffered

  True if the game uses SuperWaba's double buffering feature.

### gameDoClearScreen

    public boolean gameDoClearScreen

  True if the screen should be cleared before the onPaint() call.

### gameIsRunning

    protected boolean gameIsRunning

  True if the game is running. Set by the GameEngineMainWindow. To stop or start the game use the methods stop or run. Setting this variable has no effect.

### gameHasUI

    protected boolean gameHasUI

  Must be set to true if the game screen has any control from the waba.ui package. Complex games should not have UI elements

Constructor Detail

### GameEngine

    public GameEngine()

  Creates a new GameEngine

Method Detail

### onGameInit

    public abstract void onGameInit()

  Event notication called when the game is initialized.
  It's the first place where API calls can take place because the game engine has been initialized.
  You can do game initialization at this place. Typically Sprites may be created in the overloaded function.

### onGameExit

    public void onGameExit()

  Event notication called when the game exits.

### onGameStart

    public void onGameStart()

  Event notication called when the game mainloop is entered.
  See Also:
    `#run`

### onGameStop

    public void onGameStop()

  Event notication called when the game mainloop is leaved.
  See Also:
    `stop()`

### onTimer

    public void onTimer(ControlEvent evt)

  Event notication called when a control event is signaled.
  Parameters:
    `evt` - control event that occurred.

### onKey

    public void onKey(KeyEvent evt)

  Event notication called when a key event is signaled.
  Parameters:
    `evt` - key event that occurred.

### onPenDown

    public void onPenDown(PenEvent evt)

  Event notication called when an pen down event is signaled.
  Parameters:
    `evt` - pen event that occurred.

### onPenUp

    public void onPenUp(PenEvent evt)

  Event notication called when an pen up event is signaled.
  Parameters:
    `evt` - pen event that occurred.

### onPenDrag

    public void onPenDrag(PenEvent evt)

  Event notication called when an pen drag/move event is signaled.
  Parameters:
    `evt` - pen event that occurred.

### onOtherEvent

    public void onOtherEvent(Event evt)

  Event notication called when any other event is signaled.
  Parameters:
    `evt` - event that occurred.

### onPaint

    public void onPaint(Graphics g)

  Called at each refresh to draw the current game state
  Overrides:
    onPaint in class Container
  Tags copied from class: Control
  Parameters:
    `g` - the graphics object for drawing
  See Also:
    `Graphics`

### getHighScores

    public HighScores getHighScores()

  Get the game highscores.
  Returns:
    HighScores.

### getOptions

    public Options getOptions()

  Get a new instance of the game options.
  Returns:
    Options.

### createTextRenderer

    public final TextRenderer createTextRenderer(Font font,
                                                 Color foreColor,
                                                 String text,
                                                 int maxDigits)

  Create a new TextRenderer. A TextRenderer performs a fast String display with an optional integer value.
  Parameters:
    `font` - to display with.
    `foreColor` - text color, may be null.
    `text` - to render.
    `maxDigits` - digits to display (with leading zeros).
  Returns:
    a new TextRenderer.
  See Also:
    `TextRenderer for more information`

### start

    public final void start()

  Must be called to start the game.

### stop

    public final void stop()

  Must be called to make the game stop.

### refresh

    public final void refresh()

  This function causes an onPaint() call to draw a new frame.
  This function has to be called in non time based games to refresh the complete screen.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD