GTGE API

com.golden.gamedev
Class Game

java.lang.Object
  extended by com.golden.gamedev.Game
Direct Known Subclasses:
GameEngine, LibInfo

public abstract class Game
extends Object

Game class is Golden T Game Engine (GTGE) core class that initializes all GTGE game engines, wrap the engines up, and setup the basic game frame work to be play on.

Every game is a subclass of Game class. And every subclass of Game class have to do three things :

How-to-subclass Game class to create a new game :
(this is the basic skeleton of every game)

    import java.awt.*;
    import com.golden.gamedev.*;

    public class YourGame extends Game {

       public void initResources() {
          // initialize game variables
       }

       public void update(long elapsedTime) {
          // update the game variables
       }

       public void render(Graphics2D g) {
          // render the game to the screen
       }

    }
 

And to launch/init the game use GameLoader class :

    import java.awt.*;
    import com.golden.gamedev.*;

    public class YourGame extends Game {

       public void initResources() { }
       public void update(long elapsedTime) { }
       public void render(Graphics2D g) { }

       public static void main(String[] args) {
          GameLoader game = new GameLoader();

          // init the game with fullscreen mode, 640x480 screen resolution
          game.setup(new YourGame(), new Dimension(640,480), true);

          game.start();
       }

    }
 

There are two main tasks of Game class that we need to know :

See Also:
GameLoader, initEngine()

Field Summary
 BaseGraphics bsGraphics
          Graphics engine.
 BaseInput bsInput
          Input engine.
 BaseIO bsIO
          I/O file engine.
 BaseLoader bsLoader
          Image loader engine.
 BaseAudio bsMusic
          Audio engine for music.
 BaseAudio bsSound
          Audio engine for sound.
 BaseTimer bsTimer
          Timer engine.
protected  boolean distribute
          Indicates whether this game is finished and ready to distribute or still in development stage.
 GameFontManager fontManager
          Font manager.
static String GTGE_VERSION
          Current GTGE version.
 
Constructor Summary
Game()
          Creates new instance of Game class, please see note below.
 
Method Summary
 boolean checkPosMouse(int x1, int y1, int x2, int y2)
          Returns whether the mouse pointer is inside specified screen boundary.
 boolean checkPosMouse(Sprite sprite, boolean pixelCheck)
          Returns whether the mouse pointer is inside specified sprite boundary.
 boolean click()
          Effectively equivalent to the call bsInput.isMousePressed(java.awt.event.MouseEvent.BUTTON1).
 void drawFPS(Graphics2D g, int x, int y)
          Draws game frame-per-second (FPS) to specified location.
 void finish()
          End the game and back to operating system.
 int getCurrentFPS()
          Effectively equivalent to the call bsTimer.getCurrentFPS().
 int getFPS()
          Effectively equivalent to the call BaseTimer.getFPS().
 int getHeight()
          Effectively equivalent to the call bsGraphics.getSize().height.
 BufferedImage getImage(String imagefile)
          Effectively equivalent to the call bsLoader.getImage(String).
 BufferedImage getImage(String imagefile, boolean useMask)
          Effectively equivalent to the call bsLoader.getImage(String, boolean).
 BufferedImage[] getImages(String imagefile, int col, int row)
          Effectively equivalent to the call bsLoader.getImages(String, int, int).
 BufferedImage[] getImages(String imagefile, int col, int row, boolean useMask)
          Effectively equivalent to the call bsLoader.getImages(String, int, int, boolean).
 BufferedImage[] getImages(String imagefile, int col, int row, boolean useMask, int start, int end)
          Returns stripped images with cropped sequence.
 BufferedImage[] getImages(String imagefile, int col, int row, boolean useMask, String sequence, int digit)
          Returns stripped images with specified sequence.
 BufferedImage[] getImages(String imagefile, int col, int row, int start, int end)
          Same as getImages(imagefile, col, row, useMask, start, end) with mask color is turned on by default.
 BufferedImage[] getImages(String imagefile, int col, int row, String sequence, int digit)
          Same as getImages(imagefile, col, row, useMask, sequence, digit) with mask color is turned on by default.
 int getMouseX()
          Effectively equivalent to the call bsInput.getMouseX().
 int getMouseY()
          Effectively equivalent to the call bsInput.getMouseY().
 int getRandom(int low, int hi)
          Effectively equivalent to the call Utility.getRandom(int, int)
 int getWidth()
          Effectively equivalent to the call bsGraphics.getSize().width.
 void hideCursor()
          Effectively equivalent to the call bsInput.setMouseVisible(false).
