android.gameengine.icadroids.engine
Class GameEngine

java.lang.Object
  extended by Activity
      extended by android.gameengine.icadroids.engine.GameEngine

public abstract class GameEngine
extends Activity

GameEngine is the core of the game. Extending this class is required to make use of the GameEngine. It contains many methods for GameObjects, Alarms, Sensors, Tiles, etc.

Version:
0.9
Author:
Edward van Raak & Roel van Bergen & Leon van Kleef & Bas van der Zandt & Lex van der Laak

Field Summary
 LinearLayout dashboard
          The game dashboard.
 java.util.ArrayList<LinearLayout> dashboards
          It is possible to have multiple dashboards, stacked on top of each other. this.dashboard always holds the top level dashboard.
static java.util.Vector<Alarm> gameAlarms
          A vectorlist that holds all the active alarms.
static GameTiles gameTiles
           
static java.util.Vector<GameObject> items
          A vectorlist that holds all the active GameObjects.
static java.util.Vector<GameObject> newItems
          A vectorlist that holds all the newly created GameObjects during this cycle of the game loop.
static boolean printDebugInfo
           
 
Constructor Summary
GameEngine()
          The GameEngine forms the core of the game by controlling the gameloop and the render operations.
 
Method Summary
static void addAlarm(Alarm a)
          Add an Alarm to the list of alarms in the GameEngine.
 void addDashboard()
          Add a new dashboard.
 void addGameObject(GameObject gameObject)
          Add a GameObject to the game.
 void addGameObject(GameObject gameObject, float layerposition)
          Add a GameObject to the game.
 void addGameObject(GameObject gameObject, int x, int y)
          Add a GameObject to the game.
 void addGameObject(GameObject gameObject, int x, int y, float layerposition)
          Add a GameObject to the game.
 void addListOfObject(java.util.Collection<GameObject> objectList)
          Add a collection of GameObjects.
 void addToDashboard(LinearLayout dashboard, View v)
          Add an item to a specific dashboard.
 void addToDashboard(View v)
          Add an item to the dashboard that's currently on top.
 void clearBackgroundImage()
          Clears the background Image so only the background color will show
 void deleteAlarm(Alarm a)
          Remove an alarm from the GameEngine.
 void deleteAllAlarms()
          Removes all alarm instances
 void deleteAllGameObjects()
          Delete all GameObjects from the game
<T> void
deleteAllGameObjectsOfType(java.lang.Class<T> type)
          Remove all GameObject instances of given class type.
 void deleteGameObject(GameObject gameObject)
          Delete a GameObject from the game.
protected  void endGame()
          End the game and close the application.
 java.util.Vector<GameObject> findItemAt(Rect rectangle)
          This function finds gameObjects inside a given rectangle.
static Context getAppContext()
          Get Interface to global information about an application environment.
static View getAppView()
           DO NOT CALL THIS METHOD
 GameObject getGameObjectAtTouchPosition(int touchSize)
          Get the first (rendered) object that is touched.
<T> java.util.Vector<GameObject>
getItemsOfType(java.lang.Class<T> type)
          Get all instances of the specified type that are currently in the game
 int getMapHeight()
          Get the height of the game world
 int getMapWidth()
          Get the width of the game world
 MoveableGameObject getPlayer()
          Return the player instance.
 int getRandomX(int width)
          Get random x between left edge of world and right edge minus the specified width.
 int getRandomY(int height)
          Get random y between top edge of world and bottom edge minus the specified height.
static int getScreenHeight()
          Gets the screen height of the telephone this value may change when flipping the telephone.
static int getScreenWidth()
          Gets the screen Width of the telephone this value may change when flipping the telephone.
protected abstract  void initialize()
          This method is like a 'postponed constructor'.
protected  void initializeGameEngine()
           Don't override this method, use initialize() instead This method is called by the GameView to notify the gameEngine to start initializing.
 void intializeInput()
          Initialize the touch and/or the onScreenButtons
 boolean isTileBasedMap()
          Ask whether this game has a tilemap
 void onAccuracyChanged(Sensor sensor, int accuracy)
          DO NOT CALL THIS METHOD This method is part of the Android sensor mechanism.
protected  void onCreate(Bundle savedInstanceState)
          Do NOT call this method.
protected  void onDestroy()
          DO NOT CALL THIS METHOD This method is part of the Android Activity lifecycle which is managed by GameEngine itself.
protected  void onPause()
          DO NOT CALL THIS METHOD This method is part of the Android Activity lifecycle which is managed by GameEngine itself.
