GTGE API

com.golden.gamedev.object
Class Sprite

java.lang.Object
  extended by com.golden.gamedev.object.Sprite
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
AnimatedSprite, PatternSprite

public class Sprite
extends Object
implements Serializable

Sprite is the object in game that has graphical look and has its own behaviour.

Every sprite is lived in a background, by default sprite is attached to default background, always remember to set the sprite to the game background or use SpriteGroup class in PlayField to take care the sprite background set automatically.

Sprite is located somewhere in the background, to set sprite location simply use setLocation(double, double).
And to move the sprite use either by moving the sprite directly by using (@linkplain #move(double, double)} or give speed to the sprite by using setSpeed(double, double).

In conjunction with sprite group/playfield, every sprite has active state, this active state that determine whether the sprite is alive or not. Thus to remove a sprite from playfield, simply set the sprite active state to false by using setActive(false).

To create sprite behaviour, always use Timer class utility in order to make the sprite behaviour independent of frame rate.

See Also:
SpriteGroup, PlayField, Timer, Serialized Form

Field Summary
protected  int height
          The height of this sprite.
protected  int width
          The width of this sprite.
 
Constructor Summary
Sprite()
          Creates new Sprite with null image and located at (0, 0).
Sprite(BufferedImage image)
          Creates new Sprite with specified image and located at (0, 0).
Sprite(BufferedImage image, double x, double y)
          Creates new Sprite with specified image and location.
Sprite(double x, double y)
          Creates new Sprite with specified position and null image.
 
Method Summary
 void addHorizontalSpeed(long elapsedTime, double accel, double maxSpeed)
          Accelerates sprite horizontal speed by accel and limit the speed to maxSpeed.
 void addVerticalSpeed(long elapsedTime, double accel, double maxSpeed)
          Accelerates sprite vertical speed by accel and limit the speed to maxSpeed.
 void forceX(double xs)
          Forces sprite x position to specified coordinate.
 void forceY(double ys)
          Forces sprite y position to specified coordinate.
 Background getBackground()
          Returns the background where this sprite lived.
 Object getDataID()
          Returns sprite data ID, ID is used to mark a sprite from other sprite.
 double getDistance(Sprite other)
          Returns the distance of this sprite from the specified sprite.
 int getHeight()
          Returns the height of this sprite.
 double getHorizontalSpeed()
          Returns horizontal speed of the sprite.
 int getID()
          Returns sprite ID, ID is used to mark a sprite from other sprite.
 BufferedImage getImage()
          Returns the image of this sprite.
 int getLayer()
          Returns the layer of this sprite.
 double getOldX()
          Returns sprite x coordinate before the sprite moving to the current position.
 double getOldY()
          Returns sprite y coordinate before the sprite moving to the current position.
 double getScreenX()
          Returns sprite x coordinate relative to screen area.
 double getScreenY()
          Returns sprite y coordinate relative to screen area.
 double getVerticalSpeed()
          Returns vertical speed of the sprite.
 int getWidth()
          Returns the width of this sprite.
 double getX()
          Returns sprite x coordinate.
 double getY()
          Returns sprite y coordinate.
 boolean isActive()
          Returns active state of this sprite.
 boolean isImmutable()
          Returns whether this sprite is immutable or not.
 boolean isOnScreen()
          Returns whether the screen is still on background screen area.
 boolean isOnScreen(int leftOffset, int topOffset, int rightOffset, int bottomOffset)
          Returns whether the screen is still on background screen area in specified offset.
 void move(double dx, double dy)
          Moves this sprite as far as delta x (dx) and delta y (dy).
 boolean moveTo(long elapsedTime, double xs, double ys, double speed)
          Attempts to move this sprite to specified xs, ys location, if the sprite is right on specified location, this method will return true.
 void moveX(double dx)
          Moves sprite x coordinate as far as delta x (dx).
 void moveY(double dy)
          Moves sprite y coordinate as far as delta y (dy).
 void render(Graphics2D g)
          Renders this sprite to specified graphics context.
 void render(Graphics2D g, int x, int y)
          Renders sprite image to specified graphics context and specified location.
 void setActive(boolean b)
          Sets active state of this sprite, only active sprite will be updated and rendered and check for collision.
 void setBackground(Background backgr)
          Associates specified background with this sprite.
 void setDataID(Object dataID)
          Sets sprite data ID, ID is used to mark a sprite from other sprite.
 void setHorizontalSpeed(double vx)
          Sets horizontal speed of the sprite, the speed is based on actual time in milliseconds, 1 means the sprite is moving as far as 1000 (1x1000ms) pixels in a second to the right, while negative value (-1) means the sprite is moving to the left.
 void setID(int id)
          Sets sprite ID, ID is used to mark a sprite from other sprite.
 void setImage(BufferedImage image)
          Sets specified image as this sprite image.
 void setImmutable(boolean b)
          Sets immutable state of this sprite, immutable sprite means the sprite won't be removed from its group even though the sprite is not active.
 void setLayer(int i)
          Sets the layer of this sprite.
 void setLocation(double xs, double ys)
          Sets this sprite coordinate to specified location on the background.
 void setMovement(double speed, double angleDir)
          Moves sprite with specified angle, and speed.
 void setSpeed(double vx, double vy)
          Sets the speed of this sprite, the speed is based on actual time in milliseconds, 1 means the sprite is moving as far as 1000 (1x1000ms) pixels in a second.
 void setVerticalSpeed(double vy)
          Sets vertical speed of the sprite, the speed is based on actual time in milliseconds, 1 means the sprite is moving as far as 1000 (1x1000ms) pixels in a second to the bottom, while negative value (-1) means the sprite is moving to the top.
 void setX(double xs)
          Sets sprite x coordinate.
 void setY(double ys)
          Sets sprite y coordinate.
 void update(long elapsedTime)
          Updates this sprite.
protected  void updateMovement(long elapsedTime)
          Updates sprite movement.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

width

protected int width
The width of this sprite.


height

protected int height
The height of this sprite.

Constructor Detail

Sprite

public Sprite(BufferedImage image,
              double x,
              double y)
Creates new Sprite with specified image and location.


Sprite

public Sprite(BufferedImage image)
Creates new Sprite with specified image and located at (0, 0).

See Also:
setLocation(double, double)

Sprite

public Sprite(double x,
              double y)
Creates new Sprite with specified position and null image.

Note: the image must be set before rendering by using setImage(BufferedImage).

See Also:
setImage(BufferedImage)

Sprite

public Sprite()
Creates new Sprite with null image and located at (0, 0).

Note: the image must be set before rendering by using setImage(BufferedImage).

See Also:
setImage(BufferedImage), setLocation(double, double)
Method Detail

setBackground

public void setBackground(Background backgr)
Associates specified background with this sprite.


getBackground

public Background getBackground()
Returns the background where this sprite lived.


getImage

public BufferedImage getImage()
Returns the image of this sprite.


setImage

public void setImage(BufferedImage image)
Sets specified image as this sprite image.


getWidth

public int getWidth()
Returns the width of this sprite.


getHeight

public int getHeight()
Returns the height of this sprite.


moveTo

public boolean moveTo(long elapsedTime,
                      double xs,
                      double ys,
                      double speed)
Attempts to move this sprite to specified xs, ys location, if the sprite is right on specified location, this method will return true.

For example :

    Sprite s;

    public void update(long elapsedTime) {
       // move sprite to 100, 100 with speed 0.1 pixel in a millisecond
       if (s.moveTo(elapsedTime, 100, 100, 0.1) {
          // sprite has arrived to 100, 100
       }
    }
 


setLocation

public void setLocation(double xs,
                        double ys)
Sets this sprite coordinate to specified location on the background.


move

public void move(double dx,
                 double dy)
Moves this sprite as far as delta x (dx) and delta y (dy).


moveX

public void moveX(double dx)
Moves sprite x coordinate as far as delta x (dx).


moveY

public void moveY(double dy)
Moves sprite y coordinate as far as delta y (dy).


setX

public void setX(double xs)
Sets sprite x coordinate.


setY

public void setY(double ys)
Sets sprite y coordinate.


forceX

public void forceX(double xs)
Forces sprite x position to specified coordinate.

The difference between setX(double) with this method :
setX(double) changes the sprite old position (oldX = xs), while using forceX(double) the old position is n ot changed.

This method is used on collision check to move the sprite, but still keep the sprite old position value.


forceY

public void forceY(double ys)
Forces sprite y position to specified coordinate.

The difference between setY(double) with this method :
setY(double) changes the sprite old position (oldY = ys), while using forceY(double) the old position is n ot changed.

This method is used on collision check to move the sprite, but still keep the sprite old position value.


getX

public double getX()
Returns sprite x coordinate.


getY

public double getY()
Returns sprite y coordinate.


getOldX

public double getOldX()
Returns sprite x coordinate before the sprite moving to the current position.


getOldY

public double getOldY()
Returns sprite y coordinate before the sprite moving to the current position.


setSpeed

public void setSpeed(double vx,
                     double vy)
Sets the speed of this sprite, the speed is based on actual time in milliseconds, 1 means the sprite is moving as far as 1000 (1x1000ms) pixels in a second. Negative value (-1) means the sprite moving backward.


setHorizontalSpeed

public void setHorizontalSpeed(double vx)
Sets horizontal speed of the sprite, the speed is based on actual time in milliseconds, 1 means the sprite is moving as far as 1000 (1x1000ms) pixels in a second to the right, while negative value (-1) means the sprite is moving to the left.


setVerticalSpeed

public void setVerticalSpeed(double vy)
Sets vertical speed of the sprite, the speed is based on actual time in milliseconds, 1 means the sprite is moving as far as 1000 (1x1000ms) pixels in a second to the bottom, while negative value (-1) means the sprite is moving to the top.


setMovement

public void setMovement(double speed,
                        double angleDir)
Moves sprite with specified angle, and speed.

The angle is as followed:

   0   : moving to top (12 o'clock)
   90  : moving to right (3 o'clock)
   180 : moving to bottom (6 o'clock)
   270 : moving to left (9 o'clock)
 


addHorizontalSpeed

public void addHorizontalSpeed(long elapsedTime,
                               double accel,
                               double maxSpeed)
Accelerates sprite horizontal speed by accel and limit the speed to maxSpeed.

This is used to create momentum speed (slowly increase/decrease the sprite speed).

For example :

    Sprite s;

    public void update(long elapsedTime) {
       // accelerate sprite speed by 0.002
       // and limit the maximum speed to 4

       // moving right
       s.addHorizontalSpeed(elapsedTime, 0.002, 4);

       // moving left
       s.addHorizontalSpeed(elapsedTime, -0.002, -4);

       // momentum stop
       s.addHorizontalSpeed(elapsedTime,
                            (s.getHorizontalSpeed() > 0) ? -0.002 : 0.002,
                            0);
    }
 


addVerticalSpeed

public void addVerticalSpeed(long elapsedTime,
                             double accel,
                             double maxSpeed)
Accelerates sprite vertical speed by accel and limit the speed to maxSpeed.

This is used to create momentum speed (slowly increase/decrease the sprite speed).

For example :

    Sprite s;

    public void update(long elapsedTime) {
       // accelerate sprite speed by 0.002
       // and limit the maximum speed to 4

       // moving down
       s.addVerticalSpeed(elapsedTime, 0.002, 4);

       // moving up
       s.addVerticalSpeed(elapsedTime, -0.002, -4);

       // momentum stop
       s.addVerticalSpeed(elapsedTime,
                          (s.getVerticalSpeed() > 0) ? -0.002 : 0.002,
                          0);
    }
 


getHorizontalSpeed

public double getHorizontalSpeed()
Returns horizontal speed of the sprite.

Positive means the sprite is moving to right, and negative means the sprite is moving to left.


getVerticalSpeed

public double getVerticalSpeed()
Returns vertical speed of the sprite.

Positive means the sprite is moving to bottom, and negative means the sprite is moving to top.


getScreenX

public double getScreenX()
Returns sprite x coordinate relative to screen area.


getScreenY

public double getScreenY()
Returns sprite y coordinate relative to screen area.


isOnScreen

public boolean isOnScreen(int leftOffset,
                          int topOffset,
                          int rightOffset,
                          int bottomOffset)
Returns whether the screen is still on background screen area in specified offset.


isOnScreen

public boolean isOnScreen()
Returns whether the screen is still on background screen area.


update

public void update(long elapsedTime)
Updates this sprite.


updateMovement

protected void updateMovement(long elapsedTime)
Updates sprite movement.


render

public void render(Graphics2D g)
Renders this sprite to specified graphics context.

Parameters:
g - graphics context

render

public void render(Graphics2D g,
                   int x,
                   int y)
Renders sprite image to specified graphics context and specified location.

Parameters:
g - graphics context
x - screen x-coordinate
y - screen y-coordinate

getID

public int getID()
Returns sprite ID, ID is used to mark a sprite from other sprite.


setID

public void setID(int id)
Sets sprite ID, ID is used to mark a sprite from other sprite.


getDataID

public Object getDataID()
Returns sprite data ID, ID is used to mark a sprite from other sprite.


setDataID

public void setDataID(Object dataID)
Sets sprite data ID, ID is used to mark a sprite from other sprite.


getLayer

public int getLayer()
Returns the layer of this sprite.

See Also:
setLayer(int)

setLayer

public void setLayer(int i)
Sets the layer of this sprite.

Layer is used for z-order rendering. Use this along with PlayField.setComparator(Comparator) or SpriteGroup.setComparator(Comparator) for that purpose.

See Also:
getLayer()

isActive

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


setActive

public void setActive(boolean b)
Sets active state of this sprite, only active sprite will be updated and rendered and check for collision.

Inactive sprite is same as dead sprite, it won't be updated nor rendered, and only wait to be disposed (if the sprite is not immutable).

The proper way to remove a sprite from the game, is by setting sprite active state to false (Sprite.setActive(false)).

See Also:
setImmutable(boolean)

isImmutable

public boolean isImmutable()
Returns whether this sprite is immutable or not.


setImmutable

public void setImmutable(boolean b)
Sets immutable state of this sprite, immutable sprite means the sprite won't be removed from its group even though the sprite is not active.

This state is used for optimization by reusing inactive sprite rather than making new sprite each time.

Usually used for many, small, short live, and frequently used sprites such as projectile in shooter game. Thus rather than making a new sprite for every projectile that can cause performance degrade, the inactive projectiles can be reuse again and again.

WARNING: Immutable sprite won't be disposed by Java garbage collector until the sprite is manually removed from its group using SpriteGroup.removeImmutableSprites().

See Also:
SpriteGroup.getInactiveSprite(), SpriteGroup.removeImmutableSprites(), setActive(boolean)

getDistance

public double getDistance(Sprite other)
Returns the distance of this sprite from the specified sprite.

Used this method to check whether the specified sprite is in this sprite range area or not.

This method can be used for :


GTGE API

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