protected  void initEngine()
          Game engines is initialized in this method.
abstract  void initResources()
          All game resources initialization, everything that usually goes to constructor should be put in here.
 boolean isDistribute()
          Returns whether this game is ready to distribute or still in development stage.
 boolean isFinish()
          Returns true, if the game has been finished playing and the game is about to return back to operating system.
 boolean isRunning()
          Returns whether the game is currently running/playing or not.
 boolean keyDown(int keyCode)
          Effectively equivalent to the call bsInput.isKeyDown(int).
 boolean keyPressed(int keyCode)
          Effectively equivalent to the call bsInput.isKeyPressed(int).
protected  void notifyError(Throwable error)
          Notified of any unexpected or uncatch error thrown by the game when the game is ready to distribute (distribute = true).
protected  void notifyExit()
          Notified when the game is about to quit.
 int playMusic(String audiofile)
          Effectively equivalent to the call bsMusic.play(String).
 int playSound(String audiofile)
          Effectively equivalent to the call bsSound.play(String).
abstract  void render(Graphics2D g)
          Renders game to the screen.
 boolean rightClick()
          Effectively equivalent to the call bsInput.isMousePressed(java.awt.event.MouseEvent.BUTTON3).
 void setFPS(int fps)
          Effectively equivalent to the call bsTimer.setFPS(int).
 void setMaskColor(Color c)
          Effectively equivalent to the call bsLoader.setMaskColor(java.awt.Color).
 void showCursor()
          Effectively equivalent to the call bsInput.setMouseVisible(true).
 void showLogo()
          Shows GTGE logo/splash screen, GTGE is freeware library, please support GTGE by showing this logo on your game, thank you.
 void start()
          Starts the game main loop, this method will not return until the game is finished playing/running.
 void stop()
          Stops the game from running, and to resume the game call start() method.
 BufferedImage takeScreenShot()
          Returns a new created buffered image which the current game state is rendered into it.
 void takeScreenShot(File f)
          Captures current game screen into specified file.
abstract  void update(long elapsedTime)
          Updates game variables.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

GTGE_VERSION

public static final String GTGE_VERSION
Current GTGE version.

See Also:
Constant Field Values

bsGraphics

public BaseGraphics bsGraphics
Graphics engine.


bsIO

public BaseIO bsIO
I/O file engine.


bsLoader

public BaseLoader bsLoader
Image loader engine.


bsInput

public BaseInput bsInput
Input engine.


bsTimer

public BaseTimer bsTimer
Timer engine.


bsMusic

public BaseAudio bsMusic
Audio engine for music.


bsSound

public BaseAudio bsSound
Audio engine for sound.


fontManager

public GameFontManager fontManager
Font manager.


distribute

protected boolean distribute
Indicates whether this game is finished and ready to distribute or still in development stage.

A distributed game (distribute = true) will catch any uncatch/unexpected game exception and send the error to notifyError(Throwable) method.

When your game is completed and it is time to distribute the game to the world, set this distribute value to true in class initialization :

    public class YourGame extends Game {

       // class initialization, put it here
       { distribute = true; }

       // do not put it in initResources() method or other place!
       public void initResources() { }
       public void update(long elapsedTime) { }
       public void render(Graphics2D g) { }

    }
 

See Also:
notifyError(Throwable)
Constructor Detail

Game

public Game()
Creates new instance of Game class, please see note below.

Note: Do not make any overloading constructors. All that belong to constructor (this method) should be put in initResources() method. Leave this method empty and simply do not use constructor!

See Also:
initResources(), update(long), render(Graphics2D)
Method Detail

stop

public void stop()
Stops the game from running, and to resume the game call start() method. This method is only holding the game, to quit the game call finish() instead. During the holding time, no action is taken, even the game rendering, therefore this method is not suitable for making game pause event.

By default this stop method is only called in applet environment whenever the applet stop method is executed by the webpage.

See Also:
start(), finish()

finish

public void finish()
End the game and back to operating system.

Only call this method when the game has been finished playing. Calling this method will immediatelly makes the game to quit and the game can not be resumed/played anymore.

