GTGE API

com.golden.gamedev.object
Class PlayField

java.lang.Object
  extended by com.golden.gamedev.object.PlayField

public class PlayField
extends Object

PlayField class is the game arena where all the game objects are put on. This class manages all objects in the game, such as sprite, background, sprite group, and collision check.

PlayField simplify sprite updating and rendering.
By calling update(long) all sprites within this playfield will be updated and collision will be check.
By calling render(Graphics2D) all sprites will be rendered to the screen.

See Also:
SpriteGroup, CollisionManager

Constructor Summary
PlayField()
          Constructs new PlayField with default background.
PlayField(Background background)
          Constructs new PlayField with specified background.
 
Method Summary
 void add(Sprite extra)
          Inserts a sprite (extra sprite) directly into playfield, for example animation, explosion, etc.
 void addCollisionGroup(SpriteGroup group1, SpriteGroup group2, CollisionManager collisionGroup)
          Associates specified collision group to this playfield.
 SpriteGroup addGroup(SpriteGroup group)
          Inserts new SpriteGroup into this playfield.
protected  void checkCollisions()
          Checks for collision event.
 void clearCache()
          Clears cache sprite.
 void clearPlayField()
          Clears all sprites in this playfield and makes this playfield empty.
 Background getBackground()
          Returns background associated with this playfield.
 CollisionManager getCollisionGroup(SpriteGroup group)
          Returns any collision group associated with specified sprite group.
 CollisionManager getCollisionGroup(SpriteGroup group1, SpriteGroup group2)
          Returns associated collision group that checking collision of group1 and group2, or null if requested collision group can not be found.
 CollisionManager[] getCollisionGroups()
          Returns all collision group associated with this playfield.
 Comparator getComparator()
          Returns playfield comparator, comparator is used for sorting the sprites before rendering.
 SpriteGroup getExtraGroup()
          Returns this playfield extra sprite group.
 SpriteGroup getGroup(String name)
          Returns sprite group with specified name associated with this playfield.
 SpriteGroup[] getGroups()
          Returns all sprite group associated with this playfield.
 boolean removeCollisionGroup(CollisionManager collisionGroup)
          Removes specified collision group from this playfield.
 boolean removeGroup(SpriteGroup group)
          Removes specified sprite group from this playfield.
 void render(Graphics2D g)
          Renders background, and sprite groups (with/without comparator).
protected  void renderBackground(Graphics2D g)
          Renders background to specified graphics context.
protected  void renderSpriteGroups(Graphics2D g)
          Renders sprite groups to specified graphics context.
protected  void renderSpriteGroups(Graphics2D g, Comparator c)
          Renders all sprites using specified comparator.
 void setBackground(Background backgr)
          Associates specified background to this playfield.
 void setComparator(Comparator c)
          Sets playfield comparator, comparator is used for sorting the sprites before rendering.
 void update(long elapsedTime)
          Updates sprites, background, and check for collisions.
protected  void updateBackground(long elapsedTime)
          Updates playfield background.
protected  void updateSpriteGroups(long elapsedTime)
          Updates sprites in sprite groups on this playfield.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PlayField

public PlayField(Background background)
Constructs new PlayField with specified background.


PlayField

public PlayField()
Constructs new PlayField with default background.

Method Detail

add

public void add(Sprite extra)
Inserts a sprite (extra sprite) directly into playfield, for example animation, explosion, etc.

This method is a convenient way to add sprites directly into screen without have to creates new SpriteGroup.

The sprite is inserted to 'extra group' and all sprites on extra group will always on top of other sprites.


addGroup

public SpriteGroup addGroup(SpriteGroup group)
Inserts new SpriteGroup into this playfield. This method returned object reference of the inserted group.

The returned group used to reduce code and simplicity.
For example :

     Playfield playfield = new Playfield();
     SpriteGroup PLAYER  = playfield.addGroup(new SpriteGroup("Player"));
 
If there is no returned reference, we must set the sprite group and add it manually into playfield :
     SpriteGroup PLAYER    = new SpriteGroup("Player");

     Playfield   playfield = new Playfield();
     playfield.addGroup(PLAYER);
 

Parameters:
group - sprite group to be inserted into this playfield
Returns:
Reference of the inserted sprite group.

removeGroup

public boolean removeGroup(SpriteGroup group)
Removes specified sprite group from this playfield.

Parameters:
group - sprite group to be removed from this playfield
Returns:
true, if the sprite group is successfuly removed.