protected  void onResume()
          DO NOT CALL THIS METHOD This method is part of the Android Activity lifecycle which is managed by GameEngine itself.
 void onSensorChanged(SensorEvent event)
          DO NOT CALL THIS METHOD This method is part of the Android sensor mechanism.
 void pause()
          Pause the game (stop the gamethread)
static void printDebugInfo(java.lang.String tag, java.lang.String msg)
          Print information into the Logcat, for debugging purposes.
 void resume()
          Resume the game when it had been paused.
 void setBackground(java.lang.String backgroundImage)
          Sets the background image of the current view.
 void setBackground(java.lang.String backgroundImage, boolean backgroundFit)
          Sets the background image of the current view.
 void setBackgroundColor(int backgroundColor)
          Set the background color.
 void setMapDimensions(int mapWidth, int mapHeight)
          Set the dimensions of the game world.
 void setPlayer(MoveableGameObject player)
          Name a GameObject in the role of the Player object.
 void setPlayerPositionOnScreen(int hpositioning, int vpositioning)
          When using a viewport, set the position of the player on the screen.
 void setPlayerPositionTolerance(double ht, double vt)
          Set the tolerance of the positioning of the player.
 void setScreenLandscape(boolean landscape)
          Set landscape mode or normal mode on android device
protected  void setTileMap(GameTiles gameTiles)
          Set a GameTiles object as the current GameTile map.
 void setZoomFactor(float zoomFactor)
          Set the zoom factor for the viewport.
 void showKeyboard()
          Shows the onscreen keyboard.
 Point translateToGamePosition(float x, float y)
          Translates a given screen position to a position in the game world, taking into consideration the viewport location and the zoom factor.
 void update()
          Allows the game to run logic such as updating the world, gathering input and playing audio.
protected  void updateGame()
          Do NOT call this method.
 void vibrate(int milliseconds)
          vibrates the phone for the amount of milliseconds specified.
 void vibrate(long[] pattern)
          Vibrates the phone in the specified pattern.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

printDebugInfo

public static boolean printDebugInfo

items

public static java.util.Vector<GameObject> items
A vectorlist that holds all the active GameObjects. Can be used if you mannualy want to delete/change GameObjects. For instance, you could loop through this list and remove health of every GameObject.


newItems

public static java.util.Vector<GameObject> newItems
A vectorlist that holds all the newly created GameObjects during this cycle of the game loop. At the end of the cycle, all items in this list will be moved to the items-list and the object become active


gameAlarms

public static java.util.Vector<Alarm> gameAlarms
A vectorlist that holds all the active alarms. Can be used if you manually want to delete/change alarms.


gameTiles

public static GameTiles gameTiles

dashboard

public LinearLayout dashboard
The game dashboard. It's an Android LinearLayout (see: http://developer.android.com/reference/android/widget/LinearLayout.html) You can add new dashboard widgets and views to a dashboard by calling the addChild method with the widget to add as a parameter. To manipulate a dashboard widget, either call its run method if it's one of the widgets in android.gameengine.icadroids.dashboard or, if it's something you created yourself, create a runnable and run it on the UI thread using the runOnUiThread method of the GameEngine object (see: http://developer.android.com/reference/android/app/Activity.html#runOnUiThread(java.lang.Runnable) )


dashboards

public java.util.ArrayList<LinearLayout> dashboards
It is possible to have multiple dashboards, stacked on top of each other. this.dashboard always holds the top level dashboard.

Constructor Detail

GameEngine

public GameEngine()
The GameEngine forms the core of the game by controlling the gameloop and the render operations. All games must extend this base class.
You can override the constructor in your game, to create java-objects like ArrayLists and initialize data-variables here. Do not initialize your game here (GameObjects, tiles, etc). These GameObjects use Android resources which are not yet available at start up.
Initialize your game by overriding the initialize()-method.

See Also:
initialize()
Method Detail

onCreate

protected final void onCreate(Bundle savedInstanceState)
Do NOT call this method.

Called when activity is started. Initialise GameEngine objects and set options to be used by the GameEngine.
This method is part of the Android Activity lifecycle which is managed by GameEngine itself.

Parameters:
savedInstanceState -

initializeGameEngine

protected void initializeGameEngine()
Don't override this method, use initialize() instead This method is called by the GameView to notify the gameEngine to start initializing. It will call the initialize, beforeInitialize and afterInitialize method.


initialize

protected abstract void initialize()
This method is like a 'postponed constructor'. It is called automatically by the GameEngine when all necessary Android resources are ready. At that point you can set up your game.
You must override this method inside your game class that extends GameEngine.
Don't call this method yourself (or everything will be done twice!)
You can perform any initialization the game needs to before starting to run, like:


intializeInput

public void intializeInput()
Initialize the touch and/or the onScreenButtons


updateGame

protected final void updateGame()
Do NOT call this method.

Call the update for every GameObject added to the list.


onAccuracyChanged

public final void onAccuracyChanged(Sensor sensor,
                                    int accuracy)
DO NOT CALL THIS METHOD

This method is part of the Android sensor mechanism. It is used by GameEngine itself.


onSensorChanged

public void onSensorChanged(SensorEvent event)
DO NOT CALL THIS METHOD

This method is part of the Android sensor mechanism. It is used by GameEngine itself.


update

public void update()
Allows the game to run logic such as updating the world, gathering input and playing audio.

Override this method inside your game base class that extends from GameEngine. Every pass of the game loop this method is called once.

GameObjects that were added to the game (by either addPlayer or addGameObject) should NOT be updated here. Classes that extend from GameObject or MovableGameObject have their own update() that should be overwritten.

See Also:
MoveableGameObject, GameObject

addAlarm

public static void addAlarm(Alarm a)
Add an Alarm to the list of alarms in the GameEngine. You must add an Alarm to make it 'tick', but it won't start ticking until you call startAlarm()!

Parameters:
a - The alarm to be added.

deleteAlarm

public void deleteAlarm(Alarm a)
Remove an alarm from the GameEngine. It will stop ticking.

Parameters:
a - The alarm to be deleted.

deleteAllAlarms

public void deleteAllAlarms()
Removes all alarm instances


deleteGameObject

public final void deleteGameObject(GameObject gameObject)
Delete a GameObject from the game.

Parameters:
gameObject - The GameObject instance to be removed

deleteAllGameObjects

public final void deleteAllGameObjects()
Delete all GameObjects from the game


deleteAllGameObjectsOfType

public <T> void deleteAllGameObjectsOfType(java.lang.Class<T> type)
Remove all GameObject instances of given class type.

Parameters:
type - De class type of the instances to be removed

onResume

protected final void onResume()
DO NOT CALL THIS METHOD

This method is part of the Android Activity lifecycle which is managed by GameEngine itself.


onDestroy

protected final void onDestroy()
DO NOT CALL THIS METHOD

This method is part of the Android Activity lifecycle which is managed by GameEngine itself.


onPause

protected final void onPause()
DO NOT CALL THIS METHOD

This method is part of the Android Activity lifecycle which is managed by GameEngine itself.


endGame

protected final void endGame()
End the game and close the application.


addGameObject

public final void addGameObject(GameObject gameObject,
                                int x,
                                int y)
Add a GameObject to the game. New GameObjects will become active in the next pass of the gameloop.

Parameters:
gameObject - The GameObject that will be added to the game. Should have either GameObject or MovableGameObject as it's parent.
x - The X spawnlocation when this object is created
y - The Y spawnlocation when this object is created

addGameObject

public final void addGameObject(GameObject gameObject,
                                int x,
                                int y,
                                float layerposition)
Add a GameObject to the game. New GameObjects will become active in the next pass of the gameloop.
Layerposition may not work very well as yet, still under construction.

Parameters:
gameObject - The GameObject that will be added to the game. Should have either GameObject or MovableGameObject as it's parent.
x - The X spawnlocation when this object is created
y - The Y spawnlocation when this object is created
layerposition - The layerposition when this object is drawed. Between 0 and 1 (float). 1 front, 0 back

addGameObject

public final void addGameObject(GameObject gameObject,
                                float layerposition)
Add a GameObject to the game. New GameObjects will become active in the next pass of the gameloop.
Layerposition may not work very well as yet, still under construction.

Parameters:
gameObject - The GameObject that will be added to the game. Should have either GameObject or MovableGameObject as it's parent.
layerposition - The layerposition when this object is drawed. Between 0 and 1 (float). 1 front, 0 back

addGameObject

public final void addGameObject(GameObject gameObject)
Add a GameObject to the game. New GameObjects will become active in the next pass of the gameloop.

Parameters:
gameObject - The GameObject that will be added to the game. Should have either GameObject or MovableGameObject as it's parent.

addListOfObject

public final void addListOfObject(java.util.Collection<GameObject> objectList)
Add a collection of GameObjects. Useful if you want to add a lot of objects.

Parameters:
objectList -

setTileMap

protected void setTileMap(GameTiles gameTiles)
Set a GameTiles object as the current GameTile map.
Do not make a map that has parts sticking out. Use -1 to create an empty space.
Note: You can switch tilemaps, for instance when you move from one level to the next. Therefore the dimensions of the world are not set. Set the world dimensions yourself, to values that will make all of your tilemaps fit.