See Also:
stop()

isFinish

public boolean isFinish()
Returns true, if the game has been finished playing and the game is about to return back to operating system.


isRunning

public boolean isRunning()
Returns whether the game is currently running/playing or not. Running game means the game is in game main-loop (update and render loop).

See Also:
start()

start

public final void start()
Starts the game main loop, this method will not return until the game is finished playing/running. To stop the game use either finish() to quit the game or stop() to hold the game.

Be sure the game graphics engine has been initialized (not null) before attempt to call this method.

See Also:
finish(), initEngine(), distribute, notifyError(Throwable), notifyExit()

initEngine

protected void initEngine()
Game engines is initialized in this method.
Thus modifying or changing any game engines should be done within this method.

List of default game engines initialized in this method :

Example how to modify or change the default game engine :

    protected void initEngine() {
       super.initEngine();

       // change the timer engine
       bsTimer = new GageTimer();

       // modify the music engine base renderer
       bsMusic.setBaseRenderer(new JOrbisOggRenderer());
    }
 

See Also:
bsGraphics, bsIO, bsLoader, bsInput, bsTimer, bsMusic, bsSound, fontManager, com.golden.gamedev.engine

initResources

public abstract void initResources()
All game resources initialization, everything that usually goes to constructor should be put in here.

This method is called only once for every newly created Game class.

See Also:
getImage(String), getImages(String, int, int), playMusic(String), setMaskColor(Color), com.golden.gamedev.object

update

public abstract void update(long elapsedTime)
Updates game variables.

See Also:
keyDown(int), keyPressed(int)

render

public abstract void render(Graphics2D g)
Renders game to the screen.

Parameters:
g - backbuffer graphics context

notifyExit

protected void notifyExit()
Notified when the game is about to quit. By default this method is calling System.exit() to ensure everything is properly shut down.

Override this method to create a custom exit dialog, and be sure to call System.exit() at the end.


notifyError

protected void notifyError(Throwable error)
Notified of any unexpected or uncatch error thrown by the game when the game is ready to distribute (distribute = true).

By default this method creates an ErrorNotificationDialog to show the error to the user.

Override this method to make a custom error dialog, or simply use the ErrorNotificationDialog with your email address provided so the user can directly send the exception to your email.

For example:

    protected void notifyError(Throwable error) {
       new ErrorNotificationDialog(error, bsGraphics,
                                   "Game Title v1.0",       // the game title
                                   "yourmail@address.com"); // your email
    }
 

See Also:
distribute, ErrorNotificationDialog

isDistribute

public final boolean isDistribute()
Returns whether this game is ready to distribute or still in development stage.

See Also:
distribute

showLogo

public final void showLogo()
Shows GTGE logo/splash screen, GTGE is freeware library, please support GTGE by showing this logo on your game, thank you.

Keep this method intact!

See Also:
distribute, notifyError(Throwable)

getRandom

public int getRandom(int low,
                     int hi)
Effectively equivalent to the call Utility.getRandom(int, int)


getWidth

public int getWidth()
Effectively equivalent to the call bsGraphics.getSize().width.


getHeight

public int getHeight()
Effectively equivalent to the call bsGraphics.getSize().height.


takeScreenShot

public BufferedImage takeScreenShot()
Returns a new created buffered image which the current game state is rendered into it.


takeScreenShot

public void takeScreenShot(File f)
Captures current game screen into specified file.

See Also:
takeScreenShot()

playMusic

public int playMusic(String audiofile)
Effectively equivalent to the call bsMusic.play(String).

See Also:
BaseAudio.setBaseRenderer(com.golden.gamedev.engine.BaseAudioRenderer), com.golden.gamedev.engine.audio

playSound

public int playSound(String audiofile)
Effectively equivalent to the call bsSound.play(String).

See Also:
BaseAudio.setBaseRenderer(com.golden.gamedev.engine.BaseAudioRenderer), com.golden.gamedev.engine.audio

setFPS

public void setFPS(int fps)
Effectively equivalent to the call bsTimer.setFPS(int).


getCurrentFPS

public int getCurrentFPS()
Effectively equivalent to the call bsTimer.getCurrentFPS().


getFPS

public int getFPS()
Effectively equivalent to the call BaseTimer.getFPS().


