GTGE API

com.golden.gamedev.object
Class SpriteGroup

java.lang.Object
  extended by com.golden.gamedev.object.SpriteGroup
Direct Known Subclasses:
AdvanceSpriteGroup

public class SpriteGroup
extends Object

Group of sprites with common behaviour, for example PLAYER_GROUP, ENEMY_GROUP, etc. This class maintain a growable sprite list (array of sprites). Each time a sprite is added into this group, this group automatically adjust the size of its sprites array.

SpriteGroup is used to store a list of sprites and also manage the sprites updating, rendering, and collision check.

For example how to create and use sprite group :

    SpriteGroup ENEMY_GROUP;

    public void initResources() {
       // creates the enemy sprites
       Sprite asteroid = new Sprite();
       Sprite asteroid2 = new Sprite();

       // creates and add the sprites into enemy group
       ENEMY_GROUP = new SpriteGroup("Enemy");
       ENEMY_GROUP.add(asteroid);
       ENEMY_GROUP.add(asteroid2);
    }

    public void update(long elapsedTime) {
       // update all enemies at once
       ENEMY_GROUP.update(elapsedTime);
    }

    public void render(Graphics2D g) {
       // render all enemies at once to the screen
       ENEMY_GROUP.render(g);
    }
 

See Also:
PlayField, CollisionGroup

Constructor Summary
SpriteGroup(String name)
          Creates a new sprite group, with specified name.
 
Method Summary
 void add(int index, Sprite member)
          Inserts sprite at specified index, range from [0 - size].
 void add(Sprite member)
          Inserts sprite at the bottom (last index) of this group.
 void clear()
          Removes all members from this group, thus makes this group empty.
 Sprite getActiveSprite()
          Returns the first active sprite found in this group, or null if there is no active sprite.
 Background getBackground()
          Returns the background of this group.
 Comparator getComparator()
          Returns comparator used for sorting sprites in this group.
 int getExpandFactor()
          Returns allocation size for empty sprite (null sprite).
 Sprite getInactiveSprite()
          Returns the first inactive sprite found in this group (the returned sprite is automatically set to active), or null if there is no inactive sprite, please see Sprite.setImmutable(boolean) for tag method of this method.
 String getName()
          Returns the name of this group.
 Timer getScanFrequence()
          Schedule timer for removing inactive sprites.
 int getSize()
          Returns total active and inactive sprites (non-null sprites) in this group.
 Sprite[] getSprites()
          Returns all sprites (active, inactive, and also null sprite) in this group.
 boolean isActive()
          Returns active state of this group.
 Sprite remove(int index)
          Removes sprite at specified index from this group.
 boolean remove(Sprite s)
          Removes specified sprite from this group.
 void removeImmutableSprites()
          Throws all inactive sprites from this group even the sprite is immutable sprite.
 void removeInactiveSprites()
          Throws any inactive sprites from this group, this method won't remove immutable sprites, to remove all inactive sprites even though the inactive sprites are immutable use removeImmutableSprites().
 void render(Graphics2D g)
          Renders all active sprites in this group.
 void reset()
          Removes all group members, same with clear(), except this method also removes sprite memory reference immediately.
 void setActive(boolean b)
          Sets active state of this group, inactive group won't be updated, rendered, and won't be checked for collision.
 void setBackground(Background backgr)
          Associates specified background with this sprite group, the background will be used by all sprites in this group.
 void setComparator(Comparator c)
          Sets comparator used for sorting sprites in this group.
 void setExpandFactor(int factor)
          Sets allocation size for empty sprite (null sprite).
 void setName(String name)
          Sets the name of this group.
 void sort(Comparator c)
          Sorts all sprites in this group with specified comparator.
 String toString()
           
 void update(long elapsedTime)
          Updates all active sprites in this group, and check the schedule for removing inactive sprites.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SpriteGroup

public SpriteGroup(String name)
Creates a new sprite group, with specified name. Name is used for group identifier only.

Method Detail

add

public void add(Sprite member)
Inserts sprite at the bottom (last index) of this group.

Sprite at the last index (index = size-1) is rendered on top of other sprites (last rendered).

See Also:
add(int, Sprite)

add

public void add(int index,
                Sprite member)
