Module | Rubygame::Sprites::Sprite
In: | lib/rubygame/sprite.rb

The Sprite mix-in module (not to be confused with its parent module, Sprites) can be used to extend a class or object to behave as a sprite. Specifically, a sprite can:

- draw (blit) itself onto a Surface in its proper position
- detect bounding-box collision with Groups (collide_group) and/or other sprites (collide_sprite).
- update its own state based on arbitrary rules.

A Sprite is, fundamentally, a Surface with an associated Rect which defines the position of that Surface on the Screen. Additionally, sprites can have some behavior associated with them via the update method, including movement and collision detection; because of this, sprites can be the foundation of most on-screen objects, such as characters, items, missiles, and even user-interface elements.

In order to work properly as a Sprite, the extended object or class must have two methods defined (by default, these are defined as accessors to attributes of the same names):

image: | return a Surface with the sprite‘s image.
rect: | returns a Rect with the position and dimensions of the sprite.

Normally, the value returned by rect is used to draw the sprite onto a Surface as well as to detect collision between sprites. However, if @col_rect will be used for collision detection instead, if it is defined. See also col_rect.

Additionally, if you are extending an already-existing instance (rather than a class), that instance must have an attribute @groups, which is an Array containing all Groups to which the sprite belongs.

### Methods

add alive? col_rect collide collide_group collide_sprite? draw kill new remove undraw update

### Attributes

col_rect | [W] | Set an alternative Rect to use for collision detection. If undefined or set to nil, the Sprite‘s rect is used instead.
depth | [RW] |
groups | [R] |
image | [RW] |
rect | [RW] |

### Public Class methods

new()

Initialize the Sprite, defining @groups and @depth.

### Public Instance methods

add(*groups)

Add the Sprite to each given Group.

alive? → true or false

True if the Sprite belongs to at least one Group.

col_rect → Rect

Returns @col_rect if it is defined, otherwise calls rect. This method is used by collide, collide_group, and collide_sprite to get the bounding box for collision detection.

collide(other) → Array

Check collision between the caller and a Group or another Sprite. See also collide_group and collide_sprite. This method uses the value of col_rect as the bounding box when detecting collision.

If `other` is a Group, returns an Array of every Sprite in that Group that collides with the caller. If `other` is a Sprite, returns an Array containing `other` if it collides with the caller. Otherwise, returns an empty Array.

collide_group(group) → Array

Check collision between the caller and all members of a Group. This method uses the value of col_rect as the bounding box when detecting collision.

Returns an Array of every Sprite in `group` that collides with the caller. If none collide, returns an empty Array.

collide_sprite?(sprite) → true or false or nil

Check collision between the caller and another Sprite. This method uses the value of col_rect as the bounding box when detecting collision. Returns true if `sprite` collides with the caller, false if they do not, or nil if `sprite` does not respond to either :col_rect or :rect (meaning it was not possible to detect collision).

draw(surface) → Rect

Blit the Surface returned by image onto `surface` at the position given by the Rect returned by rect. Returns a Rect representing the area of `surface` which was affected by the draw.

kill()

Remove the caller from every Group that it belongs to.

remove(*groups)

Remove the caller from each given Group.

undraw(surface, background) → Rect

‘Erase’ the sprite from `surface` by drawing over it with part of `background`. For best results, `background` should be the same size as `surface`.

Returns a Rect representing the area of `surface` which was affected.

update( *args )

This method is meant to be overwritten by Sprite-based classes to define meaningful behavior. It can take any number of arguments you want, be called however often you want, and do whatever you want. It may return something, but Group#update will not (by default) use, or even collect, return values from this method.

An example definition might take the amount of time that has passed since the last update; the Sprite could then update its position accordingly. Game logic, collision detection, and animation would also fit in here, if appropriate to your class.

[Validate]