Parameters:
gameTiles - the current gameTiles object.

isTileBasedMap

public boolean isTileBasedMap()
Ask whether this game has a tilemap

Returns:
boolean, true if there are tiles.

vibrate

public final void vibrate(long[] pattern)
Vibrates the phone in the specified pattern.

Parameters:
pattern - the pattern is an array of milliseconds. the first value in the pattern is the amount of time to wait before turning the vibration on the second value is how long it should actually vibrate this is repeated trough out: gap-vibration-gap-vibration etc.. example SOS: long[] pattern = {200,500,200,800,200,500,200}; in this number 200 is represented as a short gap.

vibrate

public final void vibrate(int milliseconds)
vibrates the phone for the amount of milliseconds specified.

Parameters:
milliseconds - the amount of milliseconds

getPlayer

public final MoveableGameObject getPlayer()
Return the player instance.

Returns:
the GameObject that has been set to be the playerobject

setPlayer

public final void setPlayer(MoveableGameObject player)
Name a GameObject in the role of the Player object. Note that this is relevant only for the viewport. If your game is larger than the screen, the viewport will follow the GameObject that has been set as player.
You have to add the GameObject to the game before assigning the player role.
Only one GameObject can be the player. If you call this method for a second time, the player role will switch to the newly specified object. player.

Parameters:
player - The player that should be added to the game. The location of this player is used by the viewport.

setBackground

public final void setBackground(java.lang.String backgroundImage,
                                boolean backgroundFit)
Sets the background image of the current view. You can indicate if the image must be scaled to fit the screen.
Images must be stored in the res/drawable folders of your Android project. If you have only one image, store it in the 'nodpi' folder. If you have various versions (hi-res and lo-res) for rendering on devices of varying screen sizes, use the lo- & hi-dpi folders.

Parameters:
backgroundImage - The name of the background image that will be set.
backgroundFit - boolean, indicating if the image must be scaled to fit.

setBackground

public final void setBackground(java.lang.String backgroundImage)
Sets the background image of the current view. The image will not be scaled to fit the screen. The viewport will scroll over the backgroundimage, just like it does over the rest of the game.
Images must be stored in the res/drawable folders of your Android project. If you have only one image, store it in the 'nodpi' folder. If you have various versions (hi-res and lo-res) for rendering on devices of varying screen sizes, use the lo- & hi-dpi folders.

Parameters:
backgroundImage - The name of the background image that will be set

setZoomFactor

public final void setZoomFactor(float zoomFactor)
Set the zoom factor for the viewport. Always set higher than 1. 2 = 200%.
Zooming only works when the viewport is being used.

Parameters:
zoomFactor - a float, the factor by which the view must be enlarged.

setPlayerPositionOnScreen

public final void setPlayerPositionOnScreen(int hpositioning,
                                            int vpositioning)
When using a viewport, set the position of the player on the screen.
In many games, the game world is bigger than the screen. When you specify the player position, you can make the screen (viewport) move along with the player. The parameters tell how this must be done.
For the vpositioning (vertical adjustment) you can use Viewport.PLAYER_TOP, Viewport.PLAYER_CENTER, Viewport.PLAYER_BOTTOM or Viewport.PLAYER_NOADJUST, if you don't want adjustment of the player position in the vertical direction.
For the hpositioning (horizontal adjustment) you can use Viewport.PLAYER_LEFT, Viewport.PLAYER_CENTER, Viewport.PLAYER_RIGHT or Viewport.PLAYER_NOADJUST, if you don't want adjustment of the player position in the horizontal direction.
Note: if you position the player at one of the edges of the screen, like BOTTOM, this means that you can not move out of the screen that way, but you can move up a bit. How much that is, is specified by setPlayerPositionTolerance.

Parameters:
hpositioning - the horizontal postioning, or Viewport.PLAYER_NOADJUST if there is no horizontal adjustment of the viewport
vpositioning - the vertical postioning, or Viewport.PLAYER_NOADJUST if there is no vertical adjustment of the viewport

setPlayerPositionTolerance

public final void setPlayerPositionTolerance(double ht,
                                             double vt)
Set the tolerance of the positioning of the player. When tolerance is zero, the viewport moves immediately when the player moves. When tolerance is 1, you can move to the edge of the screen before the viewport moves. Values in between result in a smaller or bigger delay before the viewport moves.
Example: In a left-to right platform game, you may position the player at LEFT, CENTER. If you set the horizontal tolerance at 0.3, you may move to the right 30% of the screen before the viewport moves along. If you set vertical tolerance at 0.8, you can move 80% of the way up, before the viewport moves up also.
This method only has effect when you are using the viewport.