Inserts sprite at specified index, range from [0 - size].

Sprite at the first index (index = 0) is at the back of other sprites (first rendered).
Sprite at the last index (index = size-1) is rendered on top of other sprites (last rendered).


remove

public Sprite remove(int index)
Removes sprite at specified index from this group.

This method has a big performance hit, avoid using this method in tight-loop (main-loop).
The standard way to remove a sprite from its group is by setting sprite active state to false Sprite.setActive(false).

SpriteGroup is designed to remove any inactive sprites automatically after a period, use directly sprite removal method only for specific purpose (if you really know what you are doing).

See Also:
Sprite.setActive(boolean), getScanFrequence()

remove

public boolean remove(Sprite s)
Removes specified sprite from this group.

This method has a big performance hit, avoid using this method in tight-loop (main-loop).
The standard way to remove a sprite from its group is by setting sprite active state to false Sprite.setActive(false).

SpriteGroup is designed to remove any inactive sprites automatically after a period, use directly sprite removal method only for specific purpose (if you really know what you are doing).

Returns:
true, if specified sprite is successfuly removed from the group, or false if the sprite is not belong to this group.
See Also:
Sprite.setActive(boolean), getScanFrequence()

clear

public void clear()
Removes all members from this group, thus makes this group empty.

For example:
Destroying all enemies when player got a bomb.

     ENEMY_GROUP.clear();
 

This method simply set group size to nil. The sprites reference is actually removed when removeInactiveSprites() is scheduled.

To remove all sprites and also its reference immediately, use reset() instead.

See Also:
reset()

reset

public void reset()
Removes all group members, same with clear(), except this method also removes sprite memory reference immediately.

Use this method if only the size of the removed sprites is taking too big memory and you need to reclaim the used memory immediately.

See Also:
clear()

update

public void update(long elapsedTime)
Updates all active sprites in this group, and check the schedule for removing inactive sprites.

See Also:
getScanFrequence()

removeInactiveSprites

public void removeInactiveSprites()
Throws any inactive sprites from this group, this method won't remove immutable sprites, to remove all inactive sprites even though the inactive sprites are immutable use removeImmutableSprites().

This method is automatically called every time timer for scanning inactive sprite is scheduled.

See Also:
getScanFrequence(), removeImmutableSprites(), Sprite.setImmutable(boolean)

removeImmutableSprites

public void removeImmutableSprites()
Throws all inactive sprites from this group even the sprite is immutable sprite.

See Also:
getInactiveSprite(), removeInactiveSprites(), Sprite.setImmutable(boolean)

render

public void render(Graphics2D g)
Renders all active sprites in this group. If this group is associated with a comparator, the group sprites is sort against the comparator first before rendered.

See Also:
setComparator(Comparator)

sort

public void sort(Comparator c)
Sorts all sprites in this group with specified comparator.

This method only sort the sprites once called, use setComparator(Comparator) instead to sort the sprites on each update.

See Also:
setComparator(Comparator)

getName

public String getName()
Returns the name of this group. Name is used for group identifier only.

See Also:
setName(String)

setName

public void setName(String name)
Sets the name of this group. Name is used for group identifier only.

See Also:
getName()

getBackground

public Background getBackground()
Returns the background of this group.

See Also:
setBackground(Background)

setBackground

public void setBackground(Background backgr)
Associates specified background with this sprite group, the background will be used by all sprites in this group.

See Also:
getBackground()

isActive

public boolean isActive()
Returns active state of this group.

See Also:
setActive(boolean)

setActive

public void setActive(boolean b)
Sets active state of this group, inactive group won't be updated, rendered, and won't be checked for collision.

See Also:
isActive()

getComparator

public Comparator getComparator()
Returns comparator used for sorting sprites in this group.

See Also:
setComparator(Comparator)

setComparator

public void setComparator(Comparator c)
Sets comparator used for sorting sprites in this group. 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 by Arrays.sort(java.lang.Object[], int, int, java.util.Comparator) to sort the sprites before rendering. 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 :

    SpriteGroup ENEMY_GROUP;

    ENEMY_GROUP.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)

getActiveSprite

public Sprite getActiveSprite()
Returns the first active sprite found in this group, or null if there is no active sprite.