drawFPS

public void drawFPS(Graphics2D g,
                    int x,
                    int y)
Draws game frame-per-second (FPS) to specified location.


getMouseX

public int getMouseX()
Effectively equivalent to the call bsInput.getMouseX().


getMouseY

public int getMouseY()
Effectively equivalent to the call bsInput.getMouseY().


checkPosMouse

public boolean checkPosMouse(int x1,
                             int y1,
                             int x2,
                             int y2)
Returns whether the mouse pointer is inside specified screen boundary.


checkPosMouse

public boolean checkPosMouse(Sprite sprite,
                             boolean pixelCheck)
Returns whether the mouse pointer is inside specified sprite boundary.

Parameters:
sprite - sprite to check its intersection with mouse pointer
pixelCheck - true, checking the sprite image with pixel precision

click

public boolean click()
Effectively equivalent to the call bsInput.isMousePressed(java.awt.event.MouseEvent.BUTTON1).


rightClick

public boolean rightClick()
Effectively equivalent to the call bsInput.isMousePressed(java.awt.event.MouseEvent.BUTTON3).


keyDown

public boolean keyDown(int keyCode)
Effectively equivalent to the call bsInput.isKeyDown(int).


keyPressed

public boolean keyPressed(int keyCode)
Effectively equivalent to the call bsInput.isKeyPressed(int).


hideCursor

public void hideCursor()
Effectively equivalent to the call bsInput.setMouseVisible(false).


showCursor

public void showCursor()
Effectively equivalent to the call bsInput.setMouseVisible(true).


setMaskColor

public void setMaskColor(Color c)
Effectively equivalent to the call bsLoader.setMaskColor(java.awt.Color).


getImage

public BufferedImage getImage(String imagefile,
                              boolean useMask)
Effectively equivalent to the call bsLoader.getImage(String, boolean).


getImage

public BufferedImage getImage(String imagefile)
Effectively equivalent to the call bsLoader.getImage(String).


getImages

public BufferedImage[] getImages(String imagefile,
                                 int col,
                                 int row,
                                 boolean useMask)
Effectively equivalent to the call bsLoader.getImages(String, int, int, boolean).


getImages

public BufferedImage[] getImages(String imagefile,
                                 int col,
                                 int row)
Effectively equivalent to the call bsLoader.getImages(String, int, int).


getImages

public BufferedImage[] getImages(String imagefile,
                                 int col,
                                 int row,
                                 boolean useMask,
                                 String sequence,
                                 int digit)
Returns stripped images with specified sequence.

First the image is stripped by column and row, and then the images is arranged with specified sequence order. The images then stored into cache (bsLoader) with key as followed: the image file + sequence + digit.

For example:

   // we want the images sequence is as followed
   String sequence = "020120";
   BufferedImage[] image = getImages("imagestrip.png", 3, 1, true, sequence, 1);

   // this is plain same like above code except we use 2 digits here
   // 2 digits is used for image strip larger than 10
   String sequence = "000200010200";
   BufferedImage[] image = getImages("imagestrip.png", 20, 1, true, sequence, 1);
 
Notice that the first image is start from 0 (zero).

This is used to make custom animation (012321).


getImages

public BufferedImage[] getImages(String imagefile,
                                 int col,
                                 int row,
                                 String sequence,
                                 int digit)
Same as getImages(imagefile, col, row, useMask, sequence, digit) with mask color is turned on by default.


getImages

public BufferedImage[] getImages(String imagefile,
                                 int col,
                                 int row,
                                 boolean useMask,
                                 int start,
                                 int end)
Returns stripped images with cropped sequence.

First the image is stripped by column and row, and then the images is arranged with specified series sequence order. The images then stored into cache (bsLoader with key as followed: start sequence + the image file + end sequence.

For example:

   int start = 2, end = 4;
   BufferedImage[] image = getImages("imagestrip.png", 6, 1, true, start, end);
 
Notice that the first image is start from 0 (zero).


getImages

public BufferedImage[] getImages(String imagefile,
                                 int col,
                                 int row,
                                 int start,
                                 int end)
Same as getImages(imagefile, col, row, useMask, start, end) with mask color is turned on by default.


GTGE API

Copyright © 2003-2005 Golden T Studios. All rights reserved. Use is subject to license terms.
GoldenStudios.or.id