Parameters:
ht - horizontal tolerance, a value between 0 and 1
vt - vertical tolerance, a value between 0 and 1

translateToGamePosition

public Point translateToGamePosition(float x,
                                     float y)
Translates a given screen position to a position in the game world, taking into consideration the viewport location and the zoom factor.
Note: The x and y values are returned in a Point object, therefore they are returned as ints. You can access the individual values using .x and .y.

Parameters:
x - the screen x
y - the screen y
Returns:
Point, containing the x,y-position in the game world

clearBackgroundImage

public final void clearBackgroundImage()
Clears the background Image so only the background color will show


getItemsOfType

public final <T> java.util.Vector<GameObject> getItemsOfType(java.lang.Class<T> type)
Get all instances of the specified type that are currently in the game

Parameters:
type - the class name with .class behind it.
Returns:
an arraylist containing all gameObjects of the specified type.

findItemAt

public final java.util.Vector<GameObject> findItemAt(Rect rectangle)
This function finds gameObjects inside a given rectangle.

Parameters:
rectangle - the rectangle specified in a left, top to bottom,right location
Returns:
the list of items it found at the location the size is zero when nothing is found.

getMapWidth

public int getMapWidth()
Get the width of the game world

Returns:
width, an int

getMapHeight

public int getMapHeight()
Get the height of the game world

Returns:
height, an int

setMapDimensions

public void setMapDimensions(int mapWidth,
                             int mapHeight)
Set the dimensions of the game world.
By default the dimensions will be set to the size of the screen. If you want to play a larger game world, you can set the dimensions calleing this method in initialize().
Note: You also need to set the world dimensions when you use a tile map.

Parameters:
mapWidth - an int specifying the width of the game world
mapHeight - an int specifying the height of the game world

getScreenWidth

public static final int getScreenWidth()
Gets the screen Width of the telephone this value may change when flipping the telephone.

Returns:
the screen width.

getScreenHeight

public static final int getScreenHeight()
Gets the screen height of the telephone this value may change when flipping the telephone.

Returns:
the screen height.

setScreenLandscape

public final void setScreenLandscape(boolean landscape)
Set landscape mode or normal mode on android device

Parameters:
landscape - true if landscape screen is required, false if not

getAppContext

public static Context getAppContext()
Get Interface to global information about an application environment. This is an abstract class whose implementation is provided by the Android system. It allows access to application-specific resources and classes, as well as up-calls for application-level operations such as launching activities, broadcasting and receiving intents, etc.

Returns:
appcontext

getAppView

public static View getAppView()
DO NOT CALL THIS METHOD

Returns:
The GameView object

setBackgroundColor

public void setBackgroundColor(int backgroundColor)
Set the background color. Use Color class from Android. Example: Color.Red/Color.Blue/Color.Cyan.

Parameters:
backgroundColor -

pause

public void pause()
Pause the game (stop the gamethread)


resume

public void resume()
Resume the game when it had been paused.


showKeyboard

public void showKeyboard()
Shows the onscreen keyboard. Function is unstable around devices! Use with care!


printDebugInfo

public static void printDebugInfo(java.lang.String tag,
                                  java.lang.String msg)
Print information into the Logcat, for debugging purposes.

Parameters:
tag - The tag (shown in Logcat)
msg - The message you want to be displayed

getGameObjectAtTouchPosition

public final GameObject getGameObjectAtTouchPosition(int touchSize)
Get the first (rendered) object that is touched. Useful for checking if a gameObject is touched.

Parameters:
touchSize - The size (rectangle) around the finger that will be checked for objects.
Returns:
The first (rendered) gameObject that is touched.

getRandomX

public int getRandomX(int width)
Get random x between left edge of world and right edge minus the specified width. In this way you can find a random position for an item of the given width and the item will fit completely into the world.

Parameters:
width -
Returns:
a random x-position

getRandomY

public int getRandomY(int height)
Get random y between top edge of world and bottom edge minus the specified height. In this way you can find a random position for an item of the given height and the item will fit completely into the world.

Parameters:
height -
Returns:
a random y-position

addDashboard

public void addDashboard()
Add a new dashboard. The new dashboard will be placed in front of all other items on the screen.


addToDashboard

public void addToDashboard(View v)
Add an item to the dashboard that's currently on top.

Parameters:
v - the view to add to the dashboard.

addToDashboard

public void addToDashboard(LinearLayout dashboard,
                           View v)
Add an item to a specific dashboard.

Parameters:
dashboard -
v -