This method usually used to check whether this group still have alive member or not.
Note: alive group has different meaning from active group, inactive group is not updated and rendered even there are many active sprites in the group, but dead group means there are no active sprites in the group.

For example :

    SpriteGroup ENEMY_GROUP;

    if (ENEMY_GROUP.getActiveSprite() == null) {
        // no active enemy, advance to next level
        gameState = WIN;
    }
 

Returns:
The first found active sprite, or null if there is no active sprite in this group.
See Also:
Sprite.setActive(boolean)

getInactiveSprite

public Sprite getInactiveSprite()
Returns the first inactive sprite found in this group (the returned sprite is automatically set to active), or null if there is no inactive sprite, please see Sprite.setImmutable(boolean) for tag method of this method.

This method is used for optimization, to reuse inactive sprite instead of making new sprite.

For example :

    SpriteGroup PROJECTILE_GROUP;

    Sprite projectile = PROJECTILE_GROUP.getInactiveSprite();
    if (projectile == null) {
       // create new projectile if there is no inactive projectile
       projectile = new Sprite(...);
       PROJECTILE_GROUP.add(projectile);
    }

    // set projectile location and other stuff
    projectile.setLocation(....);
 

This method is only a convenient way to return the first found inactive sprite. To filter the inactive sprite, simply find and then filter the inactive sprite like this :

    SpriteGroup A_GROUP;
    Sprite inactiveSprite = null;
    Sprite[] sprites = A_GROUP.getSprites();
    int size = A_GROUP.getSize();

    for (int i=0;i < size;i++) {
       if (!sprites[i].isActive()) {
          // do the filter
          // for example, we want only reuse sprite that has ID = 100
          if (sprites[i].getID() == 100) {
             inactiveSprite = sprites[i];
             // activate sprite
             inactiveSprite.setActive(true);
             break;
          }
       }
    }

    if (inactiveSprite == null) {
       // no inactive sprite found like the criteria (ID = 100)
       // create new sprite
    }

    // reuse the inactive sprite
    inactiveSprite.setLocation(...);
 

Returns:
The first found inactive sprite, or null if there is no inactive sprite in this group.
See Also:
Sprite.setImmutable(boolean)

getSprites

public Sprite[] getSprites()
Returns all sprites (active, inactive, and also null sprite) in this group.

How to iterate all sprites :

    SpriteGroup GROUP;

    Sprite[] sprites = GROUP.getSprites();
    int size = GROUP.getSize();

    // iterate the sprite one by one
    for (int i=0;i < size;i++) {
       // remember the sprite array consists inactive sprites too
       // you need to check sprite active state before process the sprite
       if (sprites[i].isActive()) {
          // now, what do you want with this active sprite?
          // move it to (0, 0)
          sprites[i].setLocation(0, 0);
       }
    }
 

See Also:
getSize()

getSize

public int getSize()
Returns total active and inactive sprites (non-null sprites) in this group.

See Also:
getSprites()

getExpandFactor

public int getExpandFactor()
Returns allocation size for empty sprite (null sprite).

See Also:
setExpandFactor(int)

setExpandFactor

public void setExpandFactor(int factor)
Sets allocation size for empty sprite (null sprite). This factor is used only for optimization (reduce the cost of array enlargement operation).

The process :
If there is a new member insertion to the group and the group sprite array has been full, the array is expanded as large as this factor. For example:
Expand factor is 20 (the default).
The group size is 100.
The group member is also 100.

If new member is added into this group, the group size is automatically grow to 120 (100+20).
The new sprite added is at index 101 and the rest is empty sprite (null sprite).

Note: use large expand factor if there are many sprites inserted into this group in a period.

See Also:
getExpandFactor()

getScanFrequence

public Timer getScanFrequence()
Schedule timer for removing inactive sprites.

For example to set this group to scan inactive sprite every 30 seconds (the default is 15 seconds) :

    SpriteGroup PLAYER_GROUP;

    PLAYER_GROUP.getScanFrequence().setDelay(30000); // 30 x 1000 ms
 

See Also:
removeInactiveSprites()

toString

public String toString()
Overrides:
toString in class Object

GTGE API

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