getGroup

public SpriteGroup getGroup(String name)
Returns sprite group with specified name associated with this playfield.


getGroups

public SpriteGroup[] getGroups()
Returns all sprite group associated with this playfield.


getExtraGroup

public SpriteGroup getExtraGroup()
Returns this playfield extra sprite group.

Extra sprite group is preserve group that always in front of other groups, usually used to hold game animation such as explosion.

This group also exists for convenient way to add sprite into playfield without creating sprite group.

See Also:
add(Sprite)

clearPlayField

public void clearPlayField()
Clears all sprites in this playfield and makes this playfield empty.

This method iterates all groups in this playfield and remove all sprites inside it by calling SpriteGroup.clear()


addCollisionGroup

public void addCollisionGroup(SpriteGroup group1,
                              SpriteGroup group2,
                              CollisionManager collisionGroup)
Associates specified collision group to this playfield.


removeCollisionGroup

public boolean removeCollisionGroup(CollisionManager collisionGroup)
Removes specified collision group from this playfield.

Returns:
true, if the collision group is successfully removed.

getCollisionGroup

public CollisionManager getCollisionGroup(SpriteGroup group1,
                                          SpriteGroup group2)
Returns associated collision group that checking collision of group1 and group2, or null if requested collision group can not be found.

Parameters:
group1 - the first group of the collision group to be find
group2 - the second group of the collision group to be find
Returns:
CollisionGroup that checks group1 and group2 for collision, or null if no collision group can be found.

getCollisionGroup

public CollisionManager getCollisionGroup(SpriteGroup group)
Returns any collision group associated with specified sprite group.


getCollisionGroups

public CollisionManager[] getCollisionGroups()
Returns all collision group associated with this playfield.


update

public void update(long elapsedTime)
Updates sprites, background, and check for collisions.


updateBackground

protected void updateBackground(long elapsedTime)
Updates playfield background.


updateSpriteGroups

protected void updateSpriteGroups(long elapsedTime)
Updates sprites in sprite groups on this playfield.


checkCollisions

protected void checkCollisions()
Checks for collision event.


render

public void render(Graphics2D g)
Renders background, and sprite groups (with/without comparator).


renderBackground

protected void renderBackground(Graphics2D g)
Renders background to specified graphics context.


renderSpriteGroups

protected void renderSpriteGroups(Graphics2D g)
Renders sprite groups to specified graphics context.


renderSpriteGroups

protected void renderSpriteGroups(Graphics2D g,
                                  Comparator c)
Renders all sprites using specified comparator. Only active and on screen sprite is sorted and rendered.

Sprites that rendered within this method is stored in cache, therefore if this method is called ONLY ONCE and then comparator is set to null, it is better to manually clear the cache after it or the cache will hold the sprites forever and makes the sprite can't be disposed.


clearCache

public void clearCache()
Clears cache sprite.

Cache sprite is used to keep sprites in sorted order (if this playfield used an external comparator).
When renderSpriteGroups(Graphics2D, Comparator) called, all sprites are stored in cache and then sorted, Therefore after rendering done, the cache still remain in memory and wait to be cached again on next sort rendering.

This method simply clears the cache sprite. Call this method when sort rendering is not needed anymore.

See Also:
renderSpriteGroups(Graphics2D, Comparator)

getBackground

public Background getBackground()
Returns background associated with this playfield.


setBackground

public void setBackground(Background backgr)
Associates specified background to this playfield.


getComparator

public Comparator getComparator()
Returns playfield comparator, comparator is used for sorting the sprites before rendering.


setComparator

public void setComparator(Comparator c)
Sets playfield comparator, comparator is used for sorting the sprites before rendering. Specify null comparator for unsort order (the first sprite in the array will be rendered at the back of other sprite).

The comparator is used in Arrays.sort(java.lang.Object[], int, int, java.util.Comparator) from the java.lang package to sort the sprites, for more information about how to make comparator, please read java.util.Comparator and java.util.Arrays#sort(). Example of sorting sprites based on y-axis :

    PlayField playfield;

    playfield.setComparator(
       new Comparator() {
          public int compare(Object o1, Object o2) {
             Sprite s1 = (Sprite) o1,
                    s2 = (Sprite) o2;

             return (s1.getY() - s2.getY());
          }
       }
    };
 

Parameters:
c - the sprite comparator, null for unsort order
See Also:
Comparator, Arrays.sort(java.lang.Object[], int, int, java.util.Comparator)

GTGE API

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